2.2 VibeCoding 工作流

title: "2.2 VibeCoding 工作流"
description: "掌握 AI 原生开发的标准流程与提示词技巧"
chapter: "第二章"​

2.2 VibeCoding 工作流

阅读完本节后，你将会收获：

• 掌握 VibeCoding 标准五步工作流：探索 → 规划 → 执行 → 验证 → 提交
• 理解 Agent Native 开发思维，学会从"怎么做"转向"做什么"的产品导向思维
• 学会编写高质量提示词：直接描述任务、提供上下文、给出具体约束
• 掌握权限模式、斜杠命令、检查点功能等 Claude Code 核心交互方式
• 了解多 Agent 并行协作机制，学会利用 AI 自动化能力提升开发效率

序言中提到的"Workflow（工具流）"是 Vibecoding 的核心，以及 VibeCoding 的标准开发流程。

前置知识

::: tip 什么是 Claude Code

Claude Code 是一个 AI 命令行工具，能直接读取项目文件、执行命令、自动修改代码和完成任务。
:::

::: tip 什么是 工作流

工作流（Workflow）是完成任务的标准化流程。AI 开发的工作流包含探索、规划、编码、提交等环节。
:::

::: tip 什么是 提示词

提示词（Prompt）是发送给 AI 的文本指令，描述你希望 AI 完成的任务。好的提示词是工作流的一部分。
:::
::: details 点击查看 Agent Native 开发思维

Agent Native = 以 AI Agent 为中心的开发思维

传统开发中，AI 是辅助工具（Copilot）；Agent Native 中，AI 是自主执行者（Autopilot）。

传统思维 vs Agent Native

维度	传统 AI 辅助开发	Agent Native 开发
核心角色	人写代码，AI 帮忙	AI 为主，代码是 AI 的实现细节
工作方式	AI 是 Copilot	AI 是 Autopilot
交互模式	人写 Prompt 指挥 AI	AI 主动提问、规划、执行
输出形态	AI 生成代码片段，人来整合	AI 自主完成完整任务
你的关注点	怎么写代码	写什么产品

VibeCoding 的核心哲学：你是导演，AI 是演员

VibeCoding 的核心不是"让 AI 替你写代码"，而是"你驾驭 AI 写代码"。这个区别至关重要。如果你把 AI 当成替代品，你会逐渐失去对产品的控制权，最终做出的东西可能技术上完美，但产品上平庸。真正强大的用法是"一放一收"：放，是让 AI 在海量技术方案中自由探索，生成多种实现路径，帮你看到你原本看不到的可能性；收，是你在关键节点选定方向、拍板决策、承担责任。

你的作品价值不在于代码量有多大、技术栈有多新，而在于它体现了你选定的产品方向、你做出的架构判断、你愿意为此承担的责任。AI 可以帮你写出一万行代码，但只有你能决定这一万行代码应该解决什么问题。这就是为什么 PRD 如此重要——PRD 就是你对 AI 的"控制权"。没有 PRD，AI 是脱缰的野马，可能跑得很快但方向不对；有了 PRD，AI 是听话的执行者，它的每一步都在你的掌控之中。

AI 与人的分工：预测与判断

在 VibeCoding 工作流中，理解 AI 和人的分工至关重要。AI 负责的是"预测"——它会基于海量的训练数据，生成多种代码方案、提供架构建议、推荐技术选型。这些方案通常是概率最高的、最符合最佳实践的选择。但 AI 不知道你的业务场景、不了解你的用户需求、也无法为产品方向负责。

这就是你的价值所在。你负责的是"判断"——在 AI 给出的多个方案中选择最适合的那个，基于你对业务的理解决定是否接受某段代码，基于你对用户需求的洞察决定产品往哪个方向走。这不是因为 AI 能力不足，而是因为分工本就如此：AI 擅长基于数据做预测，你擅长基于理解做判断。

权限模式（Default/Plan/Accept Edits）本质上就是在调节"预测与判断的脱钩程度"。Default 模式下，AI 的只读探索自动执行，但修改代码时需要你判断；Plan 模式下，AI 只能探索和分析，所有判断都由你做；Accept Edits 模式下，AI 可以自主运行命令和测试，但修改代码时仍需你判断。选择哪种模式，取决于你对当前任务的熟悉程度和风险承受能力。

Agent Native 的三大原则

1. 意图驱动

告诉 AI 目标，让它自己决定实现方式：

❌ 传统思维：
"帮我写一个函数，接收数组参数，用 for 循环遍历，
遇到大于 10 的就 push 到新数组里..."

✅ Agent Native：
"过滤数组中大于 10 的元素，返回新数组"
​

2. 异步协作

AI 可以在你睡觉时工作：

# 你设定目标，AI 自主执行
"实现用户评论功能，包括：
1. 数据库 schema（Comment 模型）
2. CRUD API
3. 前端评论表单
4. 评论列表展示

完成后告诉我，我先去忙别的。"
​

3. 信任但验证

不要逐行检查 AI 的代码，而是：

验证方式：

• 功能测试：跑一下看看能不能用
• 类型检查：tsc 有没有报错
• 代码审查：只看关键逻辑，不看实现细节

从开发者到编排者

Agent Native 时代，你的角色转变：

传统开发者	Agent Native 编排者
手写代码	描述需求
逐个修复	反馈问题
关注语法	关注产品
是工匠	是指挥官

记住：代码是实现细节，产品才是目的。Agent Native 让你从"怎么做"中解放出来，专注于"做什么"。

