0-introduction

主题：构建、定制或适应 AI 辅助的开发环境

核心是利用各种 AI 工具来辅助软件工程。
通俗说法：“Vibe Coding”（氛围编程）。

Vibe Coding 体验

这个词由 OpenAI 的一位创始人提出，描述了一种进入“心流”状态的编程体验。
AI 工具能快速生成大量代码，让人感觉自己像个巫师。
痛点：当代码量增长到超出个人通常的理解范围时，会感到困惑，需要花很长时间去阅读和理解 AI 生成的代码。这是一种普遍的体验。

本次演讲的核心议题

工具介绍：有哪些 AI 工具？如何使用它们？
克服错失恐惧：AI 的发展列车并未离开车站，现在开始为时不晚。
管理复杂性：AI 能快速生成大量代码，但这不总是好事（就像接手一个庞大的遗留代码库）。如何驾驭这种复杂性是关键。

揭开 AI 的神秘面紗

AI 模型本质上是统计模型，并非魔法。
理解其基本原理有助于我们更好地利用它、设置防护措施、管理复杂性。

核心论点：回归基础

许多存在了几十年的行业最佳实践，在 AI 时代变得异常有效。
- Git 纪律：良好的 commit 习惯。
- 测试驱动开发 (TDD)：先写测试再写代码。
这些原则在与 AI 协作时能发挥重要作用。

软件开发的本质演变

软件开发始终是用类似人类的语言，让只懂开关和电流的计算机执行任务。
从打孔卡、汇编到现代语言，抽象层次不断提升。
现代开发者（如 JavaScript 工程师）已无需手动管理内存。
抽象层次的提升带来了更大的杠杆效应，AI 是最新的杠杆工具。

目标：获得杠杆，而非降低效率

关键在于理解基本概念，将“魔法”变为可控的“炼金术”。
学会利用 AI 工具获得杠杆，避免在看似高效的忙碌中实际降低了开发速度。

AI 对职业发展的影响

一个普遍现象：资深工程师写的代码越来越少，但薪水越来越高。这说明系统思维和高层架构是更重要、更困难的部分。
初级工程师通常难以接触到大型、混乱的遗留代码库来锻炼系统思维。
好消息是：现在可以利用 AI 快速生成一个庞大且混乱的项目，然后自己学习如何导航、重构和理解它，从而获得宝贵的经验。

1-ai-tools-overview

本次课程重点关注的两个工具

Cursor：一个 AI 原生的代码编辑器。
Claude Code：一个在终端中运行的 AI 编程助手。

工具范式对比

Cursor

外观与体验：是 VS Code 的一个分支（fork），UI 和操作非常相似。
核心优势：提供沉浸式体验，AI 功能直接集成在编辑器中。
交互方式：
- 侧边栏提供类似 ChatGPT 的聊天窗口。
- 可以在代码中直接看到 AI 建议的修改，并选择接受。
- 可以高亮代码块，对其进行提问或要求修改。
适用场景：当你正盯着一个特定函数需要重构时，Cursor 非常好用。

Claude Code

环境：一个终端应用程序（Terminal App），深受 Vim 用户喜爱。
交互方式：在终端中与 AI 代理进行交互，AI 不会与你同时直接操作代码文件。
优势：不受限于当前编辑器视图，可以处理更宏观的任务。
适用场景：当需要对整个代码库中某个函数的所有实例进行参数修改时，Claude Code 更适合。

其他范式：OpenAI's Codex

工作方式：指向一个 Git 仓库，通过聊天告诉它你的需求。
流程：AI 会提出一个计划，经你批准后，它会自动创建一个 Pull Request (PR)。
交互方式：转变为传统的 Code Review 模式，你在 PR 上进行评论和反馈。
优势：
- 非常强大，尤其适合异步工作。
- 不仅能写代码，还能帮助理解大型代码库的架构。
- 可以远程启动任务（如在手机上），第二天早上再来审查结果。

“我应该用哪一个？”

作者同时使用 Cursor 和 Claude Code，因为 VS Code 内置了终端。
不同的工具适用于不同的任务和工作流程。

工具的定价和可用性

Cursor

提供 14 天的 Pro Plan (专业版) 免费试用。
试用结束后降级为 Hobby Plan (兴趣版)，功能受限但大部分核心功能可用。
更高级的计划提供企业级功能，如 SSO、SAML 和企业级隐私保护。

Claude Code

目前没有免费计划。

替代方案

如果想体验终端驱动的 AI 编程，可以使用 Google 的 Gemini CLI。
只要有 Google 账户，在一定限额内免费，功能与 Claude Code 类似，是很好的替代品。

2-context-window-rules

核心概念：上下文窗口 (Context Window)

这是与大语言模型（如 ChatGPT, Gemini, Claude）交互时最核心的概念。
定义：模型在一次交互中能够“记住”和处理的信息量是有限的。这个限制就是上下文窗口。
现状：窗口大小在不断增长（如 Gemini 的 200 万 token），但并非所有模型都如此，且更大的模型通常更慢、更贵。
类比：就像人类大脑一样，同时处理太多信息会导致混乱和效率低下。

最重要的主题：管理上下文窗口

目标：确保在有限的窗口内，包含了最准确、最相关的信息。
这是获得高质量 AI 输出结果、避免 AI “胡言乱语”的关键。

如何有效管理上下文窗口

1. 分解问题

将复杂任务分解成更小的、可管理的步骤。

2. 明确计划

“编程数周，可省规划数小时”。清晰地写下你的计划和意图。
坏例子：“帮我做用户认证”。
好例子：“使用 Auth0 的 JavaScript SDK，实现一个 React Hook，该 Hook 用于检查用户认证状态，并集成 Google OAuth 登录。”
架构决策记录 (ADR) 等文档对 AI 非常有效。

3. 管理聊天历史

AI 聊天是无状态的。每次发送新消息时，整个聊天历史都会被重新发送给模型。
技巧：及时清理聊天记录，或为新任务开启新的聊天会话。

4. 分阶段工作：构思 vs. 执行

构思/头脑风暴阶段：
- 利用 AI 进行“橡皮鸭调试”，让它对你的想法提出反馈。
- 可以问：“我写的这段代码，遗漏了什么？”
- 可以利用不同模型的特点进行交叉验证：
  - 用 ChatGPT-o3 制定计划。
  - 用 Google Gemini 找这个计划的漏洞。
  - 将计划和漏洞反馈给 Claude，生成最终方案。
执行阶段：
- 在明确计划后，再让 AI 开始编写代码。
- 不要在构建的同时构思，这样会导致结果混乱。

保持代码库的整洁

定期审查：每天开始或结束时，审查 AI 生成的代码。
清理垃圾文件：AI 工具（尤其是 Claude Code）可能会生成临时或重复的文件（如 v2.js），需要手动清理。
避免 AI 学习错误模式：AI 会通过向量数据库索引你的代码库。如果不清理废弃的、过时的代码，AI 会学习这些坏模式，并在新代码中重现它们。
保持规则一致：确保你在不同工具（如 Cursor 和 Claude）中设置的规则是一致的，避免冲突。

心态调整

AI 是工具，不是魔法。当它表现不佳时，通常是我们使用不当，就像我们写 TypeScript/JavaScript 代码出错一样，问题很可能出在自己身上。

3-cursor-ai-models-overview

Cursor 的三种半主要模式

1. 内联编辑 (Inline Edit)

触发方式：Cmd/Ctrl + K。
功能：在代码上方弹出一个小窗口，可以对高亮选中的代码或光标所在位置进行快速生成或修改。

