---
name: writing-plans
description: "Use when 已有经批准的设计/规格说明、多步骤实施任务，在动代码之前需要可执行任务清单时。触发场景：写实施计划、拆解开发任务、implementation plan、执行计划文档、任务拆分、按 TDD 步骤写计划。"
---
# 实施计划编写
在**已获用户批准的设计文档**（例如方案设计师产出的 `docs/specs/…-设计.md`）基础上，编写**可交给代理或工程师逐步执行**的实施计划。假设执行者对代码库与领域几乎零上下文、测试习惯一般：计划中必须写明路径、命令、完整代码块与预期输出。遵循 DRY、YAGNI、**TDD**、小步提交。
**开场声明：**「我正在使用**实施计划编写**技能生成实施计划。」
**保存路径（默认）：** `docs/specs/plans/YYYY-MM-DD-<功能简述>.md`
（若用户或项目已有约定路径，以约定为准。）
**可选上下文：** 大功能建议在独立分支或 git worktree 上实施；若用户未准备，在计划头注明即可，不阻塞写计划。
---
## Inputs / Outputs / Gates / Handoffs（统一契约）
- **Inputs（最小输入）**：已获批准的设计/规格说明（路径 + 核心需求 + 约束）；目标仓库与测试/运行命令（如 `pytest`/`npm test`/`go test` 等）。
- **Outputs（产物形态）**：一份可勾选、可交接执行的实施计划（结构参考 `references/plan-template.md`）。
- **Gates（继续前必须满足）**：
- 禁止占位词（`TODO/TBD/适当/稍后补充`），每步必须可执行（路径/命令/预期输出齐全）。
- 需要用户确认的决策点必须显式列出并暂停等待。
- 通用门控清单可复制使用：`../code-review-expert/references/quality-gates-checklist.md`。
- **Handoffs（推荐下游）**：
- `subagent-driven-development（子代理驱动开发）`：按计划逐任务执行
- `code-review-expert（代码审查专家）`：最终质量门禁/收尾审查
- `tdd-master（TDD 开发大师）`：执行阶段遵循 RED-GREEN-REFACTOR 节奏
## 范围检查
若规格仍包含多个可独立交付的子系统，应退回方案阶段拆成多份子规格；若未拆，则建议**多份实施计划**（一子系统一份），每份计划都能单独产出可运行、可测试的软件。
---
## 文件结构先行
在写任务前，先列出将创建/修改的文件及职责，作为分解依据：
- 边界清晰、接口明确；单文件单职责；相关变更放在相近位置（按职责而非按技术层硬拆）。
- 在存量代码库中遵循既有模式；若当前修改的文件已臃肿，可在计划中包含合理拆分步骤。
---
## 任务粒度
**每一步对应一个可完成动作（约 2–5 分钟）：**
- 「编写失败测试」一步
- 「运行并确认失败」一步
- 「写最小实现使测试通过」一步
- 「运行并确认通过」一步
- 「提交」一步
---
## 计划文档头部（必填）
**每一份计划必须以如下头部开头：**
```markdown
# [功能名] 实施计划
> **给代理执行者：** 推荐配合 `subagent-driven-development（子代理驱动开发）`（每任务独立子代理 + 两阶段审查）或在本会话内按勾选逐步执行并在批次节点与用户确认。任务使用 `- [ ]` 勾选跟踪。
**目标：** [一句话说明交付什么]
**架构要点：** [2–3 句]
**技术栈：** [主要语言/框架/测试命令]
**关联设计文档：** `docs/specs/…-设计.md`（路径按实际填写）
---
```
---
## 任务块模板
````markdown
### 任务 N：[组件或主题名]
**涉及文件：**
- 新建：`exact/path/to/file.py`
- 修改：`exact/path/to/existing.py`（可注行号范围）
- 测试：`tests/exact/path/to/test_xxx.py`
- [ ] **步骤 1：编写失败测试**
```python
def test_具体行为():
result = function(输入)
assert result == 期望
```
- [ ] **步骤 2：运行测试确认失败**
运行：`pytest tests/path/test.py::test_具体行为 -v`
预期：失败（例如 NameError / 断言失败，写明预期信息）
- [ ] **步骤 3：最小实现**
```python
def function(输入):
return 期望
```
- [ ] **步骤 4：运行测试确认通过**
运行：`pytest tests/path/test.py::test_具体行为 -v`
预期：通过
- [ ] **步骤 5：提交**
```bash
git add …
git commit -m "feat: …"
```
````
（语言与测试命令按项目替换：如 `npm test`、`go test`、`cargo test` 等。）
---
## 禁止占位（计划不合格）
以下情况**禁止**出现在最终计划中：
- `TBD`、`TODO`、`稍后补充`、`实现时再想`
- 「适当错误处理」「补充校验」「覆盖边界」等无具体代码/断言的描述
- 「为上述编写测试」但无测试代码
- 「同任务 M」（执行者可能乱序阅读——重复粘贴必要内容）
- 只描述动作不给代码块（凡涉及改代码的步骤必须有代码或 diff 级说明）
- 引用未在前文任务中定义的类型/函数/模块
---
## 自检（主代理自行完成，不必派子代理）
写完计划后快速过一遍：
1. **规格覆盖：** 设计文档中的每条需求能否对应到某一任务？漏项则补任务。
2. **占位扫描：** 对照上一节，搜 `TODO`、`适当`、`类似` 等红线词并修正。
3. **命名一致：** 后文出现的函数名/类型名是否与前面任务一致。
---
## 计划审查子代理（可选）
若计划规模大或风险高，可在保存前派发审查子代理，模板见 `references/plan-document-reviewer-prompt.md`。
---
## 交付与执行交接
保存计划后，向用户说明执行方式并二选一（或用户指定）：
1. **子代理驱动（推荐）：** 每任务新子代理，任务间做**规格符合性审查 → 代码质量审查**。调用 `subagent-driven-development（子代理驱动开发）`。
2. **同会话逐步执行：** 由当前对话按勾选执行，每完成若干任务或与用户约定节点做一次同步；实施时遵循 `tdd-master（TDD 开发大师）` 的红绿重构；关键节点用 `code-review-expert（代码审查专家）` 做质量门禁。
**禁止**在未获用户同意时在 `main`/`master` 上直接开始实施（若计划针对默认分支，须在计划中或交接时明确分支策略）。
---
## 衔接关系
| 技能 | 关系 |
|------|------|
| `brainstorming（方案设计师）` | 本技能的上游：输入为已批准的设计文档 |
| `subagent-driven-development（子代理驱动开发）` | 本技能的推荐执行方式 |
| `tdd-master（TDD 开发大师）` | 子代理或本会话实施时的测试节奏依据 |
| `code-review-expert（代码审查专家）` | 全量收尾或子代理流程中的质量审查依据 |
| `prd-engineer（需求工程师）` | 偏 PRD/问题域；本技能偏工程切片与文件级步骤，二者可衔接但职责不同 |