古法编程

writing-plans 技能的核心答案是：它强制 AI 在动手写代码前，生成一份为“零上下文执行者”量身定制的计划，其中每个步骤都必须包含精确的文件路径、完整的代码块、可运行的验证命令和明确的提交信息，从而消除 AI 执行时的模糊决策和累积误差。它是 SuperPowers 工作流中承上启下的关键，将头脑风暴产出的设计文档，转化为可供子代理或内联执行器直接操作的、无歧义的任务清单。

writing-plans 技能如何写出可执行的 AI 实施计划

使用 AI 编码代理时，一个常见痛点是：需求和设计明明谈清楚了，但一执行就跑偏——AI 改了不该改的文件，跳过了测试，或者用了与项目风格不符的方案。问题根源往往不是 AI 能力不足，而是缺少一份足够细、能消除所有模糊空间的执行计划。

SuperPowers 的 writing-plans 技能正是为了解决这个问题。它不是一个简单的任务列表生成器，而是一个强制规范，要求生成的计划必须具体到让一个对你的代码库毫无了解的初级工程师也能照做不卡壳的程度。在 SuperPowers 的整体工作流中，它位于 brainstorming（头脑风暴）产出设计文档之后，subagent-driven-development 或 executing-plans 等执行技能之前，是连接“想清楚”和“做出来”的硬性桥梁。

计划文档的强制规范：从文件头到步骤细节

一份合格的 writing-plans 计划文档，其结构和内容有着严格的规范，这些规范直接来自 skills/writing-plans/SKILL.md 文件。

1. 固定的文件头与保存路径

每份计划必须以固定的 Markdown 头开始，明确告知后续的执行代理（无论是子代理还是内联执行器）应使用哪个技能来处理它。

# [功能名称] 实现计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development
> (recommended) or superpowers:executing-plans to implement this plan task-by-task.
> Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** [一句话描述目标]
**Architecture:** [2-3 句描述方案]
**Tech Stack:** [关键技术/库]

---

计划文件必须保存到 docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md 路径。这个约定让所有项目参与者（包括人类和 AI）都能轻松找到和管理计划文档。

2. 范围检查与文件结构先行

在列出具体任务前，技能要求进行范围检查。如果一份设计文档涵盖了多个独立子系统，应建议将其拆分为多份子项目设计，并分别生成计划。每份计划应能独立产出可测试的软件。

紧接着，必须先进行文件结构规划。明确列出哪些文件会被创建或修改，以及每个文件的职责。这一步是为了锁定分解决策，确保任务边界清晰。原则是：每个文件有清晰的单一职责；一起变化的文件按功能聚合；在现有项目中遵循既有模式。

3. 任务颗粒度与步骤细节

writing-plans 对任务颗粒度有明确要求：每个步骤应是一个耗时 2-5 分钟的原子操作。典型的步骤拆分如下：

  • “编写失败的测试” → 一个步骤
  • “运行测试，确认它失败” → 一个步骤
  • “编写让测试通过的最简实现” → 一个步骤
  • “运行测试，确认它通过” → 一个步骤
  • “提交” → 一个步骤

每个步骤必须包含执行者所需的一切信息。一个典型的任务结构如下所示，它明确列出了涉及的文件、每一步的代码块和验证命令：

### Task N: [组件名称]

**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 with “function not defined”

  • [ ] Step 3: 编写最简实现

def function(input):
    return expected

  • [ ] Step 4: 运行测试以验证其通过 Run: pytest tests/path/test.py::test_name -v Expected: PASS

  • [ ] Step 5: 提交

git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
这种粒度让 AI 执行时有明确的检查点，也让人工审查时能精确定位哪一步逻辑有问题。

### 4. 严禁出现的反模式
技能明确列出了计划中不允许出现的内容，这些内容被视为**计划失败**：
- **占位符**：如 “TBD”、“TODO”、“稍后实现”。
- **模糊指令**：如 “添加适当的错误处理”、“处理边界情况”。执行者无法判断“适当”的具体标准。
- **缺少代码的代码步骤**：如 “为上述代码编写测试”。
- **引用上下文**：如 “与 Task N 类似”。执行者可能不按顺序读，每个任务都必须自包含。
- **提及未定义的类型或函数**：后续任务调用的方法必须在前面的任务中被明确定义。

## 计划的审查与质量门禁

写完计划并不意味着结束，`writing-plans` 内置了两层审查机制来确保计划的质量。

### 1. 自检清单
技能要求编写者在完成计划后，以“新鲜眼光”自行检查：
1.  **需求覆盖**：对照原始设计文档，确保每一条需求都有对应的任务实现。
2.  **占位符扫描**：搜索上述反模式关键词（TBD, TODO, similar to 等），发现即修复。
3.  **类型一致性**：检查前后任务中定义的函数名、接口、参数类型是否完全一致。

### 2. 子代理驱动的计划文档审查
更严格的是，SuperPowers 设计了**计划文档审查系统**。根据 `skills/writing-plans/plan-document-reviewer-prompt.md` 的定义，当计划文档（特别是大型计划的每个逻辑块）完成后，会分派一个专门的审查子代理。

该审查子代理会对照原始设计文档，检查四个核心维度：
- **完整性**：是否存在 TODO、占位符或不完整的任务。
- **规格对齐**：计划是否覆盖了设计文档的所有要求，有无范围蔓延。
- **任务分解**：任务边界是否清晰，步骤是否可操作。
- **可构建性**：工程师能否按此计划推进而不卡住。

审查遵循迭代循环：发现问题 → 编写者修复 → 再次审查 → 直至批准。这个过程在 `writing-plans` 内部形成了闭环，确保输出的计划是经过验证的、可直接执行的。

## 执行移交：计划完成后的工作流

计划保存并审查通过后，`writing-plans` 技能会引导用户选择下一种执行方式，这体现了 SuperPowers 工作流的灵活性：
1.  **子代理驱动执行（推荐）**：使用 `subagent-driven-development` 技能，每个任务由一个独立的全新子代理执行，任务间进行两阶段审查，适合快速迭代和并行推进。
2.  **内联执行**：使用 `executing-plans` 技能，在当前会话中按批次执行任务，并在关键节点暂停等待人工确认，适合需要紧密控制的场景。

两种方式都确保了从计划到代码的平滑过渡。

## FAQ

**Q: 在什么情况下应该触发 `writing-plans` 技能？**
A: 当你拥有了一份通过 `brainstorming` 技能完成并经过审查的设计文档（规格说明）后。它在“设计确认”与“代码编写”之间，提供了一份可执行的、逐步骤的实现路线图。

**Q: 一份计划应该有多长？步骤可以合并吗？**
A: 长度取决于功能复杂度，没有硬性限制。但步骤**强烈不建议合并**。例如，将“写测试 + 运行测试 + 写实现”合并为一步，会破坏 TDD 的 RED-GREEN-REFACTOR 节奏，AI 倾向于直接写实现而跳过确认测试失败的环节。

**Q: 如果功能特别大，一份计划文档写不下怎么办？**
A: 这正是 `Scope Check` 步骤要解决的。大型设计应在 `brainstorming` 阶段就拆分为多份子项目设计文档，然后为每个子系统生成独立的计划。每份计划都应能独立产出可测试的软件增量。

**Q: 计划里的代码必须是完美、可立即运行的吗？**
A: 是的，这是最关键的要求。伪代码或示意性代码等同于没有代码。任何需要修改代码的步骤，都必须写出修改后的完整代码块，而不是“在这里加上验证逻辑”这样的描述性语句。