AI 编程工作流怎么落地

0030 秒速览：三句话，然后按你的处境直接跳

读完这一篇，你能做三件事：给 AI 派活时写出一份它不会理解错的说明书；用四道硬度不同的"闸门"确认它真的做完了；并且认出哪三类任务你根本不该走这套流程。

按你现在的处境，直接看这一节

一条可执行的上手路径（今天就能跑完）

读完你应该能

01它到底是什么：三个常见的错想，先破掉

一句话定义：AI 编程工作流就是你和 AI 代理（AI agent——能自己读文件、改文件、敲命令的 AI 程序）协作时，从接到任务到交付代码所遵循的一套固定顺序。它不是某个软件，装了就有；它是你这一侧的做事顺序。

它是"做法"而不是"对象"，所以它没有版本号、没有安装命令。同一个 Claude Code，配合这套顺序能产出可以合并的代码；不配合，就产出一堆需要你重写的东西。

01.1 错想一：它是"让 AI 自己跑"的自动化

恰恰相反。这套流程里最花时间的几件事全是你在做：写清楚要什么、判断它给的方案对不对、决定什么算做完。AI 承担的是中间那段——读代码、写代码、跑命令。

分工说得再清楚一点：你负责定义意图和验收标准，AI 负责写码和自检。它不是"把活全丢出去"，而是"把脑子留在自己这里，把手交出去"。

01.2 错想二：它是提示词技巧，多写几个字就完了

提示词技巧管的是这一次怎么问；工作流管的是一轮一轮怎么推进。你可以每句话都问得很漂亮，但如果不检查产出、不设验证、不沉淀经验，下一轮照样从零开始。

更准的区分：提示词是单次动作，工作流是带检查点的循环。检查点才是重点——它保证错误不会一路滑到线上。

01.3 错想三：它只适合大项目、只适合某种工具

流程是跨工具的。下面这些工具都能承载同一套五阶段，差别只在"操作方式"（按哪个键进计划模式、规则文件叫什么名字），不在于"要不要按流程来"：

反过来说也成立：流程对了，工具差一点你也能干活；流程不对，换最贵的模型也救不回来。模型是容易换的那部分，顺序是你自己的。

01.4 它的五个阶段（官方写的是四个）

Anthropic 的官方文档把推荐工作流写成四个阶段：Explore（先摸清现状）→ Plan（订计划）→ Implement（实现）→ Commit（提交）。其他来源的名字和颗粒度不同，但骨架一致。本文把它整理成五个，因为"验证"在官方四阶段里是隐含的，而它恰好是新手最容易跳过的一步，值得单独拎出来当一段：

01.5 什么时候别用它：三种场景，直接做反而更好

这是本篇最该被认真读的一段。工作流有成本——写任务卡、等计划、跑验证，每一步都要花你的注意力。当成本明显大于返工风险时，用它就是自找麻烦。

01.6 一张表看清它和近邻做法的差别

01.7 没有它的时候，你实际在经历什么

很多人以为自己缺的是"更强的模型"，其实缺的是检查点。下面的对比不是修辞，是两种流程产生的两种工作量分布：

# 一条消息就想让 AI 输出完整功能
帮我做一个用户登录系统

# 结果：AI 忘了密码加密、没做输入校验、把数据库连接硬编码进去了——你拿到手才发现要重写。

# 1. 先定义"完成"的标准
任务：用户登录系统
约束：JWT 认证、bcrypt 密码哈希、限流
验证：跑测试套件通过

# 2. 让 AI 出计划 → 审核 → 分步实现
# 结果：AI 每一步都知道"完成"是什么，你只在关键节点把关。

02动手前必须先有的东西：一条命令，两个文件

这套流程需要三个前置条件。缺任何一个，后面每一节都会卡住。好消息是三个都很小，半小时内能补齐。

02.1 前置一：一条"能告诉你对不对"的命令

你需要至少一条命令，跑完给你一个明确的通过或不通过。它是什么不重要，常见的是这几种：

# 跑测试套件（Node.js 项目的常见写法，具体看 package.json 里的 scripts）
npm test

# 类型检查：只检查、不生成文件
npx tsc --noEmit

# 代码风格检查
npm run lint

# 跑单个测试文件（改哪里测哪里，比每次全跑快得多）
npm test -- src/orders/order.test.js

为什么这条命令如此关键：它是整套流程里唯一一个"不需要谁相信谁"的信号。AI 说完成了，你可以不信；命令的退出码是 0 还是非 0，你没法争辩。

02.2 前置二：项目记忆文件

这是 AI 每次开工自动读的一份说明，装着"它猜不出来、但必须知道"的项目约定。不同工具认的文件名不同，跨工具的通用约定是 AGENTS.md（见 agents.md）；Claude Code 则读 CLAUDE.md。

这里有个坑要提前知道：Claude Code 读的是 CLAUDE.md，不是 AGENTS.md。如果你的仓库已经有 AGENTS.md 给别的代理用，官方给的做法是让 CLAUDE.md 把它导进来，两边共用同一份内容，避免复制两份：