:::

核心概念

Vibecoding 的核心理念

Vibecoding = Prompt（提示词） + Workflow（工具流）
​

Prompt 告诉 AI 做什么
Workflow 决定怎么做

提示词的核心原则

AI 是一个强大的编程助手，它理解技术术语、熟悉各种框架、能快速分析代码。

沟通的关键是：直接、具体、有上下文。

❌ 绕弯子：

"你是一位资深的全栈工程师，精通各种技术栈..."
​

→ AI 不需要角色扮演，它知道自己能做什么

✅ 直接说事：

"检测这个 React 组件的类型安全问题"
​

→ 一句话讲清楚要做什么

❌ 模糊描述：

"帮我优化一下代码"
​

→ AI 不知道优化什么方向

✅ 具体需求：

"优化登录页面的加载性能：
1. 添加图片懒加载
2. 延迟加载非关键资源
3. 使用 Next.js 的动态导入"
​

→ 明确优化目标和实现方式

提示词原则

好提示词的特征

提示词对比：欠佳 vs 推荐

类型	欠佳	推荐
角色扮演	"你是一位拥有 20 年经验的全栈工程师，精通 React、Vue、Angular、Node.js、Python..."	直接说任务："实现用户登录功能"
模糊指令	"帮我优化一下代码"	"优化登录页面的加载性能：添加图片懒加载、延迟加载非关键资源"
无边界限制	"写一个完整的电商系统"	"实现用户评论功能，包括：评论表单、列表展示、数据持久化"
强行要求	"你必须给出正确答案，不能说不知道"	"如果不确定，请明确说'我不确定'，而不是编造答案"
具体任务	"帮我写一个登录功能"	"实现用户登录功能：用户名+密码登录，使用 Next.js 16 App Router，Drizzle ORM + PostgreSQL，包含表单验证和错误处理"
提供上下文	"修复这个 Bug"	"修复 Bug：文件 app/login/page.tsx，问题：用户登录后没有跳转到首页，预期：跳转到 /dashboard"
指令要具体	"添加测试"	"为 app/login/page.tsx 编写测试用例，框架：Playwright，覆盖场景：密码错误、账号不存在、网络错误"

核心原则：

• 不要让 AI 猜 → 提供明确上下文
• 不要含糊其辞 → 给出具体要求
• 不要强行编造 → 给 AI 一个"不确定"的出口

让 AI 反复提问

"我要开发一个任务管理应用。
请反复问我问题，直到你完全理解我的需求。
不要猜测，直接问。"
​

提示词模板

代码生成模板

"实现 [功能名称]

技术栈：
- Next.js [版本]
- TypeScript
- Drizzle ORM
- [其他技术]

需求：
1. [具体需求1]
2. [具体需求2]
3. [具体需求3]

注意事项：
- 遵循项目现有代码风格
- 不要引入新依赖，除非必要
- 包含错误处理"
​

Bug 修复模板

"修复 Bug

文件路径: [完整路径]
错误信息:
[完整报错日志]

当前代码:
[相关代码片段]

期望行为: [描述]
实际行为: [描述]

请分析原因并提供修复方案"
​

标准工作流

AI 的自动化能力

在开始工作流之前，记住：AI 能自动处理很多任务。

::: info Claude Code vs 其他 AI 工具

关键区别：

特性	Claude Code	Cursor/Windsurf	ChatGPT 网页版
项目上下文	✅ 自动读取整个项目	✅ 自动读取	❌ 手动粘贴
命令执行	✅ 直接运行 bash	✅ 集成终端	❌ 复制到终端
文件修改	✅ 自动编辑多个文件	✅ 多文件编辑	⚠️ 逐个复制
版本控制	✅ 自动提交	✅ Git 集成	❌ 手动操作
工作流	✅ 标准化流程	⚠️ 需要手动	❌ 随意对话

为什么 Claude Code 更适合 Vibecoding：

1. CLI 原生：命令行是开发者的原生环境
2. 自动化程度高：减少手动操作
3. 标准化流程：探索 → 规划 → 实现 → 验证 → 提交
4. 完整上下文：理解整个项目结构
   :::

AI 的自动化能力：

• ✅ 自动探索项目结构（你不需要告诉它看哪些文件）
• ✅ 自动选择合适的工具（Read、Edit、Bash）
• ✅ 自动处理错误（失败会重试或换方案）
• ✅ 自动生成提交信息（根据修改内容）
• ✅ 自动识别依赖关系（知道修改会影响哪些文件）

你需要做的：

• 清楚描述任务目标
• 提供必要的上下文
• 验证结果并反馈

不需要做：

• ❌ 指定具体步骤（"先读文件A，再读文件B"）
• ❌ 告诉它用哪个工具（"用 Read 工具读取"）
• ❌ 手动组合命令（"运行 git add 然后 git commit"）
• ❌ 手动处理错误（"如果失败就重试"）

权限模式

::: tip 场景：为什么需要切换模式

你正在调试一个功能，每次运行测试都要点"确认"，一分钟内点了 5 次。效率很低。

你试着按 Shift+Tab 切换到 Accept Edits 模式，测试命令自动执行，只有修改代码时才询问。瞬间清净了。

这就是权限模式的作用：在不同场景下，平衡效率和安全。

:::

三种权限模式