2. 聊天 (Chat)

触发方式：Cmd/Ctrl + L。
功能：打开侧边栏的聊天窗口，可以与 AI 讨论整个代码库，因为它拥有代码库的上下文。

3. 代理模式 (Agent Mode)

功能：在聊天侧边栏中激活，让 AI 代理直接对你的代码库执行操作和修改。

3.5. Tab 自动完成

功能：类似 GitHub Copilot，当你开始重命名变量或修改函数参数时，它会智能地以灰色文本提示后续的、相关的修改。不仅限于当前位置，还能帮你跳转到文件中其他需要同步修改的地方。
价值：极大减少了繁琐的、重复性的查找和修改工作。

Cursor 如何理解你的代码（启发式方法）

它会读取当前打开的文件。
它会关注最近查看过的文件列表。
它会尝试搜索活跃的 Linter、编译器和最近的编辑历史。
重要限制：
- 对于一个文件，它通常只读取前 250 行。
- 在搜索时，可能只看文件的前 100 行。
启示：这鼓励我们保持文件短小精悍，或者采取措施确保重要信息在前部。

如何更精确地提供上下文

不要完全依赖 Cursor 的自动启发式方法。
主动提供：
- @ 符号：明确告诉它需要查看哪些文件、文件夹或符号（函数/变量名）。
- Docs：提供文档的 URL，让它在执行任务前先阅读相关文档。
- Web Search：让它搜索最新的库（如 Svelte, Zod, React）信息。

模型选择与权衡

通用原则：模型越大，通常能力越强，但速度越慢，成本越高。

Anthropic (Claude) 系列

Sonnet：日常主力模型，是成本和性能的“甜蜜点”，适合大多数编码任务。
Opus：最强大的模型，成本是 Sonnet 的 4-6 倍。
Haiku：更小、更快的模型。

Google (Gemini) 系列

Flash：速度快。
Pro：具有“思考”步骤，在回答前会先规划。
优势：拥有巨大的上下文窗口（200 万 Token），非常适合代码审查、项目规划和深入研究，能理解整个代码库。

OpenAI (GPT) 系列

优势：主要用于头脑风暴和事实性问题，幻觉（Hallucination）较少。
劣势：在编写代码方面表现稍逊，有时会在复杂任务中途放弃。

自托管模型 (Self-hosted)

工具：可以使用 LM Studio 等应用在本地下载并运行模型（如从 Hugging Face）。
优势：保护隐私和代码安全，不受网络限制。
劣势：对硬件要求极高，个人电脑通常难以胜任。

核心建议

一个拥有良好、详细计划的小模型，其表现会优于一个得到模糊指令的大模型。

4-cursor-tour-settings

启动与界面

可以通过命令行 cursor . 在当前目录打开，或通过图形界面打开项目。
界面与 VS Code 高度相似，本质上是 VS Code 的一个分支。

侧边栏核心功能导览

1. 聊天窗口 (Chat Window)

可以向其提问，例如“这个代码库的技术栈是什么？”，它会分析并回答。
操作时最好盯着它的输出，以便在它走向错误方向时及时停止，节省成本或 API 调用次数。

2. 添加上下文 (Add Context)

推荐方式：使用 @ 符号直接引用文件或文件夹，例如 @application.tsx。这比点击按钮更高效。
引用的文件不仅会被读取，其导入的依赖也可以被追踪。
侧边栏会显示当前上下文窗口的使用情况，防止信息过载。

3. 模型切换 (Model Toggle)

Auto (自动)：让 Cursor 自行决定使用哪个模型。
手动选择：可以强制指定使用特定模型，如 Claude Sonnet, GPT-4 等。
Max Mode：使用最强大、最昂贵的模型来处理问题。

4. 模式切换：Agent vs. Ask

Agent (代理模式)：AI 会直接对代码库进行修改。这是“搞事情”的模式。
Ask (询问模式)：AI 只会回答问题和提供建议，不会修改任何文件。适合头脑风暴或在 Agent 模式运行时进行并行规划。
并行工作：可以开一个 Agent 执行任务，同时在另一个窗口用 Ask 模式规划下一步或询问代码库问题。

重要设置项 (Cursor Settings)

可以从现有的 VS Code 中导入所有配置和插件。

Chat (聊天设置)

Default Start Mode: 设置默认启动是 Ask 还是 Agent 模式。
Auto Clear Chat: 自动清理长期未活动的聊天，以管理上下文。
Show To-Do List: 强烈建议开启，在 Agent 执行前会展示一个计划清单，让你确认。

Context (上下文设置)

Dot File Protection: 默认开启，并强烈建议保持。防止 AI 修改 .gitignore、.env 等重要的点文件。

Models (模型设置)

可以自定义下拉列表中显示哪些模型。
自带 API 密钥：可以填入自己的 OpenAI、Anthropic 等平台的 API 密钥。这样会使用你自己的账户进行计费，而不是通过 Cursor 计费。这对于公司报销或使用内部密钥非常有用。

5-using-cursor-ai-inline-edits

内联编辑 (Inline Edits)

触发：Cmd/Ctrl + K，在高亮的代码上进行操作。
特点：
- 用于进行精准、小范围的“外科手术式”修改。
- 通常会使用一个更轻量、响应更快的模型。
- 风险较低，因为每次只处理一小块代码，审查起来很容易。

Tab 自动完成功能

工作方式：当你进行重复性修改时，AI 会智能预测你接下来的操作。
示例：在一个函数中将参数 a 和 b 改为 x和 y 后，当你移动到另一个类似的函数时，它会自动提示你进行同样的修改。
价值：极大提升了重构和代码整理的效率。

表达意图与审查

交互：选中代码，用自然语言描述你的需求（例如，“将这些函数改为使用 export const 的形式”）。
审查界面：AI 会以 diff（差异对比）的形式展示建议的修改。你可以选择全部接受、部分接受或全部拒绝。
实时预览 (Live Preview)：最强大的功能之一。当 AI 提出修改建议时，编辑器会实时运行这些建议的代码。如果你的项目配置了热模块重载（HMR），你可以立即在运行的应用中看到修改后的效果，判断其是否破坏了功能，然后再决定是否接受。

实用的单次提示技巧 (One-Shot Prompting)

`mirror` (镜像/模仿)

用途：基于一个已有的代码块，创建另一个类似但有细微变化的代码块。
示例：mirror addAction as subtractAction。AI 会分析 addAction 的结构，并为你创建一个功能相反的 subtractAction。

`I need a function that...` (我需要一个函数...)

用途：基于一句简单的描述，生成一个完整的函数。
上下文感知：它会参考当前文件中的其他代码，使生成的函数风格和逻辑与现有代码保持一致。

“跟随问题”工作流 (Follow the Problem Workflow)

痛点：处理 TypeScript 报错。
Cursor 的解决方案：当代码中出现 TypeScript 错误提示时，弹窗上会多出一个特殊的按钮。
一键修复：点击该按钮，Cursor 会自动将错误信息和相关的代码片段发送到聊天窗口，并生成一个修复问题的提示。AI 会解释错误原因，并直接给出简洁的修复方案，你只需审查并接受即可。这是一个极其高效的问题解决方式。

6-using-cursor-ai-agent

代理模式 (Agent Mode)

用于执行更大型、更复杂的任务，通常会涉及创建或修改多个文件。

提示词的特异性至关重要

