writing-plans git:20261015.b377f6bA

Immutable. This exact content never changes and is served at /api/v1/blob/167762d40aded626.

---
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
- 计划可以交给另一个人或代理直接执行而无需重新决策：写清范围与非范围、选定方案及接近的备选、公开接口或配置变化、验证命令和人工验收、发布或迁移后续步骤，以及会改变外部状态的步骤如何回退。
- 用户只要求计划时，交付计划；用户已要求实现时，计划完成后直接继续执行，只有缺少必要输入或授权时才暂停依赖步骤