编写执行计划

目标

把一个多步骤任务拆成清晰、可执行、可验证的计划，方便后续直接实现。

何时使用

• 实现存在多阶段依赖或跨模块联动，需要先明确顺序与验证方式
• 存在错了会造成高成本返工的决策
• 用户希望先出计划再实现
• 全局规则的交付分档为高风险时：计划必须写明回滚方式，以及能否在不动数据的情况下回滚

何时不要使用

• 只是很小的单点改动
• 需求本身还没讲清楚
• 用户明确要求直接动手，不先写计划

写计划前的探索

• 先摸清相关代码：从入口（API、界面组件、CLI 命令）追到存储或外部调用，记录入口（带 file:line）、逐步的调用顺序与数据变换、状态变化与副作用、涉及的组件和内外部依赖、抽象分层（表现层、业务逻辑、数据层）与组件间接口、横切关注点（鉴权、日志、缓存）、关键算法与数据结构、错误处理与边界、性能考虑和已有技术债，以及相似功能的现有实现。
• 范围较大且客户端支持子代理时，可以并行派出 2-3 个只读探索者，各自负责一个方面，例如“找出与该功能相似的实现并完整追踪”“梳理该功能区域的架构与抽象”“分析某个现有功能的当前实现”“找出相关的界面模式、测试方式或扩展点”。每人返回 5-10 个必读文件和带 file:line 的结论；主执行者随后亲自阅读这些文件，不只凭摘要写计划。
• 计划写成可直接执行的蓝图：先列出依据的现有模式和约定（带 file:line），给出唯一的架构决定及理由，再写每个组件的文件路径、职责、依赖和接口，要新建和修改的文件清单，从入口到输出的数据流，以及按阶段排列的构建顺序。错误处理、状态管理、测试、性能和安全只写本次真正涉及的部分。

引导式功能开发

用户要求逐阶段推进一个新功能，或功能较大且用户希望参与每个关键决定时，按以下阶段推进，每个检查点等用户答复后再进入下一阶段；用户没有这样要求时按全局规则自行推进，不强加检查点。

1. 理解需求：需求不清时问清要解决什么问题、功能做什么、有哪些约束，复述理解并确认。
2. 探索代码：按上一节探索，汇总发现的模式。
3. 澄清问题：按 brainstorming 的检查维度列出所有未定之处，集中一次提出。检查点：等答复；用户说“你看着办”时给出推荐并取得明确确认。
4. 架构设计：按 brainstorming 的三种视角给出方案、取舍对比和推荐理由。检查点：用户选定方案。
5. 实现：用户批准后，重读相关文件，按选定方案和仓库约定实现，并随进度更新任务清单。
6. 质量审查：按 requesting-code-review 从简洁与重复、缺陷与功能正确性、项目约定与抽象三个方向审查，汇总最严重的问题。检查点：由用户决定现在修、以后修还是保持现状。
7. 总结：做了什么、关键决定、修改的文件、建议的下一步。

计划要求

计划只展开当前任务需要的部分，避免把以下问题机械写成固定章节：

• 要做什么
• 为什么这么拆
• 每一步改哪些文件
• 每一步怎么验证，完成信号是什么
• 什么情况下停止执行或回头修改计划
• 哪些地方有风险或前置依赖
• 计划依赖的最脆弱假设是什么
• 哪些决策错了代价高，是否需要先写设计文档或 ADR

依赖决策

当任务需要新增库、CLI、代码生成器、服务或其他外部能力时，补一个轻量的 build-vs-buy 判断；不要为标准库、项目已有依赖或明显的机械工具选择制造长篇比较。

至少记录：

• 要解决的具体能力，而不是只写依赖名称；
• 候选方案，包括复用现有实现、采用成熟依赖或少量本地实现；
• 最终选择及理由：维护状态、版本兼容、安全/许可证、运行成本和回滚难度；
• 选定依赖需要查阅的官方文档或源码；
• 依赖不可用、版本不兼容或方向判断错误时，计划在哪一步停止或回退。

这是决策记录，不是要求每个小改动都做形式化调研。优先复用当前项目已有模式；不要为了证明“build-vs-buy”而引入新依赖。

可选结构

按任务取用下面的章节，删除没有内容的部分：

# <任务名> 实现计划

## 目标

<一句话说明要完成什么>

## 前置条件（存在时）

- <依赖 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 的补偿逻辑比它支撑的功能还大时，说明前提错了，换路线。

切片与依赖