糟糕的提示：“帮我建一个计算器。” (结果不可预测)
优秀的提示：“在 calculator.tsx 文件中，构建一个计算器组件。然后将这个组件引入并使用在 @application.tsx 中。计算逻辑请使用 useReducer 管理状态。将实际的数学运算逻辑抽离到一个单独的工具函数文件中，以便进行单元测试。确保组件是无障碍的 (accessible) 并且使用 Tailwind CSS 进行样式设计。”
结论：你提供的指令越具体、越清晰，得到的结果就越符合预期。

标准工作流程

清理上下文：为每个新任务开启一个全新的聊天会话（快捷键 Cmd/Ctrl + N），避免旧的上下文干扰。
审查计划：启动代理后，它首先会进行思考，并生成一个行动计划（To-Do List）。在它开始编码前，务必仔细审查这个计划，确保它理解了你的意图。
执行与监控：代理会按照计划清单逐步执行任务，创建、修改文件。

代码审查是你的责任

切勿盲目接受：不要直接点击 "Keep All"（全部保留）按钮。
使用审查工具：
- 清单 (Manifest)：Cursor 会提供一个所有被修改文件的清单，类似于 git diff。
- 逐一审查：你可以查看每个文件的 diff，在文件内部的不同修改点之间跳转，也可以在不同文件之间切换。
- 直接编辑：在 diff 视图中，你可以直接对 AI 建议的代码进行微调，然后再接受。

处理错误与卡顿

紧急停止：如果发现代理陷入了循环（例如，在一个失败的测试上反复尝试）或走向了错误的方向，立即点击 "Stop" 按钮。
代理的限制：代理有执行次数上限（如 25 次工具调用），达到上限后会自动停止。
人工干预：当 AI 卡住时，需要你介入，分析问题并给出更明确的指导。

代理模式的常见问题

创建冗余文件：有时它会创建新文件（如 calculator-v2.tsx）而不是修改原来的文件。
画蛇添足：可能会添加你并未要求的功能（例如，一个额外的 Banner）。
始终记住：你仍然是主导者，最终清理和整理代码的责任在你。

7-cursor-ai-rules

什么是 Cursor 规则 (Cursor Rules)?

定义：它们是持久化的指令集，用来告诉 AI 在这个项目中应该遵循的编码规范和偏好。
目的：避免在每次提问时都重复输入相同的要求，例如“请使用 BUN 而不是 NPM”、“确保组件是无障碍的”、“使用 Kebab-case 文件命名法”。
特点：
- 这是一个“活的文档”，当 AI 做出你不喜欢的行为时，你就应该去更新和完善规则。
- 规则会占用宝贵的上下文窗口，因此需要有效管理。

规则的类型

1. 项目级规则 (Project-level rules)

位置：存储在项目根目录下的 .cursor/rules 文件夹中，以 .mdc 文件形式存在。
优势：可以被提交到 Git，与团队成员共享，确保整个团队的 AI 协作风格一致。这是最推荐的方式。

2. 用户级规则 (User-level rules)

位置：存储在用户配置中，对所有项目生效。
劣势：不方便针对不同技术栈的项目做调整（例如一个项目用 NPM，另一个用 BUN），且无法团队共享。

规则的应用方式 (Rule Attachment)

`auto-attached` (自动附加)

最佳且最常用的方式。
机制：只有当 AI 正在处理的文件路径匹配你设置的 glob 模式时，这个规则才会被加载到上下文中。
示例：可以设置一个 React 相关的规则，让它只在处理 .tsx 文件时生效；设置一个 TypeScript 规则，在处理 .ts 和 .tsx 文件时生效。
高级用法：可以创建自定义文件扩展名（如 .tool.ts）来触发特定的规则集。

`agent-requested` (代理请求)

不推荐。AI 根据对规则的描述自行判断是否应用该规则，非常不可靠。

`manually` (手动引用)

不推荐。你必须在每次提问时使用 @ 手动引用规则，非常容易忘记。

如何编写高质量的规则

具体，而非模糊：
- 好：“为所有导出的函数添加 JSDoc 注释。”
- 差：“给代码写文档。”
- 好：“对于函数式组件，使用 React.FC 类型。”
- 差：“使用 TypeScript。”
提供架构上下文：
- 明确指出项目中使用的关键库和模式，例如“进行数据获取时，请使用 React Query 的 useQuery Hook”。
保持简洁：
- 规则虽然要具体，但也要避免过于冗长，以免过度消耗上下文窗口。在具体性和简洁性之间找到平衡。

资源与参考

在 GitHub 上搜索 awesome-cursor-rules 可以找到很多优秀的规则范例。
网站 cursor-directory.com 也提供了可搜索的规则库。
注意：避免使用旧的、单一的 .cursorrules 文件格式，因为它不利于上下文管理。应使用 .cursor/rules 目录下的多个分类文件。

8-setup-cursor-rules

创建 Cursor 规则的方法

可以直接在项目根目录下创建 .cursor/rules 文件夹和规则文件。
可以通过命令面板（Command Palette）中的 "New cursor rules" 来创建。

规则文件的基本结构

本质上是一个 Markdown 文件，你可以在其中用自然语言表达你的意图和要求。

一个巧妙的验证技巧

在规则文件中加入一条指令，要求 AI 在读取该文件后，在聊天中打印出特定的三个表情符号（emojis）。
如果 AI 没有打印这些表情，就说明它没有成功加载和读取这条规则。
这是一种“既天才又荒谬”但非常有效的方法来确认规则是否生效。

配置规则的应用范围