模式	快捷键	特点	何时使用
Default	Shift+Tab	读自动，写询问	日常开发（推荐）
Plan	Shift+Tab	只读不写	想先了解代码，怕误改
Accept Edits	Shift+Tab	写需确认，其他自动	频繁测试/运行命令

快速决策：

• 不确定时 → Default
• 只想看代码 → Plan
• 频繁跑命令 → Accept Edits

试试交互模拟，感受不同模式的区别：

Default 模式（推荐）

只读操作（读取文件、搜索代码、查看状态、列出文件）自动批准，修改操作（编辑文件、删除文件、运行命令、网络请求、Git push）需要确认。

权限弹窗选项：

• Yes：同意本次操作
• Yes, don't ask again for this tool：同意本次，且后续同类操作不再询问
• No, and tell AI what to do differently：拒绝并告诉 AI 换个方式

Plan 模式（代码审查）

仅允许只读操作，所有修改操作都会被阻止。

适用场景：

• 代码审查
• 了解代码库结构
• 探索性分析

::: tip Plan 模式深度解析

Plan 模式不只是"只读"——它是 Claude Code 内置的结构化规划流程，让 AI 在动手之前先充分理解代码库。

内部机制：

当你切换到 Plan 模式时，Claude Code 会：

1. 限制为只读工具——只能读取文件、搜索代码、浏览目录，不能编辑或执行命令
2. 深度探索代码库——自动遍历相关文件，理解架构和依赖关系
3. 输出结构化方案——包含修改哪些文件、每个文件改什么、执行顺序

何时使用 Plan 模式：

场景	是否推荐	原因
新功能涉及 3+ 文件	✅ 强烈推荐	避免改到一半发现遗漏
大规模重构	✅ 强烈推荐	需要全局视角
不熟悉的代码库	✅ 推荐	先理解再动手
架构决策（选型）	✅ 推荐	需要对比分析
单文件 bug 修复	❌ 不需要	直接修就行
简单文案修改	❌ 不需要	过度流程化

实战示例：认证模块从 Session 迁移到 JWT

# 先切换到 Plan 模式（Shift+Tab 切换）
"帮我把用户认证从 express-session 迁移到 JWT"

# AI 会自动：
# 1. 读取当前 auth 相关文件
# 2. 分析 session 的使用位置
# 3. 输出迁移方案（哪些文件要改、改什么、顺序）
# 4. 等你确认后，切回正常模式执行
​

Plan 模式 vs 口头说"先规划"：

口头说"先帮我规划一下"也能让 AI 输出方案，但 Plan 模式有本质区别：

• 工具级别的限制：Plan 模式下 AI 只能使用只读工具，确保规划阶段专注于分析
• 结构化审批：方案输出后由你审批确认，再切回正常模式执行
• 探索更充分：因为不能写，AI 会把更多 token 花在理解代码上

:::

编辑操作需要确认，其他操作自动批准。

# 示例行为
"读取配置文件"
"运行测试"
# AI 直接执行（非编辑操作）

"修改函数签名"
"删除这个文件"
# AI 会询问（编辑操作需确认）
​

适用场景：

• 需要频繁运行命令/测试
• 对文件修改要谨慎
• 高度信任的自动化工作流

模式切换

快捷键

Shift+Tab # 在三种模式间循环切换

常用交互命令

在 Claude Code 中，以 / 开头的命令称为斜杠命令，用于快速执行特定操作：

命令	功能	使用场景
/clear	清空对话上下文	开始新任务时
/model	切换 AI 模型	需要更强能力时切换到 Opus
/status	查看使用额度和计费	检查剩余额度
/config	打开配置界面	修改设置
/resume	恢复最近的会话	重启后继续之前的工作
/rewind	恢复到上一个检查点	代码改错需要回退
/agents	管理 Agent	创建/查看自定义 Agent
/init	生成 CLAUDE.md 模板	新项目快速配置
/compact	压缩对话上下文	上下文太多时精简
/export	导出对话记录	分享或保存对话
/statusline	自定义状态栏显示	隐藏/显示状态信息
/vim	启用 Vim 键绑定	熟悉 Vim 的用户

常用场景：

# 开新任务时清空上下文
/clear

# 查看剩余额度
/status

# 切换到更强模型
/model opus

# 恢复到之前的状态
/rewind
​

CLI 命令与启动选项

::: details 基本命令（必读）

命令	描述	示例
claude	启动交互式 REPL	claude
claude "query"	使用初始提示启动 REPL	claude "解释这个项目"
claude -p "query"	查询后退出（无头模式）	claude -p "检查代码类型错误"
claude -c	继续上一次对话	claude -c
claude -r "id"	恢复指定会话	claude -r "abc123"
claude --continue	加载最近的对话	claude --continue
claude --resume	显示会话选择器	claude --resume

:::

::: details 常用启动选项

选项	功能	示例
-p "query"	执行查询后退出	claude -p "运行测试"
--model	指定模型	claude --model opus
--permission-mode	设置权限模式	claude --permission-mode plan
--add-dir	添加工作目录	claude --add-dir ../shared

:::

::: details 快捷键与输入控制（必读）

快捷键	功能	上下文
Ctrl+C	取消当前输入或生成	标准中断
Ctrl+D	退出会话	EOF 信号
Ctrl+L	清除终端屏幕	保留对话历史
Ctrl+R	反向搜索命令历史	搜索以前的命令
Esc+Esc	回退代码/对话	恢复到之前状态
Tab	切换扩展思考	开启/关闭思考模式
Shift+Tab	切换权限模式	循环切换权限模式