# CLAUDE.md 里写一行，把 AGENTS.md 的内容导进来
@AGENTS.md

# 或者在 macOS / Linux 上直接建软链接（symlink），让两个名字指向同一个文件
ln -s AGENTS.md CLAUDE.md

Claude Code 也提供了生成器：跑 /init 会让你先审一份它分析代码库后写出来的草稿，而不是直接覆盖你已有的文件。文件写好后跑 /context 可以确认它真的被读进去了。

02.3 前置三：一个能回退的干净起点

开工前把当前状态提交一次，让"回到原点"永远是一条命令的事。AI 改坏了你不需要跟它争论，直接回退再换说法。

# 开工前：把当前状态存成一个还原点
git add -A && git commit -m "开工前的检查点"

# 想先看 AI 改了哪些地方、改了多少
git diff --stat
git diff

# 改坏了，丢掉未提交的改动，回到还原点
git checkout -- .
git reset --hard HEAD

# 工作树：为并行任务开一个独立目录，各自一个分支
git worktree add ../myproject-feature-a -b feature-a

# 用完清理
git worktree remove ../myproject-feature-a

02.4 准备度自检：三格都能打勾再往下看

03规划：怎么把话交代清楚，让 AI 不用猜

这一节解决新手最痛的问题：话该怎么说。规则只有一条——把"做什么、不做什么、怎么证明做完了"写成 AI 不需要猜的形式。

03.1 任务卡模板：五格，照抄

下面这份模板可以直接复制，把方括号里的内容换掉。它按五格组织，每一格都对应一种 AI 容易猜错的东西：

任务：[一句话说清要做什么。不要用"更好""优化"这类形容词]

背景：
- 技术栈：[框架 / 语言 / 数据库]
- 相关文件：[关键文件路径，说明它们是干什么的]
- 现状：[现在是怎么工作的，你要改成什么样]

要做的：
1. [具体动作一]
2. [具体动作二]
3. [具体动作三]

不要做的：
- 不要 [最容易顺手做但你不想它做的事，比如改数据库结构]
- 不要引入新的依赖

验证方式：
- 运行 [确切的命令]
- 确认 [具体的行为]

完成标准：
- [哪些条件全部满足才算完]

五格各自防的是哪一种猜错，值得分开看一眼：

对照着看，差别很直观：

❌ "做个更好的搜索"

✅ "在产品列表页添加按价格排序的筛选器，默认升序，改完跑 npm test 全部通过"

其中四格还可以再短一点——它们本来就是一行标签加一句具体内容，所以你甚至只写这四行就发出去（下面这四条是本文 03.2 那个订单通知任务的原文）：

边界：不要修改现有的订单数据库结构，不要引入新的邮件服务提供商
验证：运行 npm test 且全部通过，并确认邮件发送函数被正确调用
约束：复用现有的 EmailService（src/services/email.js），不新建邮件客户端
完成标准：所有测试通过、lint 干净、发送失败有重试

03.2 五格分别怎么写：一个真实任务

假设你要给一个现有的 Node.js 电商项目加"订单邮件通知"。五格填出来是这样（下面这份原样粘给 AI 就能用）：

任务：为现有的电商订单系统添加邮件通知功能

背景：
- 项目用 Node.js + Express + PostgreSQL
- 订单创建后需要发邮件通知用户
- 已有 EmailService 类（见 src/services/email.js）

要做的：
1. 在订单创建流程中调用邮件通知
2. 邮件模板：订单确认（用户名、订单号、总额）
3. 失败时重试 2 次

不要做的：
- 不要修改现有的订单数据库结构
- 不要引入新的邮件服务提供商

验证方式：
- 运行测试套件 npm test
- 确认邮件发送函数被正确调用

完成标准：
- 所有测试通过
- 错误处理覆盖发送失败场景

逐格看它为什么这么写：

03.3 为什么"先写完成标准"比"先写代码"重要

因为没有完成标准的任务，AI 的产出永远是"差不多"。它会给你一个能跑但漏了错误处理、或者实现了你没要的功能的版本，而你没有依据说它不对。

一个可用的检查法：把"验证"那一格单独拿出来读。如果你不能用它判断一个陌生人的代码是否合格，说明它还不够具体。"测试通过"不如"npm test 全绿，且新测试断言邮件函数被调用"。

顺序上还有个反常识的地方：先写验证，再写要做的。因为"怎么证明做完了"往往比"要做几件事"更能暴露你其实没想清楚——如果连怎么验证都写不出来，这个任务大概还不该开工。

03.4 计划模式（Plan Mode）到底怎么用

计划模式是 AI 编程工具的一种只读状态：AI 只能读文件、向你提问、写一份计划，不能改任何代码，直到你批准。它的全部价值就是"在你同意方向之前，一行代码都不会被写"。

Claude Code 里的确切操作（照抄官方文档）：

# 方式一：进入会话后按 Shift+Tab，直到状态栏显示这行字
⏸ plan mode on

# 方式二：启动时就以计划模式开始
claude --permission-mode plan

