plan-crafting

制定计划

根据明确界定的工作范围编写可执行的计划文档。设计此计划时，应支持将任务拆分为可并行执行的“工作者—验证者”对。

核心原则

计划文档必须让不了解代码库背景的工作者无需提问即可执行。所有歧义都必须在规划阶段消除。

硬性要求

1. 每个步骤都必须可执行。 不得使用占位内容（TBD、TODO、“稍后实现”）。
2. 必须避免任务冲突。 修改同一文件的任务不得并行执行。存在依赖关系的任务必须等待前置任务完成。
3. 必须进行自我审查。 编写计划后，必须自行检查其完整性。
4. 任务必须拆分为最小功能单元。 每个任务只产出一项明确的交付成果。

适用场景

• 澄清技能完成并生成 Context Brief 文件后
• 用户明确要求根据清晰的提示创建计划时
• 需要多步实施，并且必须明确任务顺序和依赖关系时

输入

此技能以 Context Brief 文件 为输入。使用 clarification 技能生成的 Context Brief 来填充计划标题：

Context Brief 字段	计划标题对应项
Goal	目标
Scope (In/Out)	工作范围（包含／排除）
Technical Context	架构 + 技术栈 + 文件结构映射依据
Constraints	在任务拆分时体现为约束
Success Criteria	用作自我审查标准
Open Questions	在计划中体现为假设，随后与用户确认

如果不存在 Context Brief 文件（用户直接要求制定计划），请先与用户确认关键信息（目标、工作范围、技术栈），再编写计划。

不适用场景

• 工作范围仍不明确时（返回澄清技能）
• 单文件编辑、简单错误修复或其他单步任务
• 用户明确表示“跳过计划，直接执行”时

计划文档结构

保存位置

docs/engineering-discipline/plans/YYYY-MM-DD-<feature-name>.md

（用户对计划保存位置的偏好优先于此默认位置。）

标题

# [Feature Name] Implementation Plan

> **Worker note:** Execute this plan task-by-task using the run-plan skill or subagents. Each step uses checkbox (`- [ ]`) syntax for progress tracking.

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

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

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

**Work Scope:**
- **In scope:** [What will be implemented]
- **Out of scope:** [What is explicitly excluded]

---

文件结构映射

定义任务前，先梳理将要创建或修改的文件。此阶段将确定任务拆分方案。

• 每个文件都应有明确的职责。
• 需要共同变更的文件应放在一起。按职责拆分，而非按技术层划分。
• 遵循代码库现有模式。如果代码库使用大型文件，不要擅自重构；但如果要修改的文件已变得难以维护，在计划中纳入拆分是合理的。
• 文件结构决定任务拆分。每个任务都应产出一项独立且完整、单独来看也有意义的变更。

验证方式发现

在拆解任务之前，先发现项目最高级别的验证能力。这将决定用于结束每个计划的最终验证任务。

发现顺序（使用第一个匹配项）：

1. 现有的端到端测试 — 搜索 e2e/、tests/e2e/、cypress/、playwright/、package.json 中的 test:e2e，以及 Makefile/Taskfile 中的 e2e 目标
2. 集成测试 — 搜索 tests/integration/、integration_test、test:integration 脚本
3. 验证技能或 Agent — 检查 .claude/skills/、.claude/agents/ 和已安装的插件中是否有名称包含 verify、validate、e2e 或 test 的项目
4. 项目测试套件 — 任何覆盖范围较广的测试运行器（pytest、jest、go test、cargo test 等）
5. 构建 + lint — 如果没有测试，则以成功构建并通过 lint 检查作为最高级别的验证

如果不存在有意义的验证方式（仅有第 5 级）： 添加一个任务 0：创建验证基础设施，为此计划搭建最低限度的验证机制：

• 确定项目的技术栈和合适的测试框架
• 创建一个端到端或集成测试，用于验证计划的核心成功标准
• 此测试应在实现前失败，并在所有任务完成后通过

在计划标题中记录发现结果：

**Verification Strategy:**
- **Level:** [e2e | integration | skill/agent | test-suite | build-only]
- **Command:** [exact command to run the verification]
- **What it validates:** [what passing this verification proves]

项目能力发现

在拆解任务之前，还要发现工作者可以利用的项目级 Agent 和技能：

