writing-plans · diff
git:20260920.97cad83 to git:20261015.b377f6b
20 added, 0 removed. Audit A to A.
---
name: writing-plans
description: 用户要求执行计划，或实现存在多阶段依赖、跨模块联动及高成本决策时使用；简单多文件改动不触发。
---
# 编写执行计划
## 目标
把一个多步骤任务拆成清晰、可执行、可验证的计划，方便后续直接实现。
## 何时使用
- 实现存在多阶段依赖或跨模块联动，需要先明确顺序与验证方式
- 存在错了会造成高成本返工的决策
- 用户希望先出计划再实现
## 何时不要使用
- 只是很小的单点改动
- 需求本身还没讲清楚
- 用户明确要求直接动手，不先写计划
## 计划要求
计划只展开当前任务需要的部分，避免把以下问题机械写成固定章节：
- 要做什么
- 为什么这么拆
- 每一步改哪些文件
- 每一步怎么验证
- 哪些地方有风险或前置依赖
- 计划依赖的最脆弱假设是什么
- 哪些决策错了代价高，是否需要先写设计文档或 ADR
## 依赖决策
当任务需要新增库、CLI、代码生成器、服务或其他外部能力时，补一个轻量的 build-vs-buy 判断；不要为标准库、项目已有依赖或明显的机械工具选择制造长篇比较。
至少记录：
- 要解决的具体能力，而不是只写依赖名称；
- 候选方案，包括复用现有实现、采用成熟依赖或少量本地实现；
- 最终选择及理由：维护状态、版本兼容、安全/许可证、运行成本和回滚难度；
- 选定依赖需要查阅的官方文档或源码；
- 依赖不可用、版本不兼容或方向判断错误时，计划在哪一步停止或回退。
这是决策记录，不是要求每个小改动都做形式化调研。优先复用当前项目已有模式；不要为了证明“build-vs-buy”而引入新依赖。
## 可选结构
按任务取用下面的章节，删除没有内容的部分：
```markdown
# <任务名> 实现计划
## 目标
<一句话说明要完成什么>
## 前置条件（存在时）
- <依赖 1>
- <依赖 2>
## 步骤
### 1. <步骤名>
- 修改文件：`path/to/file`
- 主要动作：...
- 验证方式：...
### 2. <步骤名>
- 修改文件：`path/to/file`
- 主要动作：...
- 验证方式：...
## 风险与注意事项（存在时）
- ...
## 依赖决策（新增外部能力时）
| 能力 | 候选方案 | 选择 | 理由与代价 | 官方文档/验证 |
|---|---|---|---|---|
| ... | ... | ... | ... | ... |
```
## 编写原则
- 步骤按执行顺序排列
- 明确可验证的交付节点；紧密依赖的步骤可以合并验证
- 不要写成空泛口号，要写清文件、动作和验证
- 多文件实现优先拆成垂直切片，每个切片都应能交付一个可运行、可验证的路径
- 对非平凡决策写清主张和约定；计划里要能看出什么证据会推翻这个决策
- 复杂任务优先拆成小步，不要一个步骤包太多事
- 计划要贴合当前仓库结构，不要引用外部生态固定路径
- 优先复用官方方案、框架内建能力和仓库现有模式
- 明确最脆弱假设；如果它不成立，会影响哪一步
- 优先规划难以回滚的选择：接口、数据模型、权限边界、存储、部署、兼容性、长期依赖
- 低成本实现细节不要写成设计决策；能在实现中调整的内容放到对应步骤里
+ ## 计划完整性
+
+ - 批准前的计划不留占位：不写 TBD、TODO、“稍后实现”“同第 N 步”“细节待定”。有未知项时先查清，或写明推迟原因和负责人。
+ - 每个阶段都能独立合入：第 N 阶段上线后，即使第 N+1 阶段永远不做，系统也可用。做不到时合成一个阶段，不假装分期。“第 0 阶段：调研”说明调研应在计划之前完成。
+ - 涉及 8 个以上文件或新增服务时明确指出；3 个以上组件交换数据时画一张 ASCII 关系图，检查是否有环。
+ - 列出主流程、错误路径和边界情况的验证方式，并说明能否在不动数据的情况下回滚。
+ - 实施需要的 API key、token 和第三方账号在计划中一次列清，不在实施中途索要；需要的工具和外部访问能用只读方式确认的先确认，确认不了的列为前置条件。
+ - 计划新增了用户没要求的文件、抽象、错误处理层、配置项或重试时做一次精简检查：每个 try/catch、重试、回退或开关对应一个具名的失败模式，否则删除；列出新增的命令、环境变量、参数和服务，默认不新增；绕开某个异常 API 的补偿逻辑比它支撑的功能还大时，说明前提错了，换路线。
+
+ ## 并行拆分
+
+ 改动大且机械（迁移、批量重命名、跨目录替换），并且要交给多个代理或多人并行执行时：
+
+ 1. 先调研全部受影响的文件、模式和调用点，以及现有约定，保证各单元改法一致。
+ 2. 拆成彼此独立的单元：每个单元能在独立的 worktree 中实现，能单独合入而不依赖其他单元先合入，规模大致均匀；优先按目录或模块切分，不按随意的文件列表切分。单元数量随实际工作量调整。
+ 3. 确定每个单元的端到端验证方式（浏览器操作截图、CLI 实际运行、启动服务后请求接口或已有集成测试）；找不到时先问用户，因为执行者无法自己再问。
+ 4. 给每个执行者的说明必须自包含：总体目标、本单元的文件和改动描述、需要遵守的约定、验证方式，以及完成后的固定步骤（自审、运行相关测试、端到端验证、按授权提交和创建 PR、最后一行报告 PR 链接或未创建的原因）。
+ 5. 执行中用一张表跟踪每个单元的状态和 PR，全部结束后汇总成功数量和失败原因。
+
## 风险预检
当计划涉及外部依赖、高并发、数据迁移或发布链路时，至少补这几项：
- 依赖失效时会卡在哪一步
- 数据量或负载放大后最先脆断的地方
- 如果方向判断错了，回滚成本是什么
这些不是展开成长篇风险分析，而是提前暴露最危险的前提。
## 文档路由
计划包含高成本或长期设计选择时，按 [设计文档与 ADR 路由](references/design-record-routing.md) 判断。命中条件时把相应文档列为实现前置步骤，不在执行计划中复制完整文档。
文档前置不自动包含用户审批；只有用户或项目规则明确要求时，才在实施依赖该批准的步骤前等待批准。同一范围和前提下已有批准时不重复请求。
## 输出要求
- 直接给出按依赖排序的可执行步骤，并标明对应验证方式
- 计划较长且摘要能帮助读者把握依赖时，开头用一小段概括，避免复述后面的步骤
- 只有命中文档路由条件时，才说明需要先补设计文档或 ADR
+ - 计划可以交给另一个人或代理直接执行而无需重新决策：写清范围与非范围、选定方案及接近的备选、公开接口或配置变化、验证命令和人工验收、发布或迁移后续步骤，以及会改变外部状态的步骤如何回退。
- 用户只要求计划时，交付计划；用户已要求实现时，计划完成后直接继续执行，只有缺少必要输入或授权时才暂停依赖步骤