# 想直接改它的计划：按 Ctrl+G 把计划在编辑器里打开，改完再批准
Ctrl+G

计划模式下值得用的两句提示词（取自官方文档的示例，可直接粘）：

读 src/auth 目录，搞清楚我们现在的会话和登录是怎么处理的。
顺便看一下环境变量里的密钥是怎么管理的。

我想加 Google OAuth。哪些文件需要改？会话流程会变成什么样？给我一份计划。

批准计划之后，用一句话把"实现 + 验证"绑在一起：

按你的计划实现 OAuth 流程。给回调处理函数写测试，跑测试套件，修掉所有失败项。

03.5 比任务卡更重的一种做法：先写规格

任务卡是"一个任务一张"，规格（spec，一份一页纸的说明文档）是"一次改动一张"。规格驱动开发（Spec-Driven Development，SDD）的核心主张是：先把要什么写成一页纸，再让 AI 从这一页派生计划和代码；代码是产物，规格才是那个真正该被维护的东西。

什么时候值得升到规格？判据是这件事会不会跨越多个会话或多人。一张任务卡在单次会话里够用；一旦要隔天接着做、或者别人接手，口头共识就会掉——这时写成一页纸。

规格里该有什么（一页纸够，不要写成详细设计）：

# 规格模板：一页纸，写成文件放进仓库

## 用户故事
作为 [谁]，我希望 [做什么]，以便 [得到什么]。

## 验收标准
- [ ] [一条一条能打勾的行为，不要写"性能好"这类形容词]

## 边界情况
- 输入为空怎么办
- 权限不足怎么办
- 重复提交怎么办

## 明确排除的范围
- 这次不做：多语言邮件模板
- 这次不做：短信通知

## 未解决的疑问
- [ ] [写下来还没定的事，而不是装作定下来了]

写完之后有一件高价值的事，只有 AI 做得又快又好：让它先找缺口。这句提示词建议直接抄：

读这份 spec。它有哪些模糊的地方？哪些验收标准没法客观判断？
哪些边界情况没覆盖？把疑问列出来，先不要写代码。

它的价值在于：规格里的一个模糊点，就是实现阶段的一次返工。把疑问在上游暴露出来，比在下游改代码便宜得多。

03.6 项目记忆该放什么：一份真实的规则文件

项目记忆文件装的是"AI 读代码猜不出来的约定"。官方文档给的正反清单很实用，照它取舍：

一份能直接用的小样例（官方文档给的形态，换成你自己的内容）：

# CLAUDE.md

# 代码风格
- 用 ES modules（import/export）语法，不用 CommonJS（require）
- 导入尽量解构：import { foo } from 'bar'

# 工作流
- 做完一批代码改动后一定要跑类型检查
- 平时优先跑单个测试文件，不要每次跑整个测试套件（太慢）

# 已知陷阱
- 金额一律走 src/utils/format.js 的 formatMoney，不要自己写 toFixed
- 不要直接改 prisma/schema.prisma 后忘记跑迁移

04执行：怎么让 AI 动手，而且每一步都收得住

计划过了，进入写代码。这一节只解决一件事：让每次改动小到你能一眼看懂、坏了能一步退回。

04.1 为什么一次不要超过 200 行

因为瓶颈是你的审阅能力，不是 AI 的输出能力。AI 一次给你一千行，你只有三个选择：全信、全不信、或者花三小时逐行读——前两个不对，第三个不划算。

把它拆小的另一个好处是：你能理解它写的代码。这一点常被忽略——如果你不理解自己仓库里的代码，下一个 bug 会由你付账。

一个可执行的拆法：按"能单独验证"切，不按"文件"切。一次改动如果能单独跑一次测试并看到结果，它就是一个合适的颗粒度。200 行是经验值，真正的判据是"我能不能一次把它看完"。

04.2 猴子模式 vs 教练模式

这两种模式的区别不在工具，在你给指令的精确度：

❌ "帮我重构这个模块"

✅ "在 UserService.ts 第 45-60 行添加 email 字段校验，用已有的 validator 库"

04.3 上下文分三层，别一次全倒给它

"上下文"（context）就是 AI 这一次能看到的全部信息。并不是越多越好——塞太多无关内容，它会开始抓错重点。按三层组织最省事：

04.4 指定读哪些文件，比让它自己找效果好

现代 AI 代理都能自己翻文件系统，但翻的顺序和范围直接决定输出质量。一个反直觉但有效的做法是：你主动点名文件，并且说出为什么读它。

我点名几个文件，说明一下为什么要读：

- src/models/order.js —— 它定义了订单的数据模型，你要在这个结构上工作
- src/routes/order.js —— 这是你要扩展的路由实现
- tests/order.test.js —— 新测试要加在这里，先看现有测试怎么写的

读完这三个文件再动手，不要先去看仓库里其他部分。

最后一句很重要：加一句范围限制，否则它会出于"负责任"把整个仓库都翻一遍，既慢又容易跑偏。

04.5 让 AI 自己跑验证，一次都别省

这是执行阶段最值钱的一个习惯：不要只说"帮我实现这个功能"。把验证绑在同一句话里：