多行输入方法：

快捷键	上下文
\ + Enter	适用于所有终端
Option+Enter (macOS)	macOS 默认设置
Shift+Enter	配置后可用

快速命令前缀：

前缀	功能	示例
#	内存快捷方式，添加到 CLAUDE.md	# 添加项目上下文
/	斜杠命令	/clear
!	Bash 模式，直接运行命令	! npm test
@	文件路径引用	@src/app/page.tsx

:::

::: details 进阶：高级 CLI 标志

完整 CLI 标志列表：

标志	描述	示例
--add-dir	添加额外工作目录	claude --add-dir ../apps
--agents	JSON 格式定义 Agent	claude --agents '{...}'
--allowedTools	允许的工具列表	claude --allowedTools "Read,Bash"
--disallowedTools	禁止的工具列表	claude --disallowedTools "Edit"
--system-prompt	替换整个系统提示	claude --system-prompt "..."
--system-prompt-file	从文件加载系统提示	claude -p --system-prompt-file ./prompt.txt
--append-system-prompt	附加到默认提示	claude --append-system-prompt "..."
--output-format	输出格式（text/json/stream-json）	claude -p --output-format json
--input-format	输入格式（text/stream-json）	claude -p --input-format stream-json
--verbose	启用详细日志	claude --verbose
--max-turns	限制轮数	claude -p --max-turns 3
--dangerously-skip-permissions	跳过权限提示	claude --dangerously-skip-permissions

系统提示标志区别：

标志	行为	模式	用例
--system-prompt	替换整个默认提示	交互 + 打印	完全控制行为
--system-prompt-file	替换为文件内容	仅打印	从文件加载
--append-system-prompt	附加到默认提示	交互 + 打印	添加特定指令

:::

::: details 进阶：Vim 模式

使用 /vim 启用或通过 /config 永久配置。

模式切换：

命令	操作	来自模式
Esc	进入 NORMAL 模式	INSERT
i	在光标前插入	NORMAL
a	在光标后插入	NORMAL
o	在下方打开行	NORMAL

导航（NORMAL 模式）：

命令	操作
h/j/k/l	左/下/上/右移动
w	下一个单词
b	上一个单词
0/$	行首/行尾
gg/G	输入开始/结束

:::

::: details 进阶：后台 Bash 命令

后台运行的工作原理：

• 异步运行命令，立即返回任务 ID
• 输出被缓冲，可用 BashOutput 工具检索
• Claude Code 退出时自动清理

常见后台命令：

• 构建工具（webpack, vite, make）
• 包管理器（npm, yarn, pnpm）
• 测试运行器（jest, pytest）
• 开发服务器

按 Ctrl+B 将常规 Bash 调用移到后台。

Bash 模式（! 前缀）：

! npm test
! git status
! ls -la
​

• 将命令和输出添加到对话上下文
• 显示实时进度
• 支持 Ctrl+B 后台运行

:::

::: details 进阶：Agent 配置格式

--agents 标志接受 JSON（通常不需要手动使用，/agents 命令会自动处理）：

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer",
    "prompt": "You are a senior code reviewer",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'
​

必需字段：

• description：何时调用（自然语言）
• prompt：系统提示

可选字段：

• tools：可用工具数组
• model：模型别名（sonnet/opus/haiku）

:::

五步工作流

::: tip 工作流是建议而非强制

VibeCoding 五步工作流是一个推荐的实践模式，适合大多数开发场景。但你可以根据实际情况灵活调整：

• ✅ 推荐遵循：复杂功能、不熟悉的项目、团队协作
• 可以简化：简单修改、熟悉的项目、个人开发
• ⚡ 可以跳过：微小改动、明显的问题修复

核心原则：理解每步的目的后，根据实际情况灵活应用，而非机械执行。

:::

交互式工作流演示 —— 点击每步查看详情：

1. 探索项目结构

先了解项目现状，能在 prompt 中给出更精准的上下文——比如"项目已有 Comment 表，请复用"、"代码风格参考 src/modules/posts"。上下文越明确，AI 的输出越贴合你的项目。

先探索，再动手：

"探索这个项目的结构，告诉我:
1. 使用的技术栈
2. 文件组织方式
3. 现有的功能模块
4. 配置文件的作用"
​

你会得到：

项目使用 Next.js 16 + TypeScript + Drizzle
- app/: 页面和 API
- components/: 可复用组件
- src/db/: 数据库模型（已有 User 表，可关联）
​

关键信息：已有 User 表 → 直接关联，省去建表 + 10 分钟。

2. 规划实现步骤

目的: 先想清楚再动手，减少返工

"我要添加用户评论功能。
请规划实现步骤，包括:
1. 需要创建哪些文件
2. 需要修改哪些现有文件
3. 数据库 schema 变更
4. 实现顺序"
​

输出示例:

步骤:
1. 更新 Drizzle schema (添加 Comment 模型)
2. 运行 npx drizzle-kit push
3. 创建 API route (app/api/comments/route.ts)
4. 创建评论组件 (components/CommentForm.tsx)
5. 集成到详情页
​

3. 编写代码

目的：按计划实现功能

AI 的自动拆分能力：

复杂任务会被自动拆解：

# 你只需要说
"实现用户评论功能"

# AI 会自动拆分为：
1. 更新 Drizzle schema
2. 运行数据库迁移
3. 创建 API 端点
4. 编写前端组件
5. 集成到页面
6. 测试验证
​

