模板
plan 模板
要改哪些文件、按什么顺序、怎么验证
亲历产品组织阶段 · 通用更新于 2026-10-16
plan 回答“怎么做”：要改哪些文件、按什么顺序、每一步怎么验证。spec 确认之后，在 Plan mode（Shift+Tab）里让 Claude 读 spec 出计划，存到 docs/plans/YYYY-MM-DD_<slug>-plan.md；你确认计划和风险之后，才开始写代码。改动大的话，计划写完、审完就关掉这个会话，开一个新会话只读计划来执行。
为什么要单独一份 plan
spec 说的是要什么，不该写文件路径和代码；真正动手时，agent 需要知道改哪些文件、函数签名是什么、每一步用什么命令证明做对了。把这些写成一份能审的文档，有三个好处：你能在动手之前发现方向错了；执行可以交给新会话或子 agent，不依赖聊天记录；审查时可以逐条对照。
这份模板借鉴了我用了一年的 superpowers writing-plans 的两个做法：每一步都要有可检查的结果；单列一节“审查重点”。
模板
# 实现计划：<功能名>
- Spec：docs/specs/YYYY-MM-DD_<slug>.md
- 分支：feature/<slug>
- 执行方式：单个会话 / 拆成工单 / 子 agent 逐个任务执行
## 全局约束
（从 spec 原样抄过来的硬性要求：上限、命名、文案、版本）
## 文件清单
| 文件 | 新建或修改 | 负责什么 |
|---|---|---|
## 任务
### 任务 1：<名称>
- 接口：用到哪些已有接口；产出哪些新接口（写清签名）
- [ ] 写失败的测试：<测试名和断言>
- [ ] 运行 <命令>，确认失败
- [ ] 实现 <函数签名>
- [ ] 运行 <命令>，确认通过
- [ ] 提交
## 审查重点
（spec 隐含、但上面的测试都没覆盖的输入或失败情况，最多 5 条，每条补一个测试到对应任务）
## 风险与回滚
- 风险：
- 回滚办法：
## 验证
- 全量：<测试、类型检查、lint 命令>
- 人工：<要亲眼看的页面或流程>示例
# 实现计划：待办标签
- Spec：docs/specs/2026-10-16_todo-tags.md
- 分支：feature/todo-tags
- 执行方式：单个会话，3 个任务依次执行
## 全局约束
- 每条待办最多 10 个标签
- 只有大小写不同的标签名视为同一个
## 文件清单
| 文件 | 新建或修改 | 负责什么 |
|---|---|---|
| supabase/migrations/20261016_tags.sql | 新建 | tags 表和关联表 |
| src/lib/tags.ts | 新建 | 标签增删查的唯一入口 |
| src/app/todos/[id]/tag-input.tsx | 新建 | 标签输入框 |
| src/app/todos/page.tsx | 修改 | 按标签筛选 |
## 任务
### 任务 1：数据层
- 接口：产出 addTag(todoId: string, name: string): Promise<Tag>
- [ ] 写失败的测试：同一条待办加第 11 个标签时抛出 TagLimitError
- [ ] 运行 bun test src/lib/tags.test.ts，确认失败
- [ ] 实现 addTag，名称先转小写再查重
- [ ] 运行 bun test src/lib/tags.test.ts，确认通过
- [ ] 提交
## 审查重点
- 标签名前后带空格：应先去掉空格再查重
- 两个标签页同时给同一条待办加标签：总数也不能超过 10 个
## 风险与回滚
- 风险：迁移给 todos 加了外键，旧数据里有孤儿记录会导致迁移失败
- 回滚办法：迁移附带 down 脚本；先在本地库演练一遍
## 验证
- 全量：bun test && bunx tsc --noEmit && bun run lint
- 人工：本地打开 /todos，加标签、按标签筛选，截图贴进 PR每一节怎么填
| 节 | 怎么填 | 最容易犯的错 |
|---|---|---|
| 全局约束 | 从 spec 原样复制数字和规则 | 转述时丢了数字，比如把“最多 10 个”写成“数量有限制” |
| 文件清单 | 每个文件只负责一件事，一起改的文件放在一起 | 漏列文件，执行时 agent 临时决定在哪改 |
| 任务 | 每个任务自带测试，能独立审、独立通过；每一步是一个动作加一个可检查的结果 | 把计划写成代码誊抄。计划记录的是决定：签名、断言、要用的值，不是把实现提前写一遍 |
| 审查重点 | spec 隐含、测试没覆盖的输入，比如空值、超长、并发、重复 | 空着不写。一份 spec 不可能列全所有输入，它没提到的输入并不等于可以崩溃 |
| 风险与回滚 | 写清最坏情况和怎么退回去 | 只写“风险低” |
| 验证 | 写可以直接运行的命令，加上要亲眼看的地方 | 只写“跑一下测试”；UI 改动不写人工验证 |
还有两个和计划本身无关、但最常出事的地方：
- 没确认就执行。 你点头同意的是方向，不是这份你还没看过的计划。存盘、读一遍、确认了再动手
- 计划和执行挤在一个会话里。 大任务写计划就会耗掉大半上下文，执行阶段质量明显下降（见计划和执行分开会话）
大功能一份计划装不下时，用 /mattpocock-skills:to-tickets 拆成带依赖关系的工单，每张工单各自出计划；跨好几个会话的大工程，用 /mattpocock-skills:wayfinder 在 Issue 上维护决策地图。