• 先预重构：让改动变容易，再做容易的改动。需要的预重构排在最前面。
• 每个切片是一条窄但完整的路径，穿过所有相关层（schema、接口、界面、测试），完成后可以单独演示或验证；规模控制在一个新会话的上下文能装下。
• 每个切片写明阻塞它的切片；没有阻塞的可以立即开始。执行时处理“前沿”：所有阻塞都已完成的切片。
• 一次机械改动波及整个代码库（重命名列、改共享符号的类型），任何垂直切片都无法单独保持绿色时，按扩展-迁移-收缩安排：先在旧形式旁加新形式，保证什么都不坏；再按包或目录分批迁移调用方，每批一个切片并被“扩展”阻塞，因为旧形式仍在，每批之后 CI 保持绿色；最后在所有迁移批次之后删除旧形式。连分批都无法单独保持绿色时，让各批共用一个集成分支，只承诺最后的集成验证切片是绿色的。
• 计划给用户确认时，逐项列出标题、被谁阻塞和交付的端到端行为，问粒度是否合适、阻塞关系是否只包含真正的前置条件、是否需要合并或拆分。

并行拆分

将实现任务交给多个代理或多人并行执行时：

1. 先调研全部受影响的文件、模式和调用点，以及现有约定，保证各单元改法一致。
2. 划清每个单元的文件和状态所有权：并行写入任务各用独立 worktree，只读任务可共享固定快照。核对端口、数据库、缓存、命名空间和设备是否共享，按需隔离或串行使用；worktree 只隔离代码。批量机械改动优先按目录或模块拆成能单独合入的单元，规模大致均匀，数量随实际工作量调整。
3. 确定每个单元的端到端验证方式（浏览器操作截图、CLI 实际运行、启动服务后请求接口或已有集成测试）；找不到时先问用户，因为执行者无法自己再问。
4. 给每个执行者的说明必须自包含：总体目标、本单元的文件和改动描述、需要遵守的约定、验证方式，以及完成后的固定步骤（自审、运行相关测试、端到端验证、按授权提交和创建 PR、最后一行报告 PR 链接或未创建的原因）。
5. 执行中用一张表跟踪每个单元的状态和 PR，全部结束后汇总成功数量和失败原因。
6. 单元之间有阻塞关系、需要合成一个整体交付时，使用一个集成分支：每个执行者在基于集成分支的独立 worktree 中工作，开始前确认基线正确，完成前先合入集成分支最新提交；合并完成后如果前沿出现新的可做单元，立即派发。全部完成后对最终合并状态做整体代码审查，运行约定的整体检查和跨单元场景，统一修复，最后清理本次创建且不再需要的 worktree。各单元的检查不能代替集成验证。与执行者的沟通尽量用指向需求、计划、调研笔记和提交的引用，不复制内容。

无人值守执行

计划交给代理长时间自主执行、用户事后才审阅时：

• 完成条件写成每轮都能运行并判定通过或失败的检查；“工作 4 小时”这类时长不是完成条件。执行中不悄悄放宽完成条件来宣布完成。
• 只有已经手工或在旁观察下做过一次、代理拥有与人相同的验证入口、每一步都能在不达标时停下时，才转为自主执行。
• 每轮只做一个最小改动并在真实产物上验证，有进展则保留，没有进展则撤销，不留着“可能有用”的改动。
• 写明逃生条件：长时间没有进展时停止并写明原因，不去重新诠释目标。
• 在项目临时目录记录追加式决策日志（如 tmp/decisions.tsv，列为时间、阶段、决策、原因、证据指针、结果），只记分叉、单元完成、回退和阻塞；错误的记录用新行更正，不改写历史。交还前对照实际执行记录核对每行证据能否打开并支持结论，默认不提交日志。

风险预检

当计划涉及外部依赖、高并发、数据迁移或发布链路时，至少补这几项：

• 依赖失效时会卡在哪一步
• 数据量或负载放大后最先脆断的地方
• 如果方向判断错了，回滚成本是什么
• 面向真实用户或共享环境发布时，首批覆盖范围、可观测的扩大条件、失败停止条件和恢复步骤是什么；优先复用已有灰度或发布能力，新增开关需核对需求和授权。
• 恢复方案是否覆盖代码、数据和外部副作用；写清不可逆部分及备份或补偿条件，不把代码可回退等同于整个操作可恢复。

这些不是展开成长篇风险分析，而是提前暴露最危险的前提。

文档路由

计划包含高成本或长期设计选择时，按 设计文档与 ADR 路由 判断。命中条件时把相应文档列为实现前置步骤，不在执行计划中复制完整文档。

文档前置不自动包含用户审批；只有用户或项目规则明确要求时，才在实施依赖该批准的步骤前等待批准。同一范围和前提下已有批准时不重复请求。

输出要求

• 直接给出按依赖排序的可执行步骤，并标明对应验证方式
• 计划较长且摘要能帮助读者把握依赖时，开头用一小段概括，避免复述后面的步骤
• 只有命中文档路由条件时，才说明需要先补设计文档或 ADR
• 计划可以交给另一个人或代理直接执行而无需重新决策：写清范围与非范围、选定方案及接近的备选、公开接口或配置变化、验证命令和人工验收、发布或迁移后续步骤，以及会改变外部状态的步骤如何回退。
• 用户只要求计划时，交付计划；用户已要求实现时，计划完成后直接继续执行，只有缺少必要输入或授权时才暂停依赖步骤