Writing Plans Zh

---
name: writing-plans-zh
description: 编写实施计划、把 spec 拆成可交给零上下文工程师逐步执行的任务、任务颗粒度怎么定、计划里不许留占位符、计划写完怎么自查。当用户说「spec 定了帮我写实施计划」「把这个需求拆成任务」「写份 plan.md」「按 TDD 步骤排一下实现顺序」「这份计划别人能照着做吗」「动代码前先出个方案」时使用。写作前提是假设执行者是个熟练但完全不了解本代码库、也不太会设计测试的工程师，所以每个任务都要写清改哪些文件、消费与产出哪些接口、贴出真实的测试代码与实现代码、给出可执行的验证命令与提交步骤。三条硬约束：先画文件结构再拆任务；每一步是 2 到 5 分钟的单一动作；禁止出现待定、TODO、加上适当的错误处理、同任务 N 之类的占位符。
author: Captain
version: 0.1.0
display_name: "编写实施计划"
display_name_en: "Writing Plans (zh)"
description_zh: "把 spec 写成零上下文工程师能照做的实施计划：先定文件结构，再按可独立验收的任务拆分，每步 2 到 5 分钟并附真实代码与验证命令，最后自查覆盖度与类型一致性。"
description_en: "Turn a spec into a plan a zero-context engineer can follow: map the file structure, split into independently reviewable tasks, bite-sized steps with real code and verification commands, then self-review for coverage and consistency."
examples_zh:
  - "spec 定了帮我写实施计划"
  - "把这个需求拆成任务，按 TDD 步骤排一下实现顺序"
  - "这份计划别人能照着做吗"
examples_en:
  - "Write an implementation plan from this spec"
  - "Break this feature into bite-sized TDD tasks"
  - "Could a new engineer follow this plan without asking questions"
metadata:
  { "openclaw": { "requires": { "bins": [] }, "os": ["darwin", "linux", "windows"], "emoji": "🗺️" } }
---

# 编写实施计划

写一份完整的实施计划，**假设执行者对我们的代码库毫无了解、品味也不一定靠谱**。把他们需要知道的一切都写进去：每个任务要动哪些文件、代码怎么写、怎么测、可能需要查哪些文档、怎么验证。整份计划要拆成小口的任务。遵守 DRY、YAGNI、TDD、勤提交。

假设他们是熟练开发者，但**几乎不了解我们的工具链和问题域**，也**不太擅长测试设计**。

**开始时声明：**「我正在用编写实施计划技能来生成实施计划。」

**前置：** 如果要在隔离工作树里干活，那棵工作树应当在执行阶段由「Git 工作树隔离工作区」技能（`using-git-worktrees-zh`）创建。

**计划存放位置：** `docs/plans/YYYY-MM-DD-<功能名>.md`（用户指定的位置优先）。

## 何时用

手上已有 spec 或明确需求、要做的是多步骤任务、且还没开始动代码时使用。只改一行、或还没想清楚要做什么的，不适用。

## 范围检查

如果 spec 覆盖了多个彼此独立的子系统，本应在头脑风暴阶段就拆成子项目 spec。若当时没拆，现在就建议拆成多份计划——**一个子系统一份**。每份计划都要能独立产出可运行、可测试的软件。

## 流程

### 第 1 步：先画文件结构

定义任务之前，先列出**会新建或修改哪些文件、每个文件负责什么**。分解决策在这一步就被锁定。

- 设计边界清晰、接口明确的单元，每个文件一个明确职责
- 你对「一次能装进上下文」的代码推理得最好，文件聚焦时你的改动也更可靠，**宁可小而专，不要大而全**
- 一起变化的文件放在一起；**按职责切分，不要按技术分层切分**
- 在既有代码库里遵循既有模式：仓库本来就用大文件，就不要擅自重构；但如果你正在改的文件已经臃肿，把拆分写进计划是合理的

### 第 2 步：任务定颗粒度

一个任务是**能自带一个测试循环、且值得一个新评审人把关的最小单元**。画任务边界时：把搭环境、配置、脚手架、文档这些步骤，折进真正需要它们的那个任务里；**只在「评审人可以否决这个任务但批准它邻居」的地方切开**。每个任务都以一个可独立验证的交付物结束。

### 第 3 步：每一步都是小口动作

**每一步是一个动作（2 到 5 分钟）：**

