writing-plans

编写计划

编写实施计划，让经验丰富的工程师几乎无需先前背景也能安全地开展工作。计划应明确列出每项可独立验证的任务所需的确切文件、接口、行为、测试、文档和命令。 计划是持久的仓库文档，而不是只存在于聊天中的检查清单。每项任务还必须以编译、差异审查和符合规范的提交门槛收尾。

假设执行者是经验丰富的开发者，但对我们的工具集或问题领域几乎一无所知。也不要假设他们熟悉良好的测试设计。

开始时宣布：“我将使用编写计划技能来创建实施计划。”

**上下文：**如果在隔离的工作树中工作，请在执行时使用仓库的工作树工作流。计划不得依赖聊天记录。

保存计划至： .agents/plans/YYYY-MM-DD-<feature-name>.md

每份计划都必须使用带 YAML frontmatter 的 Markdown。frontmatter 是用于跨会话跟踪的机器可读索引：

---
id: YYYY-MM-DD-<feature-name>
name: <Feature Name> implementation plan
kind: plan
category: implementation
status: pending
description: <one-sentence purpose>
---

使用以下状态：

状态	含义	转换
draft	正在编写或自我审查计划	→ pending、blocked
pending	计划已完成，可以开始实施	→ running、superseded
running	已开始实施	→ blocked、done、superseded
blocked	缺少已记录的决策或输入，导致无法推进	→ pending、running、superseded
done	实施和验证均已完成	终态
superseded	已被更新的计划取代；链接到替代计划	终态

初始状态设为 draft，仅在自我审查后改为 pending，并在开始实施时改为 running。只有在验证完成后才改为 done。遇到具体缺失的决策或输入时使用 blocked；有更新的计划取代当前计划时使用 superseded。更新同一计划文件；切勿另建状态文件。

跟踪计划：

find .agents/plans -maxdepth 1 -type f -name '*.md' -print | sort
rg -n '^status:' .agents/plans
rg -l '^status: (pending|running|blocked)$' .agents/plans

当工作必须跨越工作者、会话或上下文边界时，使用 delegation-mode。实施后需要进行完整质量审查时，使用 code-review-axes-and-quality。这些阶段应彼此独立：规划定义约定，实施证明约定得到落实，审查则检查结果。

范围检查

如果规格涵盖多个互相独立的子系统，请拆分为多个计划。每份计划都必须单独交付可运行、可测试的增量。不要在实施计划中夹带无关的清理工作。

文件结构

定义任务前，先梳理将创建或修改哪些文件，以及每个文件的职责。这一步将敲定任务分解方案。

• 设计边界清晰、接口明确的单元。每个文件都应只有一个明确职责。
• 你最擅长推理的是能同时放在上下文中的代码；文件聚焦时，修改也更可靠。应优先采用小而精的文件，避免文件过于庞大、职责过多。
• 一起变更的文件应放在一起。按职责拆分，而不是按技术层拆分。
• 在现有代码库中，应遵循既有模式。如果代码库使用大型文件，不要擅自重构；但如果你要修改的文件已经过于臃肿，将拆分纳入计划是合理的。

这种结构有助于分解任务。每项任务都应产出自洽的变更，且单独来看也有意义。

合理控制任务规模

任务是具备自身测试周期、值得新审查者把关的最小单元。划分任务边界时，应将设置、配置、脚手架搭建和文档步骤并入其交付物需要这些步骤的任务中；只有在审查者可能有充分理由拒绝一项任务而批准相邻任务时，才应拆分。每项任务都应以可独立测试的交付物收尾。

细粒度任务

每一步只执行一个操作，通常需要 2–5 分钟：

• “编写失败的测试”——一步
• “运行测试，确认其失败”——一步
• “编写最精简的代码，让测试通过”——一步
• “运行测试并确认其通过”——一步
• “编译受影响的项目或软件包”——一步
• “检查完整差异并运行 git diff --check”——一步
• “使用符合约定的消息提交已验证的增量”——一步

计划文档标题

每份计划 MUST 以此 frontmatter 和标题开头：

---
id: YYYY-MM-DD-<feature-name>
name: [Feature Name] implementation plan
kind: plan
category: implementation
status: draft
description: [One-sentence purpose]
---

# [Feature Name] Implementation Plan