推荐方式：Apply to specific files (应用到特定文件)，即 auto-attached。
通过文件 glob 模式来精确控制规则的生效范围，例如 */*.tsx 表示所有 TSX 文件。
可以为项目的不同部分设置不同的规则：
- 为 src/components 目录下的组件设置一套规则。
- 为所有 React 组件设置另一套规则。
可以利用自定义文件扩展名（如 .tool.ts）来触发特定的规则集。

一致性的重要性

为 AI 提供上下文线索：代码库风格的一致性对于 LLM 来说是非常重要的模式和线索，不一致会增加系统的混乱和熵。
对 AI 可以更严格：与人类团队协作时，你可能需要容忍不同的编码风格（如箭头函数 vs. function 表达式）。但对于 AI，你可以执行最严格、最符合你个人偏好的标准，这反而会带来更好的结果。

具体规则示例

TypeScript 相关

永远不要使用 @ts-ignore 或 @ts-expect-error 而不加解释性注释。
为复杂的类型使用 JSDoc 注释。
强制不使用 enums（个人偏好）。

与工作流集成

结合 pre-commit hooks，可以告诉 AI：“除非你能成功创建一个 commit，否则你的任务就不算完成。”
这会迫使 AI 遵守 ESLint、TypeScript 检查等所有提交前的验证。
可以设置规则来阻止 AI 使用 git commit --no-verify 这样的命令绕过检查。

代码风格

强制使用特定的 import 顺序。
强制使用 Zod 进行类型验证。

使用“反向提示” (Negative Prompts)

明确指出不希望它做什么（anti-patterns），这是一种非常有效的制衡手段。

与 AI 的互动

当 AI 做出你不希望的行为时，养成问“你为什么这么做？”的习惯，这有助于你理解它的“思考”过程并反向工程其逻辑，从而优化你的规则。

9-notepads

什么是 Notepad？

Notepad 是 Cursor 的一个内置功能，是一个专用的笔记区域。

Notepad vs. Markdown 文件

Notepad 的特点

Cursor 独有：无法在其他工具（如 Claude Code, OpenAI Codex）中使用。
不在文件系统中：不会出现在你的项目目录里。
不存入版本控制 (Git)：内容是临时的，仅属于你的本地开发环境。
优点：适合存放个人、临时的笔记，不会因为频繁提交 .md 文件而打扰团队成员。

Markdown 文件的特点

通用：任何工具都可以读取。
在文件系统中：可以被版本控制，方便团队共享。
缺点：对于一些临时性的、个人化的计划或提示，提交到 Git 中可能会显得杂乱。

核心用途与最佳实践

1. 管理上下文窗口：

规则 (Rules) 是“永远在线”的，只要触发条件就会被加载。
Notepad 是“按需加载”的，只在你需要时才手动将其引入上下文，这有助于节省宝贵的 token。

2. 创建可复用的提示集：

这是 Notepad 最强大的功能之一。你可以创建一个 Notepad，在其中预先定义好一个复杂任务所需的上下文。
使用 @ 符号在 Notepad 中引用多个文件，例如 @reducer.ts, @context.ts, @product_requirements.md。
之后，在聊天时只需引用这个 Notepad 的名字（如 @calculator_notes），就可以一次性将所有相关文件加载到上下文中，极大提高效率。

示例

你可以创建一个名为 format 的 Notepad，内容是修复项目中所有 lint 错误和 TypeScript 类型错误的指令。
每当你想执行这个操作时，只需在聊天中输入 @format 即可。这能将一个复杂的、重复性的任务简化为一个简单的命令。

10-background-agents

什么是背景代理 (Background Agents)?

它们是异步的、在远程环境中运行的 Cursor 代理，而不是在你的本地机器上。

先决条件

你的代码必须托管在一个远程仓库中，通常是 GitHub，这样代理才能访问和修改它。

工作流程

代理会克隆你的仓库。
在一个独立的、新的分支上进行工作。
工作完成后，它会生成一个 Pull Request (PR) 供你审查。
你可以在一个 Web 应用（仪表盘）上随时查看它的进展。

这个工作流与 OpenAI's Codex 非常相似。

并行工作的优势

由于每个代理都在自己独立的环境和分支中工作，你可以轻松地同时启动多个代理来处理不同的任务，而不会像在本地同一个分支上那样发生冲突。

主要用例 (Use Cases)

1. 代码库分析与文档生成：

个人反思：当你在“氛围编程 (vibe coding)”中快速生成了大量代码后，可以用背景代理来帮助你分析这些代码，理解其引入的抽象和结构，并生成文档。
学习工具：这是一个极其强大的学习工具，可以用来理解一个你不熟悉的代码库（无论是你自己的还是别人的）。

2. 代码库范围的杂务与维护 (Chores and Maintenance)：

大规模重构：例如，将整个项目的 Tailwind CSS 从 v3 升级到 v4。
代理可以处理掉其中大量重复、乏味的工作。

3. 可预测的 Bug 修复或设计调整：

例如，修改一个按钮的颜色，这可能需要跨越多个微前端仓库、修改 25 个 PR 的那种任务，非常适合自动化。

限制与注意事项 (Limits and Considerations)

成本：背景代理通常使用最强大（也最昂贵）的“Max Mode”兼容模型，会产生费用。
缺乏实时反馈：你无法在代理工作过程中实时干预、提供指导或按 Escape 键停止它。
隐私模式：需要关闭隐私模式，代码会被发送到远程进行处理。对于开源项目来说问题不大，但对于私有项目需要谨慎。
无 API：目前还没有提供可编程的 API 来调用背景代理。

11-cursor-agents-dashboard

如何启动背景代理

可以在 Cursor 编辑器内的侧边栏启动。
也可以通过 Web 仪表盘（Dashboard）来管理和启动。

Web 仪表盘功能概览

1. 代理管理 (Agents)

可以设置默认使用的模型，选项通常是 O3 (GPT-4o)、Opus 等高端、具备“思考”能力的模型。
可以选择要操作的 GitHub 仓库和分支。
输入你的指令（prompt），例如“审计所有 Svelte 组件的可访问性问题”。
任务完成后，会生成一个摘要报告（例如，可访问性得分 7/10），并列出详细的步骤和发现。
最终可以生成一个 Pull Request (PR)。

2. 成本与用量管理 (Cost & Usage)

仪表盘会清晰地展示你的消费情况。
可以设置预算 (budget)，防止意外产生高额费用。
注意：当你接近或超出预算时，系统会非常容易地让你批准提高预算，这在“心流”状态下很容易导致超支。
可以查看详细的用量，包括每次模型调用的 token 数量和费用。

与 OpenAI Codex 的对比

界面与功能极其相似：两者都提供了一个 Web 界面，可以选择仓库、分支，然后输入指令来启动一个远程代理。
主要区别：可能仅仅是 UI 的主题色（亮色/暗色模式）不同。
并行处理：Codex 明确支持同时运行多个（例如 4 个）代理实例，每个实例都在独立的环境中工作，这对于并行探索不同解决方案非常有用。

核心价值

背景代理非常适合处理那些不需要实时交互、但颇为耗时的任务，例如代码审计、文档生成和大规模重构。
它将 AI 的能力从一个实时协作的“结对程序员”扩展为一个可以独立完成任务的“异步承包商”。

12-mcp-overview

什么是 MCP (Model Context Protocol)?

定义：MCP 是一种标准协议，让大语言模型（LLM）能够与外部工具和服务进行交互。它不仅仅局限于 AI 编程代理，也可以在其他应用中使用。
核心功能：它扩展了 LLM 的能力，使其不再局限于文本生成，而是可以调用 API、查询数据库、操作文件等。

核心思想与类比

LLM 的 API：就像你的应用程序可以调用 Twilio API 发送短信一样，LLM 可以通过 MCP 服务器调用其他服务的 API。
插件系统：可以将其视为 ChatGPT 的插件或浏览器的扩展程序，为核心功能添加了新的能力。
工具箱：MCP 为 LLM 提供了一个工具箱，当 LLM 决定需要使用某个工具时（例如，“我需要查询 GitHub 的问题列表”），它会告诉 MCP 服务器，服务器会执行相应的 API 调用并返回结果。

MCP 的工作原理

注册工具：你安装并注册一个 MCP 服务器（例如 GitHub、Supabase）。
通知 LLM：LLM 的上下文会被告知它现在拥有了哪些新工具以及这些工具能做什么。
LLM 决策：在处理你的请求时，LLM 会判断是否需要使用某个工具。
执行与返回：如果需要，LLM 会触发 MCP 服务器执行操作，并将结果返回给 LLM，LLM 再根据结果继续处理你的请求。

示例

Jira/GitHub：拉取 issue、创建 ticket、自动分类和打标签。
Postgres/Supabase：直接在数据库上执行 SQL 命令(高风险)，或更安全地拉取数据库的 schema（表结构）信息，让 LLM 了解你的数据模型。
Playwright/Firecrawl：驱动一个无头浏览器，进行网页抓取、端到端测试等。

重要的限制：上下文窗口与成本

Token 消耗：每增加一个 MCP 工具，它的功能描述都需要被加载到 LLM 的上下文窗口中，这会消耗宝贵的 token。
按需安装：不要盲目安装所有看起来很酷的 MCP 工具。只安装那些你确实需要并且能改变你工作流程的工具。

常用 MCP 服务器推荐

GitHub：非常强大，可以执行任何 GitHub API 能做到的事情。
Figma：连接到 Figma 的 Dev Mode，让 AI 可以读取设计稿的结构信息，并根据设计稿生成组件代码。
Notion：连接到 Notion 数据库，让 AI 可以读取你的产品需求文档、技术方案等。
Context.dev：一个聚合了大量库和框架官方文档的网站，并将其处理成适合 LLM 读取的格式。你可以让 AI 去这里获取最新的 Svelte Runes 或其他库的文档。

资源

cursor-directory.com 和 awesome-mcp-list (GitHub) 提供了数百个可用的 MCP 服务器列表。

13-web-scraper-with-firecrawl-mcp

如何安装自定义 MCP

在 Cursor 的设置中，找到 "Tools & Integrations"。
点击 "Add custom MCP"。
通常需要提供 MCP 服务器的来源（如一个 npm 包或 URL）以及相关的配置（如 API 密钥）。

实际案例：使用 Firecrawl MCP 抓取网页内容

背景：讲师的个人网站上课程列表已过时，需要从 frontendmasters.com 上抓取最新的课程信息来更新。
任务：手动完成这个任务非常繁琐，而使用一个网页抓取工具可以自动化这个过程。
步骤：
1. 安装并配置好 Firecrawl MCP 服务器。
2. 在 Cursor 中打开项目。
3. 提供目标网页的 URL (frontendmasters.com 上的讲师页面)。
4. 下达一个清晰的指令：
  
  "遍历此页面上所有的课程和工作坊。对于每一个，我需要标题 (title)、缩略图 (image) 和链接 (link)。将这些信息写入到一个名为 courses.json 的文件中。"

执行过程与结果

工具选择：Cursor 的 LLM 识别到这个任务需要网页抓取能力，于是自动选择了新安装的 Firecrawl 工具。
执行：Firecrawl 访问了指定的 URL，解析了页面内容，并提取了所需的数据。
输出：成功地在项目中创建了一个包含所有课程信息的 JSON 文件。

核心价值

赋能 LLM：MCP 就像给 LLM 增加了“超能力”。原本只能处理文本的 AI，现在可以与外部世界（如网页）进行交互。
自动化繁琐任务：这展示了如何利用 AI 和 MCP 来自动化那些虽不复杂但极其耗时和乏味的工作（如编写和维护一个网页爬虫）。
提高生产力：将原本可能需要花费一个周六下午的时间，缩短为几分钟的指令输入和结果审查。

安全警告 (The 'S' in MCP is for Security)

供应链风险：很多 MCP 服务器是从 npm 安装的，这意味着存在供应链攻击的风险。你应该只安装来自可信来源的包，或者在本地克隆并审计其代码。
API 密钥泄露：安装 MCP 服务器通常需要提供 API 密钥或访问令牌（Access Token）。要非常小心，不要安装来路不明的 MCP，尤其是那些需要你 Google Drive 或其他敏感服务访问权限的。
信任但验证：官方或知名社区维护的 MCP（如官方 GitHub MCP）相对更可信，但任何第三方代码都存在风险。
记住：每增加一个 MCP 工具，你不仅支付了 token 的成本，也承担了相应的安全风险。

14-linting-rules

传统最佳实践在 AI 时代的强化

测试 (Testing)：良好的测试覆盖率比以往任何时候都更加重要。因为 AI 代理可能会修改你意想不到的代码区域，只有完备的测试才能捕捉到这些回归问题。
版本控制 (Version Control)：频繁提交 (commit early and often) 是必须的。

为什么 ESLint 规则对 AI 编程至关重要

在人类团队中，强制推行过于严格的 lint 规则可能会引起争议和抵触。
但对于 AI 代理，这些规则成为了一个至关重要的反馈循环和护栏，它们可以约束 AI 的行为，减少混乱。

如何应用这些规则

作为反馈循环：将 lint 检查作为 pre-commit hook 的一部分。你可以告诉 AI：“你的任务必须通过 lint 检查才能提交”。AI 会读取 lint 的错误输出，并尝试修复它们。
渐进式应用：
- 使用 lint-staged 只对当前提交中修改过的文件运行 lint 规则，避免一次性修复整个旧代码库。
- 可以为 AI 设置一个特定的环境变量，使其在工作时遵循更严格的规则集。
用于重构：可以临时开启某条严格的规则，让 AI 专门针对某个目录进行“技术债偿还”，完成后再关闭规则，以免影响团队其他成员。

结论

使用现有的、成熟的工具（如 ESLint）来强化和约束 AI 的行为，是一种非常有效且被低估的策略，可以带来极佳的效果。

15-claude-code-overview

Claude Code 简介

一个在终端中运行的 AI 编程助手。
作者经常同时使用 Cursor 和 Claude Code：在 Cursor 的侧边栏规划任务，然后在终端中使用 Claude Code 执行这些计划。

优点

性能强大：通常能提供高质量的编码结果。
定价模式（在被削弱前）：Max 计划提供固定的月费，而不是按 token 计费，这对于大量使用非常有吸引力。

安装与设置

通过 npm 全局安装。
提供 SDK，可以进行程序化调用。
claude doctor 命令可以检查安装和配置是否正确。
在项目目录中直接运行 claude 即可启动。

定价与账户

两种支付方式：
1. Max 订阅计划（$20 Pro, $100/$200 Max）：价格可预测，有使用频率限制（rate limits）。强烈推荐这种方式。
2. 使用 API Key：按 token 计费，价格不可预测，有超支风险。

核心特性

交互模式：默认进入一个交互式终端会话。
单次执行模式：使用 p 参数可以执行单个指令然后退出。这非常适合在 CI/CD 流程中集成，例如：“如果 lint 失败，请分析错误并将其摘要写入 GitHub issue”。
斜杠命令 (/): 提供了类似 Slack 的快捷命令。
@ 符号: 与 Cursor 类似，用于引用文件和上下文。
Hooks: 提供了钩子函数（如 session_start），可以在会话开始等特定时机自动执行脚本。

模型选择

主要提供两个模型：
1. Sonnet: 日常主力模型，性价比高。
2. Opus: 最强大的模型，用于处理复杂任务、制定计划和进行深入研究。消耗的 rate limit 额度远高于 Sonnet（大约 4-6 倍）。
切换模型：
- 可以在会话中通过 model 命令进行切换。
- 可以在启动时通过命令行标志指定模型。
使用策略：
- 使用 Opus 进行头脑风暴、制定详细计划和研究。
- 当有了一个清晰、详尽的计划后，切换到更经济的 Sonnet 来执行具体的编码任务。

Rate Limits (使用频率限制)

这是使用 Claude Code 最需要注意的一点。
限制是基于时间窗口的（例如，每 5 小时内有多少次请求），并且 Opus 和 Sonnet 的消耗额度不同。
保护 Rate Limits：作者会使用其他模型（如 Gemini 或 GPT-4o）来进行头脑风暴，而将宝贵的 Claude rate limits 留给核心的编码任务，这是一种跨模型协作的策略。

16-thinking-mode-compacting-context-windows

Anthropic 的思考模式 (Thinking Mode)

背景：像 GPT-4o 这样的模型被认为是“推理模型”，它们在回答前会进行思考。Anthropic 的模型（如 Sonnet, Opus）也可以被引导进入这种思考状态。
触发方式：在你的提示词中包含关键词 "think"。
- think this through: 启动约 4000 token 的推理过程。
- think hard: 启动约 10000 token 的推理过程。
- ultrathink: 最多可达 31,999 token（讲师对此表示怀疑，认为其效果可能与 think hard 相同，但名字听起来更厉害）。
成本与权衡：
- “思考”会消耗大量的 token，尤其在使用昂贵的 Opus 模型时。
- 这是一个权衡：是花 token 进行深入思考以获得高质量的计划，还是直接生成代码然后发现是垃圾再重来？哪种方式更节省 token？
- 没有标准答案：需要根据具体情况、模型、以及你当前的 rate limit 额度来决定。有时，在其他工具（如 Gemini）中规划好再粘贴过来，完全不消耗 Claude 的 token 也是一种有效策略。

上下文窗口的压缩 (Compacting Context Windows)

问题：当聊天历史变得很长，接近上下文窗口的极限时，需要进行处理。
Cursor 的做法：强制你开启一个新的聊天窗口。
Claude Code 的做法：它会进行“压缩”。
- 压缩机制：Claude 会将当前的整个聊天历史发送给模型，并要求其“总结成一个更短的版本”。
- 缺点：在这个过程中，一定会损失信息保真度。如果你之前的聊天中包含了多个不相关的话题，一些你关心的重要细节可能会在总结中被丢掉。

如何主动管理压缩

主动触发：你可以随时使用 /compact 命令来手动触发压缩。
最佳时机：在完成一个任务、准备开始下一个任务的“自然间歇点”进行压缩。
提供指导：手动压缩时，你可以提供一个简短的提示，告诉模型在总结时应该关注哪些重点（例如，“只保留待办事项”或“总结与这个功能相关的要点”）。这比让系统自动压缩要可靠得多。
clear vs. compact：
- 如果你要彻底切换到一个全新的任务，直接使用 /clear（清空上下文）可能比 /compact（保留部分旧信息）更好。这相当于重启一个新的会话。

17-getting-started-with-claude-code

启动与基本命令

在项目目录下输入 claude 即可启动。
输入 / 可以查看所有可用的斜杠命令。

常用斜杠命令

add-dir: 将另一个目录（如一个本地链接的库）添加到 Claude 的可访问路径中，适合 Monorepo 或多项目协作场景。
export: 将当前会话的完整历史（以 JSONL 格式）导出到文件或剪贴板，便于复盘和分析。
ide: 在 VS Code 或 Cursor 的内置终端中使用时，会自动安装一个配套的 VS Code 扩展，用于显示 side-by-side diff 等。
github: 安装 GitHub Actions，让你可以在 PR 中 @ Claude 并向它提问。
model: 在 Sonnet 和 Opus 模型之间切换。
permissions: 精细化控制 Claude 的权限，例如允许 git status 但禁止 git commit 或 git push。
resume: 恢复之前的任意一个会话。所有会话都以 JSON 格式存储在本地文件系统中。
status: 非常有用。可以查看当前使用的模型、rate limit 的状态（何时恢复），以及其他账户信息。

项目初始化：`claude.md` 文件

/init 命令：在一个新项目中，首先运行此命令。Claude 会分析整个代码库，并自动生成一个 claude.md 文件。
claude.md 的作用：
- 相当于 Cursor 的规则文件集合，但集中在一个文件中。
- 包含了对项目架构、技术栈、状态管理、测试策略等的全面总结。
- 你的核心工作：维护和策划 (curate) 这个文件，不断地向其中添加项目的特定知识、架构约束和个人偏好。

与 `claude.md` 的交互

持续加载：Claude 会确保在每次任务开始时，claude.md 的内容都在其上下文中。
实时更新：
- 可以直接编辑这个 Markdown 文件。
- 可以在聊天中随时使用 #add-to-memory 命令，将新的规则或知识点追加到 claude.md 中。

同时使用 Cursor 和 Claude Code 的挑战

最大的问题是需要手动保持 Cursor 的规则文件 (.cursor/rules/) 和 Claude 的 claude.md 文件内容同步，否则会导致 AI 在不同工具中行为不一致。

18-project-boundaries-reference-files

`claude.md` 的深度定制

作为项目的“活文档”：这个文件是你与 AI 沟通的核心。你应该在其中详细阐述项目的方方面面。
具体示例：
- 编码准则：明确指出应该复用已有的工具函数，而不是创建新的。
- 架构约束：用 Markdown 表格清晰地列出 Chrome 扩展中不同脚本（Service Worker, Content Script）的权限和能力边界。
- 技术选型：解释为什么在特定场景下选择使用 Lit Web Components 而不是 Svelte。
- 抽象层：指示 AI 使用你封装好的消息传递抽象，而不是直接调用底层的 chrome.* API。
结果：尽管看起来有些繁琐，但你投入在 claude.md 上的精力越多，AI 犯错的次数就越少，结果也越可靠。

引用外部文件：超越 `claude.md`

你可以在项目中创建专门的参考文件（例如存放在 reference/ 目录下）。
这些文件可以是：
- 从 context.dev 等服务拉取的官方文档。
- 你亲自编写的产品需求文档 (PRD) 或技术实现计划。
使用方式：在向 Claude 提问时，使用 @ 符号将这些参考文件明确地引入上下文。

计划模式 (Plan Mode)：Claude Code 的核心优势

触发方式：按 Shift + Tab 切换模式，选择 "Plan Mode"。
工作流程：
1. 提供上下文：给 Claude 一个详细的任务描述，并 @ 引用所有相关的计划文档和代码文件。
2. 生成计划：Claude 不会立即开始编码，而是会先生成一个详尽的、分步骤的行动计划。这个计划通常会包括：
  - 需要安装的依赖。
  - 分阶段的任务列表（例如，分成几个“周”或“阶段”）。
  - 潜在的风险和收益分析。
3. 互动与修订 (Workshop)：这是关键一步。你可以审查这个计划，并给出反馈：
  - Yes: 同意计划，开始执行。
  - No + 反馈: 提出修改意见，例如“请不要引入那个库”或“你考虑过……情况吗？”
  - Keep Planning: 让它继续完善计划。

19-commands

隐藏的Hackathon模式

激活方式

使用 dash continue 或 dash resume 命令启动 Claude，可以接续上一个会话。
这会开启一个隐藏的第四种模式，可以通过 Shift + Tab 切换其显示。

主要功能：待办事项列表 (To-Do List)

该模式会保留并显示一个待办事项清单 (to-do list)。
这个清单会自动存储在用户主目录的 JSONL 文件中，因此即使中断会话也不会丢失，确保了工作的连续性。

与旧方法的对比

过去，开发者通过 Markdown 文件和 Markdown 清单来实现类似的功能。
当前的集成模式更加方便和高效。

命令 (Commands) 功能介绍

核心概念

类似于 Cursor 中的 "notepads" 功能，是一种快捷方式。
如果你发现自己经常重复输入某些特定的指令或提示，可以将其创建为一个命令文件。
命令本质上是预设提示词 (Prompt) 的快捷方式，通过简单的斜杠 / 触发。

工作原理

当你在聊天框中输入一个命令（例如 /lint），它会自动将命令文件中预设的文本内容插入到你的当前提示词中。

命令使用示例

示例 1：`/lint` 命令

功能: 运行代码规范检查 (lint rules)。
预设内容: 指示 AI 运行特定的 lint 命令，确保所有错误都被解决，但可以忽略某些警告（如文件长度警告）。
作用: 快速执行一个带有特定规则的检查任务，避免每次手动输入复杂的指令。

示例 2：结合个人思考

用户可以在使用命令的同时，添加自己临时的想法、笔记和上下文。
命令的预设内容会与用户的即时输入结合，形成一个更完整、更具针对性的提示词。

高级命令功能

运行 Bash 命令

在命令文件中，任何以感叹号 ! 开头的行都会被当作 Bash 命令来执行，其输出结果会被插入到提示词中。

插入文件列表（如未提交的文件）

可以通过运行一个 Shell 脚本（例如 git status）来动态获取文件列表（如所有未提交的文件），并将其插入到提示词中。
示例: 创建一个命令，要求 AI "review all the following files..."，后面自动附加上由脚本生成的文件列表，以便进行代码审查或文档生成。

指定参数位置 (`$arguments`)

默认情况下，用户在命令后输入的任何文本都会被追加到预设提示词的末尾。
如果在命令文件的模板中使用了 $arguments 这个占位符，那么用户输入的内容将被精确地插入到该占位符所在的位置。

使用 @ 提及文件以添加上下文

在提示词中使用 @文件名（例如 @product summary.markdown），可以将被提及的整个文件内容拉入到当前对话的上下文中。
这是一种主动、精确地向 AI 提供相关背景信息的方法，与之前讨论的“如何排除文件出上下文”相反，这是“如何主动包含文件进上下文”。

`/goal` 命令示例

功能: 将项目目标文件 product summary.markdown 加载到上下文中。
作用: 当需要 AI 理解项目整体目标时，只需输入 /goal，即可快速为其提供必要的背景信息，而无需手动复制粘贴。

20-claude-code-hooks

什么是 Claude Hooks?

它们是在 Claude Code 执行过程中的特定生命周期时刻触发的钩子函数。
目前，这些钩子只能执行 Bash 命令。

生命周期钩子

session_start：在会话开始时触发。
on_stop：在任务停止时触发。可以用来发送通知（如桌面通知、短信）。
pre_compact：在上下文压缩前触发。

核心钩子：`pre_tool_use` 和 `post_tool_use`

`pre_tool_use` (工具使用前)

功能：在 Claude 即将执行一个“工具”（如运行 shell 命令、编辑文件、调用 MCP）之前触发。
核心用途：拦截和阻止不安全或不希望的操作。
示例：
- 检查 shell 命令是否包含 git commit --no-verify，如果包含，则返回非零退出码（如 2）来阻止它。
- 阻止 AI 修改 ESLint 配置文件。
- 检查 web_fetch 命令中是否意外包含了 API token。

`post_tool_use` (工具使用后)

功能：在 Claude 完成一个“工具”操作后立即触发。
核心用途：立即进行验证和格式化。
示例：
- 当 Claude 修改或创建了一个文件后，立即对该文件运行 prettier 和 eslint --fix。
- 如果 lint 检查失败，则返回非零退出码，迫使 Claude 回去修复它自己造成的 lint 问题。
- 当一个代码文件被修改后，自动运行相关的单元测试。

实现更严格的规则

为 AI 定制规则：你可以为 post_tool_use 钩子中的 lint 命令设置更严格的规则，例如 max-warnings=0。这意味着，如果 AI 的修改引入了任何 lint 警告（即使构建本身会通过），钩子也会失败，迫使它写出更干净的代码。
解决 Claude 的坏习惯：Claude 有时只会修复高优先级的 lint 问题而忽略低优先级的。通过这种钩子，你可以强制它修复所有问题。

使用 TypeScript 编写 Hooks

直接编写复杂的 Bash 脚本很痛苦。社区提供了一个名为 claude-hooks 的 TypeScript 库。
这个库允许你用 TypeScript 来编写钩子逻辑，它会处理与 Claude 终端之间的标准输入/输出通信。
你可以更轻松地实现复杂的逻辑，例如：
- 解析 CSV 任务列表。
- 根据任务的复杂性决定是立即执行还是将其添加到待办事项中。

实验与学习

讲师展示了一个个人实践：他创建了一个钩子，将每一次工具调用的 payload（载荷）都记录到一个文件中。
这样做可以帮助他深入理解 Claude 内部都调用了哪些工具，以及这些工具的输入和输出是什么，从而更好地设计和编写自己的钩子。

21-subagents

什么是子代理 (Subagents)?

这是 Claude Code 最近推出的一个新功能，允许你创建具有特定角色和职责的“子”AI 代理。
这是对社区中已经出现的“多代理框架”（通过命令、钩子等 hacky 方式实现）的官方支持。

核心优势：独立的上下文窗口

关键特性：每个子代理都拥有自己独立的上下文窗口，它与主代理以及其他子代理的上下文是隔离的。
价值：
1. 避免上下文污染：主代理可以将一个复杂的任务分派给子代理。子代理在自己的小世界里处理完任务后，只将最终结果返回给主代理，而不会用其冗长的思考过程污染主代理的上下文窗口。
2. 避免压缩和信息丢失：由于上下文被分片（shard），可以有效避免主上下文窗口过早达到上限而被迫进行有损压缩。

子代理的配置

独立的系统提示 (System Prompt)：可以为每个子代理设置一个独特的系统提示，赋予它一个特定的“人格”或“视角”。例如：
- “你是一位经验丰富的前端架构师。”
- “你是一位初级工程师，你的任务是质疑所有不明确的需求。”
- “你是一位文案编辑，负责修正拼写和语法错误。”
独立的工具集：可以为每个子代理分配不同的工具权限。例如：
- “测试工程师”子代理可以使用 Playwright。
- “前端架构师”子代理只能编辑 Markdown 文件，不能写代码。

如何使用子代理

创建/管理：使用 /agents 命令。你可以创建项目级或用户级的子代理。
调用：在提示中通过名字提及子代理，主代理就会将任务分派给它。

有效的子代理角色示例

Copyeditor (文案编辑)：一个用户级的子代理，专门用来修正拼写和语法错误，同时能区分代码中的变量名和真正的错别字。
Test Strategist (测试策略师)：负责规划和编写测试。
Junior Engineer (初级工程师)：非常有价值的角色。它的任务是阅读计划或需求，并提出所有它认为不明确、有疑问的地方。这会迫使你（或主代理）把问题想得更清楚，最终生成一个问题和答案的清单，极大提高了计划的质量。

22-running-a-plan-through-a-subagent

演示工作流

任务设定：有一个关于使用 tRPC 的详细计划文档 (trpc.md)。
子代理协作：
- 主代理的指令：@JuniorEngineer @FrontendArchitect read @trpc.md, provide answers to those questions, and write both the questions and answers to trpc_questions.md。
- JuniorEngineer 的角色：阅读计划，并提出所有它认为不明确的问题。
- FrontendArchitect 的角色：回答 JuniorEngineer 提出的问题。
执行过程：
- 终端会显示不同颜色的输出来区分是哪个代理在工作。
- JuniorEngineer 首先分析计划并生成问题列表。
- 然后 FrontendArchitect 接手，对这些问题进行回答。
- 最终，将整个问答过程写入一个新的 Markdown 文件。

创建新的子代理

使用 /agents 命令，选择 "Create new agent"。
可以告诉 Claude 你想要一个什么样的代理（例如，“一个非技术用户”），它会自动为你生成一个配置文件草稿。
配置文件是一个 YAML 文件，你可以在其中进行精细调整：
- Persona (人格)：定义代理的行事风格和思考角度。例如，非技术用户会“总是从用户影响的角度来反馈”。
- Allowed Tools (允许的工具)：严格限制该代理可以使用的工具，例如，禁止非技术用户编辑或写入任何文件。
- Color (颜色)：为代理在终端中的输出指定一个颜色。

结果分析与核心价值

结果：生成的 Markdown 文件包含了一系列深刻的问题和相应的架构层面的回答。例如：
- 问题：Chrome 扩展的 Service Worker 生命周期很短，无法维持 tRPC 所需的持久连接，我们如何解决这个问题？
- 价值：这个问题点出了原始计划中一个被忽略的、致命的技术难点。
AI 的真正力量所在：
- 这次交互的价值不在于生成了代码，而在于它通过模拟不同角色的对话，帮助人类识别出了计划中的缺陷和未考虑到的复杂性。
- 即使最终这个计划被证明不可行而被放弃，这次“失败”的探索也极大地节省了时间，避免了在错误的方向上投入数周的开发工作。这比盲目地快速生成代码要快得多。
作为学习工具：
- 当你独自工作，没有团队可以讨论时，子代理可以模拟一个团队评审过程。
- 对于初学者，阅读 AI 生成的这些深刻问题和架构讨论，是快速学习和理解复杂技术权衡的绝佳方式。
- 如果看不懂 AI 提到的术语，可以立刻追问：“请用五岁小孩能听懂的方式，通过水管的比喻来解释……”，这是一种非常有效的学习技巧。

23-tips-for-using-subagents

子代理使用的注意事项

调用方式：目前看来，必须在提示中明确按名字提及，AI 才能选择并使用相应的子代理。它还不能智能地根据任务内容自动选择最合适的代理。
一次性上下文：子代理的上下文是独立的，任务完成后，其上下文中的信息（除了返回值）就会丢失。如果你拒绝了子代理的返回结果，那么它在这次任务中消耗的所有 token 都相当于被浪费了。
监控有限：在主代理的界面中，你只能看到“某个子代理正在工作”，但无法实时看到它具体的思考过程和正在执行的操作。
时间和 Token 消耗：使用子代理会增加总体的执行时间（因为是串行处理）和 Token 消耗。
避免“厨房里厨师太多”：过多的子代理可能会导致混乱。应从少量、职责清晰的子代理开始。

最佳实践

1. 从小处着手，保持简洁

子代理的配置文件（尤其是 Persona 描述）不宜过长，以免消耗过多的 Token。

2. 明确调用

在需要时主动、明确地调用子代理。

3. 精细化权限管理

这是一个非常强大的应用场景。可以利用子代理来隔离权限，尤其是与 MCP 服务器结合时：
- 将危险或昂贵的 MCP 工具（如 Playwright）只授权给特定的“测试工程师”子代理。
- 禁止“架构师”子代理编写代码，只允许它编辑 Markdown 和文档。
- 创建一个专门的“Linter”子代理，只有它有权限修改 ESLint 配置文件。
这样可以有效地将上下文和权限控制结合起来，提高安全性和可控性。

并行工作与 Git Worktrees

背景：之前讨论过如何通过背景代理实现并行工作。在本地，可以使用 git worktree 来实现。
git worktree：Git 的一个功能，允许你在文件系统上为同一个仓库创建多个工作目录，每个目录可以对应一个不同的分支。
问题与挑战：
1. Rate Limit 消耗加倍：同时运行 4 个 Claude 实例，你的 rate limit 消耗速度会是原来的 4 倍。
2. 审查瓶颈：即使 AI 可以并行生成代码，你（作为人类）的审查能力是有限的，你仍然是整个流程中的“主线程”和瓶颈。
3. 管理开销：需要管理多个目录，清理，以及在每个目录中安装依赖等，非常繁琐。
工具推荐：有一个名为 Crystal 的开源应用，它为管理 git worktree 和并行运行 Claude 实例提供了一个图形化界面，可以简化这个过程。
结论：尽管听起来很酷，但作者个人发现，在引入了更严谨的审查和规划流程后，并行“氛围编程”的实际效率提升有限。

24-wrapping-up

核心思想总结

重点不在于生成代码：AI 时代，软件开发的难点从未改变——它在于权衡 (trade-offs)、管理复杂性 (complexity) 和做出明智的决策。单纯地输出大量代码并不能解决这些根本问题。
提升人类的价值：AI 抬高了对人类清晰表达意图、建立结构和护栏的要求。讲师之所以能从 AI 获得高质量的输出，是因为他建立了严格的 ESLint 规则、钩子、测试和详细的计划。
关注真正有价值的工作：让 AI 处理那些繁琐、重复的工作（如修复 lint 错误、数据结构转换），人类则可以专注于更高层次的活动，如架构设计、代码审查、系统思考——这些才是职业发展的关键。
编程技能依然重要：AI 会制造混乱，你需要有能力去理解和修复它。编程技能不会消失，只是抽象层次提高了。
AI 是强大的学习和加速工具：
- 它可以让你接触到在职业生涯早期难以接触到的复杂系统。
- 即使一个由 AI 生成的计划最终被证明是错误的，这个探索过程本身也能帮助你更快地理解问题，避免在错误的方向上浪费时间。这个“学习和修正”的过程非常有价值。
拥抱新范式：这是一个巨大的机遇。能够熟练驾驭这些工具的工程师，将在知识和技能上迅速与那些固守传统方法的资深工程师站在同一起跑线上。

Cursor & Claude Code: Professional AI Setup

0-introduction

主题：构建、定制或适应 AI 辅助的开发环境

Vibe Coding 体验

本次演讲的核心议题

揭开 AI 的神秘面紗

核心论点：回归基础

软件开发的本质演变

目标：获得杠杆，而非降低效率

AI 对职业发展的影响

1-ai-tools-overview

本次课程重点关注的两个工具

工具范式对比

Cursor

Claude Code

其他范式：OpenAI's Codex

“我应该用哪一个？”

工具的定价和可用性

Cursor

Claude Code

替代方案

2-context-window-rules

核心概念：上下文窗口 (Context Window)

最重要的主题：管理上下文窗口

如何有效管理上下文窗口

1. 分解问题

2. 明确计划

3. 管理聊天历史

4. 分阶段工作：构思 vs. 执行

保持代码库的整洁

心态调整

3-cursor-ai-models-overview

Cursor 的三种半主要模式

1. 内联编辑 (Inline Edit)

2. 聊天 (Chat)

3. 代理模式 (Agent Mode)

3.5. Tab 自动完成

Cursor 如何理解你的代码（启发式方法）

如何更精确地提供上下文

模型选择与权衡

Anthropic (Claude) 系列

Google (Gemini) 系列

OpenAI (GPT) 系列

自托管模型 (Self-hosted)

核心建议

4-cursor-tour-settings

启动与界面

侧边栏核心功能导览

1. 聊天窗口 (Chat Window)

2. 添加上下文 (Add Context)

3. 模型切换 (Model Toggle)

4. 模式切换：Agent vs. Ask

重要设置项 (Cursor Settings)

Chat (聊天设置)

Context (上下文设置)

Models (模型设置)

5-using-cursor-ai-inline-edits

内联编辑 (Inline Edits)

Tab 自动完成功能

表达意图与审查

实用的单次提示技巧 (One-Shot Prompting)

mirror (镜像/模仿)

I need a function that... (我需要一个函数...)

“跟随问题”工作流 (Follow the Problem Workflow)

6-using-cursor-ai-agent

代理模式 (Agent Mode)

提示词的特异性至关重要

标准工作流程

代码审查是你的责任

处理错误与卡顿

代理模式的常见问题

7-cursor-ai-rules

什么是 Cursor 规则 (Cursor Rules)?

规则的类型

1. 项目级规则 (Project-level rules)

2. 用户级规则 (User-level rules)

规则的应用方式 (Rule Attachment)

auto-attached (自动附加)

agent-requested (代理请求)

manually (手动引用)

`mirror` (镜像/模仿)

`I need a function that...` (我需要一个函数...)

`auto-attached` (自动附加)

`agent-requested` (代理请求)

`manually` (手动引用)