writing-plans git:20260920.878daedA

Immutable. This exact content never changes and is served at /api/v1/blob/24598a76682c3c26.

---
name: writing-plans
description: 用户要求执行计划，或实现存在多阶段依赖、跨模块联动及高成本决策时使用；简单多文件改动不触发。
---

# 编写执行计划

## 目标

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

## 何时使用

- 实现存在多阶段依赖或跨模块联动，需要先明确顺序与验证方式
- 存在错了会造成高成本返工的决策
- 用户希望先出计划再实现

## 何时不要使用

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

## 计划要求

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

- 要做什么
- 为什么这么拆
- 每一步改哪些文件
- 每一步怎么验证
- 哪些地方有风险或前置依赖
- 计划依赖的最脆弱假设是什么
- 哪些决策错了代价高，是否需要先写设计文档或 ADR

## 依赖决策

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

至少记录：

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

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

## 推荐结构

```markdown
# <任务名> 实现计划

## 目标

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

## 前置条件

- <依赖 1>
- <依赖 2>

## 步骤

### 1. <步骤名>
- 修改文件：`path/to/file`
- 主要动作：...
- 验证方式：...

### 2. <步骤名>
- 修改文件：`path/to/file`
- 主要动作：...
- 验证方式：...

## 风险与注意事项

- ...

## 依赖决策（需要时）

| 能力 | 候选方案 | 选择 | 理由与代价 | 官方文档/验证 |
|---|---|---|---|---|
| ... | ... | ... | ... | ... |
```

## 编写原则

- 步骤按执行顺序排列
- 明确可验证的交付节点；紧密依赖的步骤可以合并验证
- 不要写成空泛口号，要写清文件、动作和验证
- 多文件实现优先拆成垂直切片，每个切片都应能交付一个可运行、可验证的路径
- 对非平凡决策写清主张和约定；计划里要能看出什么证据会推翻这个决策
- 复杂任务优先拆成小步，不要一个步骤包太多事
- 计划要贴合当前仓库结构，不要引用外部生态固定路径
- 优先复用官方方案、框架内建能力和仓库现有模式
- 明确最脆弱假设；如果它不成立，会影响哪一步
- 优先规划难以回滚的选择：接口、数据模型、权限边界、存储、部署、兼容性、长期依赖
- 低成本实现细节不要写成设计决策；能在实现中调整的内容放到对应步骤里

## 风险预检

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

- 依赖失效时会卡在哪一步
- 数据量或负载放大后最先脆断的地方
- 如果方向判断错了，回滚成本是什么

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

## 文档路由

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

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

## 输出要求

- 直接给出按依赖排序的可执行步骤，并标明对应验证方式
- 计划较长且摘要能帮助读者把握依赖时，开头用一小段概括，避免复述后面的步骤
- 只有命中文档路由条件时，才说明需要先补设计文档或 ADR
- 用户只要求计划时，交付计划；用户已要求实现时，计划完成后直接继续执行，只有缺少必要输入或授权时才暂停依赖步骤