> **For agentic workers:** Use `delegation-mode` for resumable or multi-worker execution. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

**Spec:** [path to the spec/design doc this plan implements — the plan
argues from the spec, so the spec travels with it; executors read both]

## Global Constraints

[The spec's project-wide requirements — version floors, dependency limits,
naming and copy rules, platform requirements — one line each, with exact
values copied verbatim from the spec. Every task's requirements implicitly
include this section.]

---

任务结构

### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py:123-145`
- Test: `tests/exact/path/to/test.py`

**Interfaces:**
- Consumes: [what this task uses from earlier tasks — exact paths and signatures]
- Produces: [what later tasks rely on — exact paths, names, parameters, and
  return types. This block is the contract for an implementer who sees only
  this task.]

- [ ] **Step 1: Write the failing test**

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

- [ ] **Step 2: Run test to verify it fails**

Run: `pytest tests/path/test.py::test_name -v`
Expected: FAIL with "function not defined"

- [ ] **Step 3: Write minimal implementation**

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

- [ ] **Step 4: Run test to verify it passes**

Run: `pytest tests/path/test.py::test_name -v`
Expected: PASS

- [ ] **Step 5: Compile the affected project or package**

Run the narrowest real compile/build command that proves the changed
interfaces are valid. Record the exact command and result in the task handoff.

```bash
<project compile or build command>
```

Expected: exit 0 with no compile errors.

- [ ] **Step 6: Review the complete diff**

```bash
git diff --check
git diff -- <files owned by this task>
git status --short
```

Confirm there are no unrelated files, generated artifacts, secrets, or
unreviewed edits. If the diff is not scoped, fix it before committing.

- [ ] **Step 7: Commit the verified increment**

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

Record the commit hash and verification evidence in the task result. Do not
mark the task `done` before the compile, diff, and commit gates pass.

不得使用占位内容

每一步都必须包含工程师所需的实际内容。以下均属计划缺陷——绝不要这样写：

• “TBD”“TODO”“稍后实现”“补充细节”
• “添加适当的错误处理”／“添加验证”／“处理边界情况”
• “为上述内容编写测试”（但未提供实际测试代码）
• “与任务 N 类似”（应重复代码，因为工程师可能会按乱序阅读任务）
• 只描述要做什么，却不展示如何操作的步骤（代码步骤必须包含代码块）
• 引用任何未在某个任务中定义的类型、函数或方法

自我审查

完成整份计划后，请重新审视计划，并根据规范进行检查。 这是由你自行执行的检查清单，不是要派发给子 Agent 的任务。

1. 规范覆盖情况： 浏览规范中的每个章节／要求。能否指出由哪个任务实现了该要求？列出所有遗漏。

2. 占位内容检查： 搜索计划中的危险信号——即上文“不得使用占位内容”一节中的任何模式。发现后予以修正。

3. 类型一致性： 后续任务中使用的类型、方法签名和属性名称，是否与早期任务中定义的内容一致？任务 3 中的函数名为 clearLayers()，任务 7 中却变成 clearFullLayers()，这就是一个错误。

如发现问题，请直接修正。无需重新审查，修正后继续即可。如果发现某项规范要求没有对应任务，请补充该任务。

执行交接

保存计划后，提供执行方式供选择。路径必须位于仓库的 .agents/plans/ 命名空间中：

“计划已完成并保存至 .agents/plans/<filename>.md。有两种执行方式：

1. 委派执行（推荐）——为每项任务派发一名新的工作者， 将每项结果记录在 .agents/plans/ 下，并在任务之间进行审查。

2. 就地执行——在本次会话中通过检查点执行任务， 并随着工作进展更新计划状态。

你选择哪种方式？”

对于委派执行，使用 delegation-mode：稳定的任务 ID、每项任务一个结果文件、明确的恢复状态，并且只有在确认所有任务完成后才进行最终汇总。对于就地执行，保留相同的任务边界，并在计划中更新复选框和状态。

在将计划或实现标记为完成之前，必须取得新的验证证据： 运行相关的编译／构建和测试，检查完整差异，运行 git diff --check，仅暂存预期文件，检查暂存区差异， 并提交已验证的增量。不得仅凭意图或 Agent 的成功报告将状态标记为 done。如果某项任务没有记录编译结果、差异审查和提交哈希，则该任务尚未完成。