实现这个功能，然后运行 npm test，让所有测试通过。
如果失败，读错误日志、修复、再跑，直到全绿。
最后把命令和输出原文贴给我。

官方文档的表述是：给 AI 一个它能自己跑的检查，是"你在旁边盯着"和"你可以离开"之间的区别。它自己能闭环，你就不用守在那儿。

还有一句要加上——要求它给证据，而不是下结论：

不要告诉我"已完成"。给我三样东西：
1. 你运行的完整命令
2. 命令的输出原文（不要摘要）
3. git diff --stat 的结果

04.6 多个任务同时开工时怎么不乱

想同时推两件事的时候，别在同一份工作区里交叉进行——两个任务的文件改动会互相污染，你会分不清哪行是谁改的。三种开法，按隔离程度递增：

05验证：怎么确认它没在骗你

这一节是整篇文章的重心。跳过规划你会白干一次；跳过验证，你会把白干过的东西发到线上。

05.1 为什么"它说完成了"不能算证据

因为语言模型输出的是一段"看起来最像答案"的文字，不是对现实世界的检查结果。它无法区分"这个测试通过了"和"这个测试应该会通过"——除非你真的让它去跑。

更麻烦的是，它的语气不会随把握程度变化：猜错的时候和猜对的时候一样自信。于是你会遇到这种局面——它产生错误改动的速度，比你能发现错误的速度还快。这不是模型不行，是你装了一台没有刹车的加速器。

05.2 四层验证：从最便宜到最贵

不要一上来就人工逐行读代码——那是最贵的一层，应该留到最后。按这个顺序往上走，多数问题会在前两层被拦住：

前三层的具体命令形态：

# 第一层：测试。让 AI 跑，失败就让它读日志修，循环到全绿
npm test

# 如果失败：AI 读取错误日志并修复，重复直到所有测试通过

# 第二层：类型检查（TypeScript 项目）
npx tsc --noEmit

# 第三层：风格检查
npm run lint

# 第四层之前先看范围：只改了该改的地方吗？
git diff --stat

第四层人工审阅有个省力的技巧：只看 git diff，不要重读整个文件。你要回答的问题只有三个：它改了该改的地方吗？有没有夹带你没要的改动？边界情况处理了吗？

05.3 前三层都绿了还是有 bug：说明闸门漏了

这不是"验证没用"，而是你的闸门没有覆盖到那条路径。两种补法，按优先级：

05.4 错误信息该怎么喂回去

这是新手最容易做错的一步。"它不工作了"对 AI 等于零信息，它只能猜，猜错你就更生气，然后进入死循环。

一个可以直接粘的排查句式：

这个页面点击提交按钮后报错：TypeError: Cannot read property 'id' of undefined（来自 src/utils/validate.js 第 12 行）。
期望行为：邮箱格式不对时应该提示错误并留在当前页。
请先排查根本原因，不要先加 try/catch 掩盖它。修完跑相关测试确认。

注意最后两句话："先找根本原因"和"用测试确认"。少了它们，AI 最常见的反应是加一层错误捕获把报错藏起来——报错消失了，bug 还在。

05.5 调试 AI 代码的四种手法

四句话都可以直接抄：

把整个项目塞过去之前，先帮我把问题隔离成最小的一段。

逐行解释这个函数的执行过程，每一步告诉我 X 的值。

报错原文是：[贴完整报错]。请从这个报错出发定位，不要猜。

现在换个身份：你是审查者。审查你刚才写的这段代码，找出 bug、边界情况和你自己的假设。

05.6 重构为什么是最危险的一种改动

重构（refactoring——改变代码的内部结构，但不改变它的外部行为）是这套流程里最容易悄悄出事的一类任务：AI 会在"整理"的过程中顺手改掉一个行为，而测试没覆盖到那里，于是这个改动一路滑到线上。

一个可以直接照抄的四步做法：

# 1. 让 AI 先理解现有代码
解释 src/services/payment.js 的整体结构和数据流

# 2. 在 Plan Mode 下提出重构计划
把支付服务拆分为 3 个函数，提取错误处理，保持行为不变

# 3. 用测试做安全网
跑现有测试确保全部通过 → 重构 → 再跑测试

# 4. 逐文件验证
每改一个文件就确认一次，不一次性改所有文件

05.7 计划里最该看的不是步骤，是"风险"那一段

把 03.2 那份订单通知任务卡发给 AI，它读完文件后通常会回这么一份计划。注意最后那一条——那才是你真正要看的东西：

# AI 的计划（你审核这一步）
1. 在 src/orders/orderService.js 中添加 notifyUser 函数
2. 在 src/controllers/orderController.js 的 createOrder 中调用
3. 在 tests/order.test.js 中添加邮件发送的测试用例

风险：
- 修改了 orderController 的返回值格式，需要确认前端兼容

为什么风险那一段比三步计划更有价值：步骤只说明它打算动哪些文件，风险才说明它意识到哪里可能改坏。上面这条风险指向一个真实问题——接口返回值格式变了，调用它的前端页面会跟着坏，而项目里的测试很可能覆盖不到前端。看到这类提示，你的动作不是批准，而是先回答它：

