规格驱动与计划先行

你对智能体说「给后台加一个 Google 登录」。四十分钟后它交来一个一千二百行的 diff：引入了一个新的认证库，另起了一套会话存储，还顺手重构了用户表。代码能跑。问题是项目里本来就有会话模块，你只需要在它旁边加一个 OAuth 回调，三百行以内就能搞定。

这类失败的根源不是模型不会写，而是它在你没来得及纠正的时候，已经替你做了一连串架构决定。事后在一千二百行代码里找出哪些决定错了，是最贵的纠错方式；在一页计划里发现它打算「另起一套会话存储」，只需要划掉一行字。

规格驱动和计划先行，本质上就是把错误拦截在最便宜的地方。

工作流：探索、计划、实现、提交

Claude Code 官方最佳实践把推荐流程拆成四步，我认为这个划分对任何工具都成立：

1. 探索：只读，不改。让智能体读代码、回答问题，建立对现状的理解。
2. 计划：产出一份实现计划，你审阅、修改、批准。
3. 实现：按计划写代码，并对照计划验证。
4. 提交：写清楚的提交信息，开 PR。

前两步靠计划模式（plan mode）来保证「只读」。在 Claude Code 里有三种进入方式：按 Shift+Tab 循环切换直到状态栏显示 ⏸ plan mode on；启动时用 claude --permission-mode plan；或者在单条提示前加 /plan。计划模式下，智能体可以读文件、搜索、回答问题，但在你批准计划之前不会修改源码。

计划就绪后，批准界面有三个选择：用自动模式继续、手动逐个批准编辑，或者「继续计划」。别急着点第一项，先按 Ctrl+G，把计划在你自己的编辑器里打开，直接改。计划是文字，改起来比改代码便宜得多，这是整个流程最值钱的一步。

两个机制值得知道：计划会写成文件，保存在 ~/.claude/plans/（路径可配置）；长会话被压缩之后，计划文件会被重新注入，所以它是能挺过压缩的「锚」。如果你用的是别的工具，原则一样：让计划落到文件里，而不是只存在对话里。

$ claude --permission-mode plan
> 阅读 src/auth/ 理解现有会话和登录流程，再看看环境变量里的密钥是怎么管理的。
⏺ （只读探索：Read、Grep……不修改任何文件）
> 我要加 Google OAuth。需要改哪些文件？复用现有会话模块，给出计划。
⏺ 计划：1) 新增 src/auth/google.ts … 2) 复用 session.create() …
# 按 Ctrl+G 在编辑器里改计划，再批准执行

规格文档：让计划有一个靠得住的源头

计划模式解决「想清楚再动手」，但如果需求本身是含糊的，计划只是把含糊换了个形式。较大的功能，应该先写规格（spec），它比计划更稳定，由人拥有；计划是智能体为了完成规格临时生成的，可以丢弃重来。

官方推荐了一种很好用的办法：让智能体采访你。你只给一句话需求，让它用提问工具连续追问技术实现、边界情况、取舍，把你没想到的难点挖出来，最后写成 SPEC.md。写完规格就开一个新会话去执行，新会话的上下文全部用于实现，旁边还有一份书面规格可以对照。

好规格有三个特征，都来自同一个要求：自包含，新会话只读它就能干活。

• 写具体的名字：文件路径、接口、要复用的现有函数。「复用 src/auth/session.ts 的 createSession」比「和现有登录对接」强得多，它直接堵住了开头那个「另起一套会话存储」的错误。
• 写范围外：智能体倾向于「顺手」做更多。把「不改用户表结构」「不引入新的认证库」写进去，等于提前划好围栏。
• 以端到端验证收尾：怎样从头到尾证明它能用。这一条会在下一课展开，它决定了智能体能不能自己判断「做完了」。

规格不需要长。一页纸，几十行，够了：

# SPEC: 管理后台 Google 登录

## 目标
管理员可用 Google 账号登录；邮箱密码登录保持不变。

## 不做
- 不改 users 表结构（Google 的 sub 存入已有的 external_id 字段）
- 不引入新的认证库，使用已安装的 openid-client
- 不做注销所有设备

