writing-plans git:20260905.64eb187A

Immutable. This exact content never changes and is served at /api/v1/blob/71ccd2b6ac5b05b4.

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

# 编写执行计划

开始时声明："我正在使用 writing-plans 技能拆解实现计划。"

## 目标

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

## 何时使用

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

## 何时不要使用

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

## 计划要求

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

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

## 推荐结构

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

## 目标

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

## 前置条件

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

## 步骤

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

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

## 风险与注意事项

- ...
```

## 编写原则

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

## 风险预检

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

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

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

## 文档路由

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

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

## 输出要求

- 先给计划摘要
- 再给完整步骤
- 标明验证方式
- 标明是否建议先补设计文档或 ADR
- 用户只要求计划时，交付计划；用户已要求实现时，计划完成后直接继续执行，只有缺少必要输入或授权时才暂停依赖步骤