- 「写失败测试」—— 一步
- 「跑一遍，确认它失败」—— 一步
- 「写让测试通过的最少代码」—— 一步
- 「跑测试，确认通过」—— 一步
- 「提交」—— 一步

### 第 4 步：写计划头

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

```markdown
# [功能名] 实施计划

> **给执行者：** 必需的后续技能——用「子代理驱动开发」（推荐）或「执行实施计划」逐任务落地本计划。步骤用 `- [ ]` 复选框语法便于跟踪。

**目标：** [一句话说明这次要建什么]

**架构：** [2 到 3 句话说明思路]

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

**Spec：** [本计划所实现的 spec / 设计文档路径 —— 计划是从 spec 论证出来的，所以 spec 要跟着计划一起走，执行者两份都读]

## 全局约束

[Spec 里贯穿全项目的要求 —— 版本下限、依赖限制、命名与文案规则、平台要求 —— 每条一行，数值逐字照抄 spec。每个任务的要求都隐含包含本节。]

---
```

### 第 5 步：写任务

````markdown
### 任务 N：[组件名]

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

**接口：**
- 消费：[本任务用到的、来自前序任务的东西 —— 精确签名]
- 产出：[后续任务依赖的东西 —— 精确的函数名、参数与返回类型。任务的执行者只看得到自己那一个任务，这一块是他们了解邻居任务命名与类型的唯一途径。]

- [ ] **第 1 步：写失败测试**

```python
def test_specific_behavior():
    result = function(input)
    assert result == expected
```

- [ ] **第 2 步：跑测试，确认它失败**

执行：`pytest tests/path/test.py::test_name -v`
预期：FAIL，报 "function not defined"

- [ ] **第 3 步：写最小实现**

```python
def function(input):
    return expected
```

- [ ] **第 4 步：跑测试，确认通过**

执行：`pytest tests/path/test.py::test_name -v`
预期：PASS

- [ ] **第 5 步：提交**

```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
```
````

### 第 6 步：自查

整份计划写完后，用新鲜的眼睛对着 spec 再过一遍。**这是你自己跑的检查清单，不是派子代理。**

1. **Spec 覆盖度：** 扫一遍 spec 的每一节/每条要求，你能指到某个任务实现它吗？把缺口列出来。
2. **占位符扫描：** 在计划里搜下面「禁止占位符」一节的所有红旗写法，改掉。
3. **类型一致性：** 后面任务里用的类型、方法签名、属性名，跟前面任务定义的对得上吗？任务 3 叫 `clearLayers()`、任务 7 写成 `clearFullLayers()`，那就是个 Bug。

发现问题就地改掉，不用再审一轮——改完继续。发现 spec 里有要求没有对应任务，就补一个任务。

需要更强的把关时，可以派一个评审子代理，提示词模板见 `{baseDir}/references/plan-reviewer-prompt.md`。

## 禁止占位符

**每一步都必须写出工程师真正需要的内容。** 下面这些是**计划的缺陷**，永远不要写：

- 「待定」「TODO」「后面再实现」「细节待补」
- 「加上适当的错误处理」/「加校验」/「处理边界情况」
- 「给上面这些写测试」（却没给出真实测试代码）
- 「同任务 N」（把代码重复写一遍 —— 执行者可能不按顺序读任务）
- 只说做什么、不给怎么做的步骤（代码类步骤必须带代码块）
- 引用了任何任务里都没定义过的类型、函数或方法

## 输出契约：交接执行

计划存盘后，给出执行方式的选择：

> **「计划已完成，保存在 `docs/plans/<文件名>.md`。两种执行方式：**
>
> **1. 子代理驱动（推荐）** —— 每个任务派一个全新子代理，任务之间我来评审，迭代快
>
> **2. 本会话内联执行** —— 在当前会话里逐任务执行，按检查点批量推进
>
> **选哪种？」**

- **选子代理驱动：** 必需的后续技能是「子代理驱动开发」（`subagent-driven-development-zh`）—— 每任务一个全新子代理 + 两段式评审
- **选内联执行：** 必需的后续技能是「执行实施计划」（`executing-plans-zh`）—— 带检查点的批量执行

---
改编自 [obra/superpowers](https://github.com/obra/superpowers) 的 `writing-plans`（MIT）。改动见 ATTRIBUTION.md。