你不需要手动指定每个步骤，AI 会：

• 识别任务依赖关系
• 确定执行顺序
• 并行处理独立部分
• 验证每个步骤的结果

当然，你也可以分步执行：

"按照步骤 1，更新 Drizzle schema"
​

"按照步骤 2，生成并运行迁移"
​

"按照步骤 3，创建评论 API"
​

4. 测试验证

目的：确保功能正常

"测试评论功能:
1. 验证 API 能正常创建评论
2. 验证评论能正确显示
3. 验证错误处理"
​

5. 提交代码

场景：AI 改崩了代码，想回退

AI 为了修一个 Bug，改了 10 个文件，结果功能全乱了。你想回退，但发现没有存档点。

解决方案：让 AI 自动提交代码。

配置方法：在 CLAUDE.md 中添加：

"每当你完成一个独立功能的开发，或修复完一个 Bug 并验证通过后，请自动运行 git commit 提交代码，并生成一句简洁的中文 commit message。"

效果：

• AI 写完登录功能 → 自动 git commit -m "feat: 实现登录"
• AI 写完首页 → 自动 git commit -m "feat: 添加首页"
• AI 搞崩了代码 → git log 找到上一个版本，git reset 回退

自动提交 vs 检查点：

方式	能回滚什么	不能回滚什么	适用场景
检查点	AI 写入的文件	终端命令产生的变更	快速回退
Git 提交	所有已跟踪文件	未跟踪文件	重要里程碑

建议：两者都用。检查点用于快速试错，Git 提交用于重要节点。

6. 检查点功能

场景：代码改崩了，想回滚

你让 AI 重构代码，结果功能全乱了。按 Esc+Esc，选择之前的检查点，代码恢复。松了口气。

但注意检查点的局限：

你用 /rewind 回滚到早期版本，然后 ls 一看——

• index.html 恢复了 ✓
• node_modules/ 还在（AI 删不了）
• 数据库表也还在（AI 动不了）

原因：检查点只回滚 AI 写入的文件，终端命令（npm install、mkdir）产生的变更无法回滚。

正确姿势：

• 小改动 → 检查点快速回滚
• 大改动 → git commit 后再让 AI 动手

使用方法：
按 Esc+Esc 或 /rewind，选择：

• 仅对话：回退消息，保留代码
• 仅代码：恢复文件，保留对话
• 两者都恢复

::: details 进阶：检查点工作原理

自动跟踪：

• 每个用户提示创建新检查点
• 检查点在会话间持久存在
• 30 天后自动清理（可配置）

限制：

• Bash 命令更改（rm、mv、cp）无法回退
• 外部编辑无法回退
• 检查点用于快速恢复，Git 用于永久历史

:::

理解 Agent

什么是 Agent

Agent = AI 本身

AI 本身就是一个 Agent，它的工作是：

• 理解你的意图和需求
• 做决策（用什么工具、先做什么后做什么）
• 协调各种工具完成任务

可以把 Agent 理解为一个任务执行器：

• 接收你的指令（提示词）
• 调用各种工具完成任务
• 返回执行结果

与普通 AI 对话的区别：

普通 AI 对话	Agent
只能聊天	能调用工具
被动回答	主动决策
单轮交互	持续执行

什么是自定义 Agent

自定义 Agent = 你创建的专门 Agent

自定义 Agent 是主 Agent 可以调用的"专门助手"。每个自定义 Agent：

• 有特定的用途和专业领域
• 有独立的上下文窗口（不污染主对话）
• 有自定义的系统提示（专门训练）
• 可以限制工具访问权限

使用自定义 Agent 的优势：

优势	说明
上下文保留	主对话保持简洁，自定义 Agent 独立处理复杂任务
专业分工	针对特定任务优化（如代码审查、调试）
并行处理	多个 Agent 可同时工作，提高效率
灵活权限	可限制 Agent 只能用特定工具，提高安全性

Agent 类型：

类型	说明	示例
官方内置	系统自带，自动调用	Plan（计划模式专用）
用户自定义	你创建的专门 Agent	code-reviewer、debugger
通用 Agent	Task 工具调用的通用 Agent	general-purpose、Explore

::: tip 官方内置 Agent：Plan

Plan Agent 是 Claude Code 自带的专门 Agent，专门用于计划模式：

• 模型：使用 Sonnet 进行更强大的分析
• 工具：Read、Glob、Grep、Bash（代码库探索）
• 目的：搜索文件、分析代码结构、收集上下文
• 自动调用：在计划模式中研究代码库时自动使用

工作原理：

你：[在计划模式] 帮我重构认证模块
我：让我先研究一下你的认证实现...
[内部调用 Plan Agent 探索认证相关文件]
[Plan Agent 搜索代码库并返回发现]
我：基于研究，这是我的建议方案...
​

:::

创建自定义 Agent

使用 /agents 命令创建你自己的自定义 Agent。

第0步：在 Claude 内输入 /agents 回车

第一步：选择创建方式 (Creation Method)

这里决定了 Agent 的"大脑"（系统提示词）是如何生成的。

选项	含义	适用场景
Generate with Claude	让 Claude 帮你生成	90% 的情况推荐。用自然语言描述需求，Claude 自动转化为专业 Prompt
Manual configuration	手动配置	高级用户。已有写好的 Prompt，或需要精确控制每个字符

::: tip 快捷方式：直接对话修改

