writing-plans

实施计划编写

在已获用户批准的设计文档（例如方案设计师产出的 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 分钟）：

• 「编写失败测试」一步
• 「运行并确认失败」一步
• 「写最小实现使测试通过」一步
• 「运行并确认通过」一步
• 「提交」一步

---

计划文档头部（必填）

每一份计划必须以如下头部开头：

# [功能名] 实施计划

> **给代理执行者：** 推荐配合 `subagent-driven-development（子代理驱动开发）`（每任务独立子代理 + 两阶段审查）或在本会话内按勾选逐步执行并在批次节点与用户确认。任务使用 `- [ ]` 勾选跟踪。

**目标：** [一句话说明交付什么]

**架构要点：** [2–3 句]

**技术栈：** [主要语言/框架/测试命令]

**关联设计文档：** `docs/specs/…-设计.md`（路径按实际填写）

---

---

任务块模板

### 任务 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: …"
```