关于返回值格式：请不要改现有的返回结构，只把邮件通知加在副作用里。
前端不在这个仓库里，改了格式我这边没法验证。

反过来，如果它给的计划里只有"1. 实现 2. 测试 3. 完成"这种空壳，没有任何具体文件名和风险，那说明它没真的读代码——退回计划模式，让它先读文件再出计划。

05.8 陷入"修了又坏"的死循环时怎么办

先认出一个信号：同一个报错反复出现、或者每修一处就冒出新的一处，而且已经超过两三轮。这时候继续调不是坚持，是沉没成本在推着你走。

判断该退到哪一层，有一张简单的对照：

# 错误做法：反复让 AI 改
AI: "修复了" → 测试失败 → "再改" → 又失败 → 死循环

# 正确做法：停下来，回到规划阶段
1. 停止当前 agent
2. 问自己：方向对吗？方法本身有问题吗？
3. 回到规划阶段，重新审视需求定义
4. 修正方向后再重新开始

06沉淀：怎么让下一次不用从头解释

这是被跳过最多的一个阶段。多数人的循环是：提需求 → 写代码 → 测试 → 收工 → 下一个任务。缺的那一步是：把这次的教训变成下次自动生效的规则。结果是每次从零开始，同一个坑反复踩。

06.1 为什么这一步的收益最晚才看得见

因为它是唯一有复利的一步。任务本身只完成一次，而规则会在此后每一次会话里生效。第一天你可能觉得"写这一行有什么用"，第三周你会发现 AI 第一次就把约定做对了——因为你已经不用再解释。

反过来说，如果你发现自己每天都在重复同一句纠正（"不要用 toFixed，走 formatMoney"），那说明这就是一条该写进项目记忆的规则，而不是一句每天都要重说的话。

06.2 沉淀有三种强度，从轻到重

判断该用哪一种，问自己："这件事会再发生吗？大概多久一次？"只发生一次的就别花半小时去封装，写一行规则就够了。

06.3 规则文件更新样例：照着这个格式写

每次任务完成后往里面追加的，就是几行"这个项目里的做法"。示例（一个邮件通知功能收尾时加的三行）：

# 在 CLAUDE.md 中新增规则

## 邮件通知
- 使用已有的 EmailService，不要新建邮件客户端
- 发送失败时重试 2 次（指数退避）
- 测试必须验证邮件函数被调用过一次，不能只测"不报错"

再换一个场景，认证端点收尾时的规则：

# CLAUDE.md 新增规则

## 认证端点
- 必须使用 bcrypt 哈希密码，禁止明文存储
- 必须有输入校验（用项目里已有的 express-validator）
- 注册成功必须调用 EmailService 发送欢迎邮件

注意这些规则有三个共同特征，值得模仿：短（一行一条）、具体（点名文件和库）、可检查（能判断有没有违反）。（CLAUDE.md 是 Claude Code 认的文件名；别的工具认 AGENTS.md，见 02.2。）

06.4 第三种强度：把重复流程封成一句话

当你发现自己反复让 AI 做同一套动作（"跑测试、修到全绿、把输出给我"），就该把它封成一个技能（skill）——一份写好的操作说明，放在工具约定的目录里，下次用一句话触发。

Claude Code 里技能落盘的形状是这样的：

# 技能目录：一个技能一个文件夹，里面一份 SKILL.md
.claude/skills/fix-tests/SKILL.md

# 建好之后，会话里用斜杠加名字触发
/fix-tests

# 旧的 .claude/commands/xxx.md 写法仍然有效，两者等价
.claude/commands/deploy.md

技能和项目记忆的分界线：偶尔才用到的整套流程适合做成技能（按需加载，不占每次会话的位置）；每次都要遵守的约定适合放进项目记忆文件（每次自动加载）。官方文档给的一句判据很好用：当项目记忆文件里的某一段已经长成"一套流程"而不是"一条事实"时，把它挪去当技能。

06.5 收尾检查清单：五步，两分钟

06.6 复利效应到底长什么样

不用算公式，看这只飞轮就够——它把前面所有阶段串成了一个环：

任务完成 → 记录失败模式 → 更新项目记忆 → 创建/优化技能 → 下次任务更快更准
   ↑                                                                    |
   └────────────────────────────────────────────────────────────────────┘

具体到你手上的变化：第一个任务你可能要写一份很长的任务卡来解释项目约定；第十个任务时，那部分内容已经在记忆文件里了，你的任务卡只需要写"这次要做什么"。省下来的是重复解释的时间。

还有一个更隐蔽的收益：你自己的判断力也在复利。你会在几周内摸清"哪类任务它一做就对、哪类任务它总要跑偏"，然后自然地把流程强度调到合适的位置——这正是 10 那张表的用法。

07七个最常见的坑（附改法）

下面七个坑按"出现频率"排序，不是按"严重程度"。每一段的前半是这个坑长什么样，后半是可以直接照做的改法。