创建 Agent 后，你可以直接在对话中用 @agent名字 来修改或者使用它：

# 直接告诉 AI 你的需求
"@code-reviewer 以后检查代码时，特别关注安全性问题"

@翻译agent 把这段翻译成英文，但保持技术术语不变
​

AI 会自动更新 Agent 的配置，无需手动编辑配置文件。

:::

::: details 完整流程（第二步至最后一步）

第二步：选择底层模型 (Select Model)

这里决定了 Agent 运行时的"智商"、速度和成本。

选项	说明
Sonnet	平衡性能和速度
Opus	最强能力，成本较高
Haiku	最快速度，简单任务
Inherit from parent	继承父级模型，跟随主对话切换

第三步：选择工具权限 (Select Tools)

这里决定了 Agent 能干什么（安全管控的关键）。

选项	权限	适用场景
All tools	全权授权	需要完整能力的 Agent
Read-only tools	只读权限	代码审查、文档分析
Edit tools	编辑权限	修改代码、创建文件
Execution tools	执行权限	运行终端命令（风险最高）
MCP tools	外部工具	调用 MCP 服务器连接的服务

第四步：选择存储位置 (Choose Location)

这里决定了 Agent 在哪里可以被看见和使用。

选项	含义	适用场景
Project (.claude/agents/)	项目级私有	专门为当前项目服务的 Agent
Personal (~/.claude/agents/)	用户级全局	通用工具（翻译、发邮件等），随处可用

第五步：选择背景颜色 (Choose background color)

纯视觉设置，用于在终端里区分不同的 Agent。建议按功能分类：

• 红色：危险操作（删除文件）
• 蓝色：辅助查询
• 粉色/紫色：创意写作

最后一步：确认并保存 (Confirm and save)

按键	操作
s 或 Enter	保存并创建
e	保存后立刻进入编辑器（微调 Prompt）
Esc	放弃创建

:::

多 Agent 并行协作

::: tip 什么是多 Agent 协作

Claude Code 会自动启用多 Agent来并行处理独立任务，每个 Agent 有独立的上下文窗口，专注完成特定工作。

两种方式：

1. 自动并行：我识别到独立任务，自动创建通用 Agent 并行处理
2. 专门协作：调用你创建的自定义 Agent（如 code-reviewer）

:::

自动启用

Claude Code 根据任务描述主动委派任务，使用 Task 工具创建通用 Agent 并行处理：

• 任务描述中的关键词："并行"、"同时"、"多 Agent"
• 自定义 Agent 配置中的 description 字段
• 当前上下文和可用工具

::: tip Task 工具

当 Claude Code 识别到独立任务时，会自动使用 Task 工具创建通用 Agent 来并行处理。

通用 Agent vs 自定义 Agent：

类型	调用方式	用途
通用 Agent	Task 工具自动创建	通用任务（探索、搜索、读取文件）
自定义 Agent	/agents 命令创建	特定领域（代码审查、调试、测试）

特点：

• 处理大量文件读取和搜索时更高效
• 多个通用 Agent 可以并行工作，加快速度
• 不需要预先配置，Claude 自动创建

:::

多个并行 Agent

关键词	效果
"并行"	同时执行多个独立任务
"同时"	多个 Agent 一起工作
"多 Agent"	明确使用多个 Agent 协作

::: info 并行能力说明

Claude 的并行能力：

在单个响应中，Claude 可以并行调用多个独立工具或子代理（具体数量取决于任务复杂度和上下文窗口剩余空间）。

这意味着如果你有多个独立的任务（比如同时读取多个文件、执行多个独立的搜索等），Claude 可以在一条消息里一次性发出所有请求，大大提高效率。

举例 1：并行调研多个技术文档

任务：了解 Prisma、Drizzle、Supabase 三种数据持久化方案

串行方式：
读 Prisma 文档 → 等待 → 读 Drizzle 文档 → 等待 → 读 Supabase 文档 → 等待 → 总结对比

并行方式：
1 个消息 → 同时发起 3 个文档调研请求 → 收集所有信息 → 生成对比报告
​

举例 2：并行编写多个相关组件

任务：开发用户设置页面的多个功能模块

串行方式：
写头像上传 → 等待 → 写密码修改 → 等待 → 写通知偏好 → 等待 → 集成测试

并行方式：
1 个消息 → 同时启动 3 个 Agent 分别编写 3 个模块 → 收集所有代码 → 统一集成测试
​

最佳实践：

• 确保任务之间没有依赖关系
• 在提示词中使用"同时"、"并行"等关键词
• 让 Claude 自动识别哪些任务可以并行

:::

使用示例

# 自动并行 - AI 自动识别独立任务
"同时做这三件事：
1. 编写后端 API（用户认证）
2. 编写前端 UI（登录表单）
3. 编写数据库 schema（User 表）"

# 明确使用多 Agent
"使用多 Agent 并行开发任务模块：
- Agent 1 做 CRUD API
- Agent 2 做任务列表和表单
- Agent 3 做 Task 数据模型"
​

::: tip Agent 团队与多视角分析

除了简单的并行任务，Claude Code 还支持更高级的 Agent 团队模式和多视角分析模式。

Agent 团队模式

让不同专业的 Agent 协作完成复杂任务，每个 Agent 专注自己的领域：

简单并行 vs Agent 团队：

维度	简单并行	Agent 团队
任务关系	完全独立	有协作关系
典型场景	同时读 5 个文件	架构师+前端+安全联合评审
结果处理	各自返回	汇总整合
提示词	"同时做 A、B、C"	"从 X、Y、Z 角度分析"