1. 项目 Agent — 检查 .claude/agents/ 中是否有与任务领域相关的 Agent（例如 test-runner Agent、db-migration Agent）
2. 插件 Agent — 检查已安装的插件中是否有专用 Agent（例如 build-validator、lint-fixer）
3. 项目技能 — 检查 .claude/skills/ 中是否有与任务操作相匹配的技能

如果发现有用的 Agent 或技能，请在适用的任务步骤中引用：

- [ ] **Step N: Run migration**

Use the project's `db-migration` agent for this step if available.
Run: `<migration command>`

工作者无需使用发现的 Agent；它们只是提高效率的提示。如果 Agent 不可用或不合适，工作者可以直接执行步骤。

任务拆解

拆解任务时，请考虑以下事项：

1. 并行性和依赖关系

任务应尽可能支持并行执行。但在以下情况下，必须等待前置任务完成：

• 多个任务要修改同一文件（避免文件冲突）
• 一个任务的输出会被另一个任务引用（接口依赖）
• 多个任务会修改共享状态（数据库架构、配置文件等）

依赖关系应在任务标题中注明：

### Task N: [Task Name]

**Dependencies:** Runs after Task K completes
**Files:**
- Create: `path/to/file`
- Modify: `path/to/existing-file` (anchor: `functionName`)
- Test: `path/to/test-file`

没有依赖关系的任务应标记为可并行执行：

### Task N: [Task Name]

**Dependencies:** None (can run in parallel)
**Files:**
- Create: `path/to/file`
- Test: `path/to/test-file`

2. 工作者与验证者结构

每个任务的设计都应支持由独立工作者（子 Agent）执行，并由另一位独立验证者进行验证：

• 工作者： 执行任务步骤。任务的目标和验收标准是具有约束力的契约；步骤则是预期的执行路径。如果代码库与某个步骤相矛盾，工作者应进行最小限度的调整，以满足验收标准（参见 run-plan 的调整规则）。
• 验证者： 根据代码库逐条判断任务的验收标准，结果只能是通过或不通过。仅此而已——回归检查和计划级成功标准属于后续验证阶段。

这种结构支持同时启动多个任务，并能独立验证每个任务。要实现这一点，验收标准必须写得清晰明确、无需解释——请参阅下文的验收标准规则。

3. 任务粒度

每个步骤只包含一个操作（2–5 分钟）：

• “编写失败测试”——一个步骤
• “运行测试，确认其失败”——一个步骤
• “编写使测试通过所需的最少代码”——一个步骤
• “运行测试，确认其通过”——一个步骤
• “提交”——一个步骤

任务格式

### Task N: [Component Name]

**Goal:** [One sentence stating what this task accomplishes — written to be copied verbatim into the validator prompt]
**Dependencies:** [Predecessor task or "None (can run in parallel)"]
**Files:**
- Create: `exact/path/to/file`
- Modify: `exact/path/to/existing-file` (anchor: `functionOrSectionName`)
- Test: `tests/exact/path/to/test-file`

**Acceptance Criteria:**
- [ ] [binary-decidable condition, e.g., "`pytest tests/path/test.py::test_name` passes"]
- [ ] [binary-decidable condition, e.g., "`function(input)` returns `expected` for the null-brand case"]

- [ ] **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: Commit**

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

文件引用应使用符号锚点，而非行号。 行范围（file.ts:123-145）会在之前的任务修改文件后立即过时。应锚定到不会因编辑而消失的内容：函数名、类名、配置键、章节标题。

验收标准规则

验收标准是任务的约定——执行者可根据实际情况调整步骤，但标准不可协商，验证器也只会评判这些标准。

1. 每项任务至少有一条标准。 如果无法将任务完成情况表述为标准，那它就不是任务，而是一个愿望。
2. 每条标准都必须可进行二元判定。 独立验证器阅读代码并运行列出的命令后，必须能够不作主观判断地回答“满足”或“不满足”。如果某条标准需要解释，那就是计划失败——请重写。
   • 计划失败示例：“代码整洁”“妥善处理错误”“正常工作”“速度合理”
   • 可进行二元判定的示例：“pytest tests/api/test_users.py 通过”“缺少电子邮件时，POST /api/users 返回 400”“grep -r 'legacyParser' src/ 未返回匹配项”
3. 任务的整体判定结果是其所有标准的逻辑与。 不设部分分数，也没有“基本完成”。一条标准未满足，任务就未完成。
4. 标准描述结果，而非实现方式。 “内部使用 HashMap”不是标准；“查找在通过的测试中返回结果”才是。即使执行者选择了与步骤不同的实现路径，标准仍必须适用。