坑 1：跳过规划直接写码

现象："帮我做个 XX"这种模糊指令，得到的是一堆需要返工的代码。改法：发出指令前，先花 5 分钟填 03.1 的五格任务卡。填不出"验证"那一格就别发——那是没想清楚的信号。

坑 2：信任 AI 的"done"声明

现象：它说完成了，你直接合并——没有验证门，等于把错误直接放进主干。改法：把"跑完把命令和输出原文贴给我"变成每次必带的一句。看输出，不看结论。

坑 3：一次给太多任务

现象："帮我重构整个后端"——产出混乱、改动巨大，你审不动也不敢不回退。改法：拆到"能单独验证"的颗粒度。10 的对照表里验证层写"测试"的那种任务，就是合格的颗粒度参照。

坑 4：不提供错误上下文

现象："它不工作了"——AI 只能猜，猜错你更急，两轮之后你就开始怀疑模型能力。改法：用 05.4 的四件套——症状 + 报错原文 + 位置 + 期望行为。四样缺一样，它的猜测空间就大一圈。

坑 5：一个会话做多件事

现象：前半段在改订单模块、后半段在改登录——两边的改动互相干扰，AI 开始把 A 任务的约定用到 B 任务上。改法：一个任务一个会话，做完就开新的。04.6 给了三种隔离开法。

坑 6：不沉淀，每次从零开始

现象：同一句纠正你说了一个月，AI 每次都犯。改法：说出第二次的时候就该写进文件了。06 给了三种沉淀强度。

坑 7：在测试为零的代码库上重度依赖 AI

现象：没有测试，AI 无法自证，你也无法验收，最终只能逐行读代码。这是七个坑里唯一一个"会伤到别人"的。改法：先给要改的那一小块补上测试，再让 AI 进场。不需要整个项目都有覆盖——从你这次要动的地方开始补就有效。

七个坑速查：现象 → 一条改法

08完整例子：给一个商城加注册邮件通知

上面所有原则，在这一节跑一遍完整链路：一个真实的 Node.js + Express 项目，要加一个"用户注册后发欢迎邮件"的接口。每一段提示词都可以改改就用。

第 0 步：开工前（2 分钟）

确认验证命令现在是绿的，并留一个还原点：

git add -A && git commit -m "feature: 注册邮件通知 开工前检查点"
npm test    # 确认现在是全绿的——不绿就先别开工

第 1 步：规划（5 分钟）——第一句话就是任务卡

在计划模式下输入（注意五格齐全、且带"不要做的"）：

为现有的电商系统添加用户注册邮件通知端点。

需求：
- POST /api/register 接收 username, email, password
- 使用 bcrypt 哈希密码
- 调用已有的 EmailService.sendWelcomeEmail()
- 返回 201 + { userId, email }
- 密码最低 8 位，含特殊字符

不要做的：
- 不要修改数据库 schema
- 不要引入新的依赖
- 不要修改现有的 /api/login 端点

验证：npm test 且所有测试通过

它会先读文件、再给一份计划。计划大概长这样，你要审的就是那三行和一个"风险"：

# AI 的计划（你审核这一步）
1. 在 src/routes/auth.js 中创建注册端点
2. 在 tests/auth.test.js 中添加测试用例
3. 运行 npm test 验证

风险：
- 新增端点会共用 validate 中间件，需要确认它不会被改动影响 /api/login

看到一个具体的风险提示，通常说明它真的读了代码；如果计划只有"1. 实现 2. 测试 3. 完成"这种空壳，退回去让它先读文件。

第 2 步：执行（15 分钟）——分三步，每步都能单独验证

批准计划后，明确要求分步、一步一步来：

按计划分步做，每做完一步停下来告诉我改了什么。

步骤 1：在 src/routes/auth.js 中创建注册端点
步骤 2：在 tests/auth.test.js 中添加测试用例
步骤 3：运行 npm test 验证

底层要遵守的纪律（04）：单次改动别超过 200 行；上下文只给相关文件；每步跑一次验证。

第 3 步：验证（5 分钟）——它自己发现了一个失败

它跑测试，发现密码校验那一步有问题（只校验了长度、漏了特殊字符），读报错、修复、重跑，最后全绿。这一步的价值恰恰在于失败是它自己撞上的——如果它没跑测试，这个漏掉的校验就会直接进你的 diff。

✓ 3 tests passing
✓ lint clean
✓ tsc --noEmit passes

你要的那句话在这里："把命令和输出原文贴出来"。上面那三行是它的证据，不是它的结论。

第 4 步：人工审阅（3 分钟）——只看 diff

git diff --stat
git diff src/routes/auth.js

只回答三个问题：只改了该改的文件吗？有没有夹带 /api/login 的改动？密码校验和错误返回符合预期吗？

第 5 步：沉淀（2 分钟）

# CLAUDE.md 新增规则

## 认证端点
- 必须使用 bcrypt 哈希密码，禁止明文存储
- 必须有输入校验（用已有的 express-validator）
- 注册成功必须调用 EmailService 发送欢迎邮件