多视角分析模式

对同一段代码或决策，从多个专业角度同时分析：

"从以下角度分析这个 API 设计：
1. 安全性：是否有注入风险、认证漏洞
2. 性能：N+1 查询、缓存策略
3. 可维护性：命名规范、职责划分
4. 向后兼容：API 版本策略"
​

适用场景：

场景	推荐视角组合
代码审查	安全 + 性能 + 可读性
技术选型	成本 + 生态 + 学习曲线 + 扩展性
重构决策	风险 + 收益 + 工作量 + 影响范围
Bug 排查	复现路径 + 根因 + 影响面 + 修复方案

自定义 Agent 配置

你可以在项目中创建专属 Agent，让 Claude Code 在特定场景自动调用：

# 创建自定义 Agent（放在 .claude/agents/ 目录）
# 例如：security-reviewer.md
---
name: security-reviewer
description: 安全审查专家
model: sonnet
tools: [read, grep, glob]
---

你是一个安全审查专家。检查代码中的：
- SQL 注入
- XSS 漏洞
- 硬编码密钥
- 不安全的依赖
​

然后在对话中通过 Task 工具调用这些 Agent，实现团队化协作。

:::

两个选项：

• --continue：自动继续最近的对话
• --resume：显示对话选择器

使用示例：

# 继续最近的对话
claude --continue

# 使用特定提示继续
claude --continue -p "显示我们的进度"

# 显示对话选择器
claude --resume

# 非交互模式继续
claude --continue -p "再次运行测试"
​

工作原理：

1. 对话自动保存在本地
2. 恢复时加载完整消息历史
3. 工具状态和结果被保留
4. 上下文完整恢复

:::

::: details 进阶：并行会话与 Git Worktrees

使用场景：同时处理多个任务，完全隔离代码

创建 worktree：

# 使用新分支创建
git worktree add ../project-feature-a -b feature-a

# 使用现有分支创建
git worktree add ../project-bugfix bugfix-123
​

在每个 worktree 中运行 AI：

cd ../project-feature-a
claude
​

管理 worktrees：

# 列出所有 worktrees
git worktree list

# 删除 worktree
git worktree remove ../project-feature-a
​

优势：

• 每个工作目录完全隔离
• 更改不会相互影响
• 共享相同的 Git 历史

:::

::: details 进阶：Unix 风格实用程序用法

添加到验证流程：

// package.json
{
  "scripts": {
    "lint:claude": "claude -p '你是 linter。检查 vs main 的更改，报告拼写错误。每行一个文件名和行号，第二行描述问题。不返回其他文本。'"
  }
}
​

管道输入输出：

# 管道数据
cat build-error.txt | claude -p '简明解释构建错误的根本原因' > output.txt

# 控制输出格式
cat data.txt | claude -p '总结数据' --output-format text > summary.txt
cat code.py | claude -p '分析代码 bug' --output-format json > analysis.json
cat log.txt | claude -p '解析日志错误' --output-format stream-json
​

输出格式：

• text：纯文本响应（默认）
• json：完整对话日志的 JSON 数组
• stream-json：实时 JSON 对象流

:::

人在环路

AI 能够自主完成很多任务，但以下场景建议保持人工审查：

场景	原因	建议做法
生产环境部署	影响所有用户	AI 生成方案，人工审核后执行
数据库结构变更	难以回滚，影响数据	先 review schema，再执行迁移
安全相关代码	漏洞后果严重	代码审查必不可少
支付/财务逻辑	涉及资金安全	测试+双人验证
性能关键路径	影响用户体验	性能测试+基准对比
API 兼容性变更	影响第三方集成	版本管理+通知机制

::: warning 小白提示

如果你是编程新手，遇到上述场景不确定如何处理：

1. 不要独自承担风险

   • 在测试环境先验证
   • 让 AI 解释风险点和注意事项
   • 在技术社区寻求帮助

2. 渐进式信任

   • 从简单任务开始让 AI 自主完成
   • 复杂/高风险任务逐步增加人类审查
   • 建立 checklist 确保关键点都被检查

3. 寻找帮助的途径

   • 技术社区（Stack Overflow、GitHub Issues）
   • 让 AI 解释风险点："这样做有什么风险？"
   • 付费咨询有经验的开发者

:::

::: details 需要人工审查的信号

AI 建议时保持警惕：

• AI 说"可能破坏XXX"
• AI 建议删除大量代码
• AI 修改核心配置文件
• AI 建议重构核心模块

操作建议：

1. 要求 AI 解释改动原因
2. 检查受影响的文件列表
3. 考虑先在分支测试
4. 必要时寻求第二意见

:::

Hooks 自动化

::: tip 什么是 Hooks

Hooks = 在特定事件时自动执行的 Shell 命令

当 Claude Code 触发某些事件（如工具调用、用户提交提示）时，可以自动执行你注册的脚本命令。

常见用途：

• 代码写完后自动格式化（运行 prettier/eslint）
• AI 要删除重要文件时先拦截确认
• 提交代码前自动运行测试

:::

::: warning 安全提示

Hooks 会以你的用户权限执行 Shell 命令，配置前请理解它在做什么。

新手建议：

• 从简单场景开始（如自动格式化）
• 复杂场景寻求有经验的人帮助
• 只使用可信来源的 Hooks

:::

使用 Hooks