## 接口
- 新增 `GET /auth/google` 与 `GET /auth/google/callback`（`src/auth/google.ts`）
- 登录成功后调用现有 `createSession(userId)`（`src/auth/session.ts`）

## 验收标准
1. 回调 state 不匹配时返回 400，且不创建会话
2. 首次登录的 Google 用户必须已存在于白名单邮箱，否则 403
3. `npm run verify` 通过，且新增测试覆盖上述两条

## 端到端验证
本地启动后，用测试 Google 账号走完整登录流程，并用 curl 验证
带会话 Cookie 能访问 /admin，不带则 401。

把大任务拆成可验证的小步

规格定义了终点，计划决定路径。计划的质量，看每一步是否带着「怎么验证」。

Anthropic 在长时任务的 harness 文章里记录了一个典型失败：给智能体一个高层目标，它会试图一口气做完，上下文用光时停在半成品上，后来的会话看到一堆半成品，甚至直接宣布「已完成」。他们的对策是把需求展开成一份功能清单，每项带验证步骤和一个 passes 标记，一次只做一项，做完提交并更新进度。你不需要搭整套 harness，但可以抄这个思路：

# PLAN.md（由智能体起草，人审阅后冻结）

- [ ] 1. 新增 google.ts：授权跳转与 state 生成
      验证：`npm test -- src/auth/google.test.ts` 通过 state 相关用例
- [ ] 2. 实现回调：校验 state，换取令牌，解析邮箱
      验证：同一测试文件通过；伪造 state 的用例返回 400
- [ ] 3. 白名单检查与创建会话
      验证：新增 2 个用例；`npm run verify` 全绿
- [ ] 4. 路由接入与端到端检查
      验证：按 SPEC 的「端到端验证」手动走一遍，贴出 curl 输出

一个合格的步骤满足四点：

• 有完成条件：一条命令或一个可观察的结果，通过或失败，没有「看起来差不多」。
• 小到一次 diff 能看完：我自己的经验是，超过两三百行变更的步骤就该再拆；这是判断，不是标准。
• 顺序有依赖逻辑：先有底层能力，后接入口，每一步结束时代码处于能跑的状态。
• 每步一提交：出了问题 git revert 或 /rewind 都有清晰的落点。

审阅计划时，不必抠措辞，盯住三件事：它打算改哪些文件（有没有越界）、它打算复用什么（有没有重复造轮子）、每一步怎么验证（没有验证的步骤，等于没有步骤）。

计划批准之后，长任务可以交给 /goal 无人值守地推进：给一个可验证的终态，比如「npm run verify 退出码为 0，且没有改动测试文件以外的无关模块，或者在 20 轮后停止」。评估由另一个模型在每轮结束后做，它只能依据对话里已经出现的内容判断，所以要让智能体把命令输出打印出来。

什么时候不要计划

计划不是免费的，它有时间成本，也会产生「计划看起来很完整、现实一碰就变」的错觉。官方给的判断标准很实用：如果你能用一句话描述这次 diff，就跳过计划。 改个拼写、加一行日志、重命名一个变量，直接做。

还有几种情形，我倾向于轻量对待甚至跳过：

• 探索性原型：你自己也不知道要什么，需要看到东西才能判断。此时模糊的提示加快速迭代，比写规格更有效，但要说好这份代码是一次性的。
• 修一个有清晰复现的 bug：直接给复现步骤，要求先写失败的测试再修，比计划更管用。
• 计划已经比代码长：说明任务本身该拆小，或者你在过度设计。

反过来，这些情形一定要计划：改动跨多个文件，对要改的代码不熟，方案有多种选择且选错代价大，或者涉及数据、权限、支付这类出错代价高的地方。

最后提醒一个陷阱：计划是活的。实现中发现计划错了，应该更新计划文件并告诉智能体，而不是让代码悄悄偏离计划。偏离而不更新，下一个会话读到的就是一份过期的谎话。

延伸阅读：从想法到规格的完整练习见实战：从想法到规格，上下文如何影响计划的存活见上一课。下一课讲怎么让智能体自己证明做对了：验证闭环。