注意这条规则是怎么长出来的：失败模式（漏了特殊字符校验）→ 一条规则（必须有输入校验）→ 下次自动生效。这就是整个循环的复利来源。

整条链路的时间账

09排错：四种卡住的情况，怎么解

下面四种是实际用起来最常撞上的。它们的共同点是：看起来都像"AI 不行"，实际都不是。

情况一：它说完成了，但我觉得不对

先别重读代码。按顺序问三句，通常第二句就能定位：

情况二：它一直在同一处绕圈

这属于 05.8 的死循环。这里补一条具体操作：把"停止"当成一个正规动作，而不是失败。停下来的做法是三件事——停止代理、把当前 git diff 存成一份补丁文件（万一里面有值得留的片段）、然后用一个新会话重述任务。

为什么换会话有效：旧会话里积了一堆错误尝试和错误结论，它们会持续影响它的判断。新会话只拿着"任务卡 + 现在代码的真实状态"，比在污染过的上下文里继续纠缠干净得多。

情况三：测试一直是红的，但它说已经修好了

这几乎总是三件事之一：

情况四：环境问题它搞不定，反复重试

表现是"同样的报错、不同的尝试、每次都不对"。典型的环境类问题有：依赖没装、运行时版本不对、端口被占、环境变量没配。这类问题你比它强——因为你手上有它没有的信息（比如你十分钟前刚在别的终端占用了那个端口）。

处理方式：把这类东西从"让它自己摸索"改成"写进项目记忆"。比如：

# CLAUDE.md 里加一节，专治环境类反复重试

## 开发环境
- 本机 Node 版本：见 .nvmrc，开工前先 nvm use
- 测试需要本地 Postgres，启动命令：docker compose up -d db
- 3000 端口常被占用，开发服务固定用 3001

# 以及一条给它的行为指令
- 遇到"端口占用""模块找不到"这类环境报错，不要反复重试，
  直接把命令和报错贴给我，由我来处理环境。

四种情况的速查

10到底什么任务用什么闸：一张决策表

这套流程最常见的误用是对什么都上全套——那会让你觉得它慢、麻烦、不值得。正确的用法是按风险配闸门。这张表是本篇最该存下来的一份东西。

按任务类型配闸门

按你自己的处境选路线

11一页纸：下次开工照着念

这一节是给你贴在手边用的，不是给你读的。它把全文压成四组可打勾的条目。

整份清单：四组，十六格

# 开工前（每 2 分钟）
[ ] 我有一条能跑、而且现在是绿的验证命令
[ ] 工作区已提交，能一步回退
[ ] 这次的任务能用一句不含形容词的话说清
[ ] 如果涉及 3 个以上文件或不可逆操作 → 我准备开计划模式

# 发指令时（照着填五格）
[ ] 任务：一句话，没有"更好/优化/完善"
[ ] 背景：技术栈 + 点名相关文件（并说明为什么读它们）
[ ] 要做的：编号，每步都能单独验证
[ ] 不要做的：至少一条真在意的边界
[ ] 验证 + 完成标准：确切命令 + 确切行为

# 验收时（不顺就回退，不要硬调）
[ ] 它贴了完整命令和输出原文（不是"已完成"）
[ ] 我看的是 git diff，不是重读整个文件
[ ] 我单独看了测试文件的 diff（断言有没有被放宽）
[ ] 出错的那条路径 → 我补了一条会失败的测试

# 收尾时（2 分钟，收益在下一周）
[ ] 这次犯的错 → 写成一条项目记忆规则（一行，具体，可检查）
[ ] 反复出现的错 → 补测试或风格检查规则，别只写提醒
[ ] 做过三次以上的流程 → 考虑封成技能
[ ] 清空上下文，再开下一个任务

红线（违反这几条，上面所有努力都会打折）

12术语对照表

这些词会在你读工具文档、和同事讨论时反复出现。第三列是它为什么重要、什么时候用、以及最容易把它当成什么——只看前两列是不够的。

13常见问题

下面这些问题都是"读者真会问的"，不是用来凑章节的。答案尽量给判断依据，而不是给立场。

99一句话总结

如果只能带走一件事：下次它说"完成了"的时候，回一句"把命令和输出原文贴给我"。这一句话的收益，比这篇文章里其他所有内容加起来都大。

98参考来源与证据边界

这是一篇"做法型"文章，所以它的事实成分主要是工具的确切行为（按哪个键、文件叫什么名字、有没有大小限制）。下面这些是我逐一取回原文核对过的，没有一条是凭记忆写的。

一手来源（逐条取原文核对）