运行 /hooks 打开交互式配置界面，这是最推荐的创建方式。

配置流程：

1. 选择 Hook 事件类型：

   • PreToolUse - 工具调用前
   • PostToolUse - 工具调用后
   • PostToolUseFailure - 工具执行失败后
   • Notification - 发送通知时
   • UserPromptSubmit - 用户提交提示时（推荐）

2. 配置 Hook 行为：

   • 选择触发条件（matcher）
   • 编写执行的 Shell 命令
   • 设置超时时间（默认 60 秒）

3. 保存并生效

::: info 重要说明

• 每个事件可注册多个 Hooks，并行执行
• /hooks 目录外的修改需要重启才能生效
• 超时时间：60 秒
• 权限：以你的完整用户权限执行

:::

常用场景

场景	事件	触发时机	执行命令
自动格式化	PostToolUse	Write/Edit 后	prettier --write $FILE
保护敏感文件	PreToolUse	要修改 .env 时	拦截并警告
运行测试	UserPromptSubmit	提交包含"测试"的提示时	npm test
添加上下文	UserPromptSubmit	每次提交提示前	自动加载项目信息

::: details 进阶：配置文件说明

注意：以下内容仅供参考，一般不需要手动编辑配置文件。

配置位置（优先级从高到低）：

• .claude/settings.local.json - 本地项目设置（不提交）
• .claude/settings.json - 项目设置
• ~/.claude/settings.json - 用户全局设置

常用事件对照：

事件	触发时机	典型用途
PreToolUse	工具调用前	验证、修改输入、权限控制
PostToolUse	工具调用后	格式化、通知、验证结果
PostToolUseFailure	工具执行失败后	错误处理、回滚操作
Notification	发送通知时	自定义通知渠道、记录日志
UserPromptSubmit	用户提交提示时	验证提示、添加上下文
Stop	主代理完成响应时	最终检查、清理、记录统计

:::

::: details 实用示例

自动格式化

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{
          "type": "command",
          "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/format-code.sh"
        }]
      }
    ]
  }
}
​

除了执行命令（type: "command"），还可以用 LLM 做智能决策（type: "prompt"）。

适用场景：需要理解内容后再决定是否放行。

敏感文件保护

#!/usr/bin/env python3
# .claude/hooks/protect-files.py

import json, sys

data = json.load(sys.stdin)
path = data.get('tool_input', {}).get('file_path', '')

# 阻止写入敏感文件
if any(p in path for p in ['.env', '.key', '.pem']):
    print("受保护：不允许写入敏感文件", file=sys.stderr)
    sys.exit(2)
​

:::

::: details 进阶：Hook 输入输出格式

输入（通过 stdin 接收 JSON）：

{
  "session_id": "会话ID",
  "cwd": "当前工作目录",
  "hook_event_name": "事件名称",
  "tool_name": "工具名称",
  "tool_input": {...}
}
​

输出方式：

• 退出代码：0=成功，2=阻止操作
• JSON 输出：可返回 decision、reason 等字段

:::

安全注意事项

::: warning 安全注意事项

不要把敏感信息发送给 AI：

• ❌ API 密钥、密码
• ❌ 生产数据库连接字符串
• ❌ 用户隐私数据

使用环境变量：

# .env 文件（不要提交到 Git）
DATABASE_URL="postgresql://..."
OPENAI_API_KEY="sk-..."

# .gitignore
.env
​

不要让 AI 修改敏感配置文件：

• 项目根目录的 .env
• SSH 密钥
• 生产环境配置
  :::

核心理念

Workflow 让 AI 开发可预测、可复现。

记住工作流五步曲：探索 → 规划 → 执行 → 验证 → 提交（根据情况灵活应用）

::: tip 灵活应用

• 复杂任务：严格遵循五步，减少返工
• 简单修改：可以跳过探索，直接执行
• 紧急修复：最小化流程，快速解决

关键是有意识地思考每一步是否需要，而不是机械执行。

:::

提示词自检清单

发送提示词前检查：

• 任务描述清晰具体
• 提供了必要的上下文
• 明确了输出格式
• 给了 AI"不确定"的出口
• 包含了必要的约束条件
• 避免了冗长的角色设定
• 没有包含敏感信息（API Key、密码等）

常见问题

Q1: 提示词越长越好吗？

A: 不是。

提示词的质量在于精确，不在于长度。

简洁但具体的提示词 > 冗长但模糊的提示词

Q2: AI 还是会编造答案怎么办？

A: 加强约束：

"只使用项目已有的依赖。
如果需要新功能，先告诉我。
不要编造不存在的 API。"
​

Q3: 为什么不直接让 AI 写代码？

A: 直接写容易返工。

探索 → 规划 → 编写，这个流程能让你：

• 避免重复造轮子
• 发现潜在问题
• 保持代码风格一致

Q4: 工作流会不会太慢？

A: 不会。

看似多了步骤，实际上减少了返工时间。整体效率更高。

对比：

• 直接写：10 分钟，返工 30 分钟
• 按流程：15 分钟，一次通过

Q5: 什么时候该停止对话？

A: 信号：

• 连续 3 轮没有进展
• AI 开始重复相同的建议
• 问题需要更多信息（如查看生产环境日志）

策略：切换模型或换思路

相关内容

• 详见：2.3 MCP、插件与 Skills
• 详见：2.4 项目规则配置
• 前置：2.1 AI 编程的经济学
• 后续：2.5 高效调试心法