编写计划

概览

编写全面的 implementation plans，假设执行工程师对我们的 codebase 零上下文，且品味可疑。记录他们需要知道的一切：每个 task 要触碰哪些文件、代码、测试、他们可能需要检查的 docs、如何测试。把完整 plan 拆成小块 tasks 给他们。DRY。YAGNI。TDD。频繁 commits。

假设他们是熟练开发者，但几乎不了解我们的 toolset 或 problem domain。假设他们不太懂好的 test design。

开始时宣布： "I'm using the writing-plans skill to create the implementation plan."

上下文： 如果在隔离 worktree 中工作，它应该已在执行时通过 superpowers:using-git-worktrees skill 创建。

将计划保存到： docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md

• （用户对 plan 位置的偏好会覆盖此默认值）

范围检查

如果 spec 覆盖多个独立 subsystems，它应该已在 brainstorming 期间拆分成 sub-project specs。如果没有，建议将它拆成多个单独 plans —— 每个 subsystem 一个。每个 plan 都应能独立产出可工作、可测试的软件。

文件结构

定义 tasks 之前，先梳理哪些文件会被创建或修改，以及每个文件负责什么。这是锁定分解决策的位置。

• 设计边界清晰、interfaces 明确的 units。每个文件都应有一个清晰责任。
• 你对一次能放进上下文的代码推理最好；当文件聚焦时，你的 edits 也更可靠。优先选择更小、更聚焦的文件，而不是承担过多职责的大文件。
• 一起变化的文件应该放在一起。按责任拆分，而不是按技术层拆分。
• 在现有 codebases 中，遵循既有 patterns。如果 codebase 使用大文件，不要单方面重构 - 但如果你要修改的文件已经变得难以驾驭，在 plan 中包含拆分是合理的。

这个结构会指导 task 分解。每个 task 都应产出自包含的更改，且独立看也合理。

小块 Task 粒度

每个 step 是一个 action（2-5 分钟）：

• "Write the failing test" - step
• "Run it to make sure it fails" - step
• "Implement the minimal code to make the test pass" - step
• "Run the tests and make sure they pass" - step
• "Commit" - step

Plan Document Header

每个 plan 必须以此 header 开头：

# [Feature Name] 实施计划

> **给 agentic workers：** REQUIRED SUB-SKILL: 使用 superpowers:subagent-driven-development（推荐）或 superpowers:executing-plans，逐 task 实现此 plan。Steps 使用 checkbox（`- [ ]`）语法进行跟踪。

**目标：** [One sentence describing what this builds]

**架构：** [2-3 sentences about approach]

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

---

Task 结构

````markdown

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

• Step 1: 编写失败测试

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

• Step 2: 运行测试以验证它失败

Run: pytest tests/path/test.py::test_name -v Expected: FAIL，包含 "function not defined"

• Step 3: 编写最小 implementation

def function(input):
    return expected

• Step 4: 运行测试以验证它通过

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

• Step 5: Commit

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

````

不要有占位符

每个 step 都必须包含工程师所需的实际内容。这些是 plan failures —— 绝不要写：

• "TBD", "TODO", "implement later", "fill in details"
• "Add appropriate error handling" / "add validation" / "handle edge cases"
• "Write tests for the above"（没有实际 test code）
• "Similar to Task N"（重复代码 —— 工程师可能会乱序阅读 tasks）
• 只描述要做什么却不展示怎么做的 steps（code steps 需要 code blocks）
• 引用任何 task 中都未定义的 types、functions 或 methods

记住

• 始终使用精确 file paths
• 每个 step 都要有完整 code —— 如果 step 更改 code，就展示 code
• 精确 commands 与 expected output
• DRY、YAGNI、TDD、频繁 commits

自我评审

写完整 plan 后，用新鲜视角查看 spec，并对照检查 plan。这是你自己运行的 checklist —— 不是 subagent dispatch。

1. Spec coverage： 浏览 spec 中的每个 section/requirement。你能指向实现它的 task 吗？列出任何 gaps。

2. Placeholder scan： 在你的 plan 中搜索 red flags —— 上方 "No Placeholders" section 中的任何 patterns。修复它们。

3. Type consistency： 你在 later tasks 中使用的 types、method signatures 和 property names 是否匹配 earlier tasks 中定义的内容？Task 3 中名为 clearLayers()、Task 7 中却名为 clearFullLayers() 的 function 是 bug。

如果发现问题，就 inline 修复。无需重新评审 —— 修复后继续。如果发现某个 spec requirement 没有对应 task，就添加该 task。

执行交接

保存 plan 后，提供执行选择：

"Plan complete and saved to docs/superpowers/plans/<filename>.md. Two execution options:

1. Subagent-Driven (recommended) - I dispatch a fresh subagent per task, review between tasks, fast iteration

2. Inline Execution - Execute tasks in this session using executing-plans, batch execution with checkpoints

Which approach?"

如果选择 Subagent-Driven：

• REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development
• 每个 task 使用 fresh subagent + 两阶段 review

如果选择 Inline Execution：

• REQUIRED SUB-SKILL: Use superpowers:executing-plans
• 带 review checkpoints 的 batch execution