Writing plans

编写实现计划

概述

从批准的spec编写全面的实现计划。计划是给人执行的——描述构建什么和为什么，绝不编写实现代码。

开始时宣布： "我正在使用 writing-plans 技能创建实现计划。"

计划保存到： docs/deep-reviewer-seek/plans/YYYY-MM-DD-<功能名称>.md （用户偏好覆盖此默认路径）

范围检查

如果spec覆盖多个独立子系统，建议将其拆分为单独的计划——每个子系统一个。每个计划应该能独立产出可工作的、可测试的软件。

OpenSpec 追溯性（吸收 OpenSpec 方法论）

计划中的每个任务必须引用它实现的spec需求。这创建了双向追溯：

• Spec → Plan：每个spec需求映射到至少一个任务
• Plan → Spec：每个任务引用它实现的spec章节

使用内联引用：(Spec §3.2) 或 (Spec: 用户认证) 在每个任务标题之后。

这种追溯性是计划审查的基础。 当计划被审查时，审查者通过追溯链验证：

1. 完整性：每个spec需求是否至少有一个任务？
2. 一致性：任务的范围是否与spec需求的范围匹配？
3. 可行性：任务分解是否足以指导实现？

文件结构

在定义任务之前，规划哪些文件将被创建或修改以及每个文件的职责。

• 设计具有清晰边界和良好定义接口的单元。每个文件应有单一的清晰职责。
• 优先使用更小、聚焦的文件而非做太多事的大文件。
• 一起变更的文件应该放在一起。按职责拆分，而非按技术层拆分。
• 在已有代码库中，遵循既有模式。如果你要修改的文件已经过于庞大，在计划中包含拆分是合理的。

一口大小的任务粒度

每个任务是一个连贯的工作单元。一个任务应该能被不熟悉代码库的熟练工程师在15-30分钟内完成。

计划文档头部

每个计划必须以这个头部开始：

# [功能名称] 实现计划

> **面向工程师：** 此计划设计为人类实现。每个任务
> 引用它实现的spec需求并包含验收标准。

**目标：** [一句话描述构建什么]

**架构：** [2-3句话描述方法]

**技术栈：** [关键技术/库]

**Spec：** [链接到spec文档]

---

任务结构

### 任务 N：[组件名称] (Spec: §X.Y)

**文件：**
- 创建：`exact/path/to/file.py`
- 修改：`exact/path/to/existing.py:123-145`
- 测试：`tests/exact/path/to/test.py`

**构建什么：** [2-3句话描述此任务产出什么以及为什么]

**关键决策：** [实现者需要知道的权衡、约束或设计选择]

**验收标准：**
- [ ] 可验证的条件 1
- [ ] 可验证的条件 2

**依赖：** 任务 N 需要任务 X、Y 先完成（或 "无"）

绝对不留下占位符

每个任务必须包含工程师需要的实际内容。绝不写：

• "TBD"、"TODO"、"稍后实现"、"填写细节"
• "添加适当的错误处理" / "添加验证" / "处理边缘情况"
• "类似任务 N"（重复内容——工程师可能乱序阅读任务）
• 描述做什么但不指定完成是什么样的步骤

自审

写完完整计划后，运行此检查清单：

1. Spec覆盖：浏览每个spec需求。你能指出一个实现它的任务吗？列出任何缺口。
2. 占位符扫描：搜索你的计划中的 "TBD"、"TODO"、模糊指令。修复它们。
3. 类型一致性：类型、方法签名和属性名是否跨任务匹配？
4. 可审查性（为后续计划审查做准备）：
   • 是否每个任务都引用了spec需求？
   • 依赖关系是否清晰且无环？
   • 任务粒度是否合理（15-30分钟）？

如果发现问题，内联修复。不需要重新审查——修复后继续。

计划本身可被审查

实现计划写完后，可以使用 requesting-code-review 技能的 plan 审查类型进行审查：

• 计划审查检查：完整性（spec覆盖）、可行性（任务分解）、一致性（与spec对齐）
• 审查结果：发现缺口、矛盾或不可行的任务
• 在开始编码前通过计划审查可以避免大量返工

铭记

• 始终使用精确文件路径
• 每个任务引用其spec需求
• 每个任务有可验证的验收标准
• 无代码片段——描述构建什么，不描述如何键入
• DRY、YAGNI、频繁提交（面向人类实现者）