• Claude Code 官方最佳实践（code.claude.com/docs/en/best-practices）——四阶段工作流的官方表述（Explore → Plan → Implement → Commit）、进入计划模式的确切操作（按 Shift+Tab 到状态栏显示 ⏸ plan mode on，或 claude --permission-mode plan）、Ctrl+G 打开计划编辑、以及"能一句话描述 diff 就跳过计划"这条判据。本文 03.4 里的提示词示例取自这一页。
• Claude Code 官方记忆文档（code.claude.com/docs/en/memory）——CLAUDE.md 每个会话加载、目标 200 行以内、/init 与 /context 的用途、@AGENTS.md 导入写法与 ln -s 软链接做法，以及一句关键澄清：Claude Code 读的是 CLAUDE.md，不是 AGENTS.md。02 与 03.6 的取舍清单同样来自这里。
• Claude Code 技能文档（code.claude.com/docs/en/slash-commands）——技能的落盘形状（.claude/skills/<名字>/SKILL.md）、用 /名字 触发、以及"旧的 .claude/commands/xxx.md 写法仍然有效、两者等价"。
• Codex CLI 的 AGENTS.md 官方文档（developers.openai.com/codex/guides/agents-md）——发现顺序（全局 ~/.codex/AGENTS.md，项目从根目录往下走、遇到第一个就停）、逐层合并、AGENTS.override.md 的优先级、以及默认 32 KiB 的合并上限。
• AGENTS.md 跨工具约定（agents.md）——把 AGENTS.md 作为通用文件名的那份约定，是"不同工具认不同文件名"这一节的依据。
• Codex CLI 官方仓库 README（github.com/openai/codex）——它的定位是"在你自己电脑上本地运行的编程代理"，以及安装方式（curl -fsSL https://chatgpt.com/codex/install.sh | sh、npm install -g @openai/codex、brew install --cask codex）。
• OpenCode README（github.com/anomalyco/opencode）——"开源的 AI 编程代理"定位，与本文 01.3"流程跨工具"的论述一致。
• Pi Coding Agent README（pi.dev）——一句值得注意的对照：Pi 刻意不做子代理与计划模式，把"要不要这套流程"完全交给你通过扩展自己装。这说明本文这套流程是一种做法，不是一个工具的必备功能。

行业实践类来源（用于交叉印证做法，不作为工具行为的事实依据）

• Addy Osmani — My LLM Coding Workflow Going Into 2026（medium.com/@addyosmani）——"把项目拆成迭代步骤、一次实现一个""每次任务后问自己哪里出了问题，把新规则加到项目记忆或技能里"。
• Andrew Crookston — AI Coding Field Guide（andrewcrookston.com）——Scope → Plan → Execute → Verify → Wrap-up 五步分法、"不要把不相关的事混在同一个会话"、反馈循环表（测试失败退回执行、死循环退回规划）。
• Mehul Jain — AI Coding Agents Implementation Guide（jainmehul.com）——"验证门是核心"、以及"没有测试的代码库上重度依赖代理是风险最高的组合"这一判断。
• Jyme News — Prompt Engineering for Coding Tasks（jyme.io）——"显式说明为什么要读这个文件，比把整个仓库塞给 AI 效果好得多"，本文 04.4 的写法依据。
• Levelop — Spec-Driven Development 指南（levelop.dev）——SDD 的五步循环与"spec 是唯一真相源"的表述。
• DeepLearning.AI — The AI Engineering Skills Map（deeplearning.ai）——"最有价值的不是模型本身，而是工作流"这一判断的出处。

本文自己做的核对

• 工具行为逐条取原文：本文所有"按哪个键""文件叫什么名字""有没有大小限制""命令怎么写"都来自上面列出的官方页面原文，没有一条来自转述或记忆。凡是官方页面里没有的，本文一律不写具体键位。
• 旧版做法的修正：旧版说 Claude Code 的 Plan Mode 是"按 Shift+Tab 两次"。本次核对官方文档，当前表述是按到状态栏出现 ⏸ plan mode on 为止，并且多给了 claude --permission-mode plan 这条启动参数。所以本文改成"按到状态栏显示为止"，不再写"两次"。
• 旧版一处前提的修正：旧版把 CLAUDE.md / AGENTS.md 当作同一回事。核对官方记忆文档后确认：Claude Code 只读 CLAUDE.md，仓库里的 AGENTS.md 需要导入或软链接才会被读到。这一点对"规则写了却不生效"的读者很关键，所以 02 单独讲了。

证据边界与时效

• 模型与界面在变。本文标了 learn:shelf-life=evolving：流程骨架（说清要什么 → 小步做 → 看证据 → 沉淀）不会过时，但具体键位、文件名、大小限制会随版本变化。看到与你的界面不符的地方，以你所用工具的官方文档为准。
• 没有做的事。我没有实际安装并跑完上面每一个工具；没有验证各家工具在具体版本上的界面细节；旧版里引用的一些具体数字（如"3x 速度提升""80% 首次通过率""10x 调试时间减少"）我无法在任何一手来源中找到对应出处，因此本次没有保留——这类数字如果不能指出原始研究，就不该出现在教程里当事实用。
• 一处口径提醒。"3 个文件以上就该开计划模式"是官方文档给的经验判据，不是硬阈值。真正的判据是那两个量：改动范围和可逆性；文件数只是范围的一个方便代理指标。

最后一句：这篇文章是做法，不是规范。你的项目、你的团队约定、你手上的验证手段，都比这里的任何一条更该被优先遵守。