vinvcn 编写计划
概览
编写全面的 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 结构
### 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: 编写失败测试**
```python
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**
```python
def function(input):
return expected
```
- [ ] **Step 4: 运行测试以验证它通过**
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"
```
不要有占位符
每个 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