最终验证任务

每个计划都必须以一个最终验证任务结束，运行所发现的最高级别验证。该任务始终是最后一项，依赖所有其他任务，且不能并行执行。

### Task N (Final): End-to-End Verification

**Dependencies:** All preceding tasks
**Files:** None (read-only verification)

- [ ] **Step 1: Run highest-level verification**

Run: `[verification command from Verification Strategy]`
Expected: ALL PASS

- [ ] **Step 2: Verify plan success criteria**

Manually check each success criterion from the plan header:
- [ ] [criterion 1]
- [ ] [criterion 2]
- ...

- [ ] **Step 3: Run full test suite for regressions**

Run: `[full test suite command]`
Expected: No regressions — all pre-existing tests still pass

如果最终验证失败，计划就尚未完成。run-plan 中的执行者—验证器循环会处理失败响应（请参阅 run-plan 的端到端失败响应协议）。

禁止使用占位内容

每个步骤都必须包含执行者所需的实际内容。以下均属于计划失败——绝不要这样写：

• “TBD”“TODO”“稍后实现”“补充细节”
• “添加适当的错误处理”／“添加验证”／“处理边缘情况”
• “为上述内容编写测试”（未提供实际测试代码）
• “与任务 N 类似”（请重复给出代码——执行者可能会乱序阅读任务）
• 只描述要做什么，却不说明如何做的步骤（涉及代码的步骤必须提供代码块）
• 引用所有任务中都未定义的类型、函数或方法
• 无法进行二元判定的验收标准（“正常工作”“代码整洁”）

请牢记

• 始终提供精确的文件路径
• 每个步骤都提供完整代码——如果某一步会修改代码，就展示完整代码
• 提供精确命令及预期输出
• 遵循 DRY、YAGNI、TDD，频繁提交

自我审查

完成计划后，重新审视规格说明，并对照检查计划。这是你自己执行的检查清单，不是调度子代理。

1. 规格覆盖： 浏览规格说明中的每个章节/要求。能否指出实现它的任务？列出任何遗漏。

2. 占位符扫描： 搜索计划中的危险信号——上文“无占位符”章节中的任何模式。修复这些问题。

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

4. 依赖关系验证： 确认并行任务不会修改同一个文件。确认没有遗漏任何依赖链。

5. 验证覆盖： 计划是否包含最终验证任务？是否引用了发现的验证命令？如果没有发现验证命令，是否有创建验证基础设施的任务 0？

6. 验收标准可判定性： 每个任务是否都有目标和验收标准？像严苛的验证者一样逐条审视标准：仅通过阅读代码和运行命令，能否判定其是否达标？重写任何需要主观判断的标准。

如果发现问题，请直接修复。无需重新审查，修复后继续。如果某项规格要求没有对应任务，请添加该任务。

执行交接

保存计划后，提供执行方式选择：

“计划已完成，并保存到 docs/engineering-discipline/plans/<filename>.md。”

“你希望如何继续？”

1. 子代理执行（推荐） —— 为每个任务调度一个新的子代理，在任务之间进行审查，快速迭代

2. 内联执行 —— 在此会话中使用 run-plan 技能执行任务，并在检查点进行批量执行

反模式

反模式	失败原因
将修改同一文件的任务标记为可并行	文件冲突，改动无法合并
列出任务却不注明依赖关系	执行顺序混乱，接口不匹配
步骤假设“执行者会自行想办法”	执行者随意解释，导致规格偏离
批准含有占位符的计划	执行阶段受阻，必须退回规划阶段
完成计划却不进行自我审查	规格覆盖不足、类型不匹配和依赖错误可能未被发现

最简清单

完成计划编写后进行自检：

• 所有任务是否都有准确的文件路径？
• 每个任务是否都有目标和可二元判定的验收标准？
• 所有步骤是否都包含可执行的代码/命令？
• 并行任务之间是否没有文件冲突？
• 是否准确说明了依赖链？
• 计划是否涵盖了所有规格要求？
• 是否没有占位符？
• 计划开头是否包含验证策略？
• 最终验证任务是否是计划中的最后一个任务？

后续步骤

计划获批后：

• 计划已准备好执行时 → 使用 run-plan 技能
• 如果发现工作范围存在歧义 → 返回 clarification 技能以解决

此技能本身不会调用下一个技能。 它会在展示计划文档并让用户选择下一步后结束。