writing-plans

编写计划

目的

创建可执行、歧义极少的实施计划，让其他工程师能够逐项执行，并获得可预测的结果。

适用场景

在以下情况下使用此技能：

• 已有需求／规范，但尚未开始实施
• 工作涉及多个步骤，需要协调多个文件和测试
• 需要为其他会话或工程师准备可直接交接的计划

进度跟踪

在每个规划阶段显示进度：

[████░░░░░░░░░░░░░░░░] 25% — Phase 1/4: Gathering Context & Constraints
[████████░░░░░░░░░░░░] 50% — Phase 2/4: Decomposing Into Tasks
[████████████░░░░░░░░] 75% — Phase 3/4: Specifying Files & Commands
[████████████████████] 100% — Phase 4/4: Writing & Saving Plan

工作流

1. 收集背景信息和约束条件
2. 将工作拆解为小任务，并采用测试优先的方法
3. 明确指定文件、代码片段和命令
4. 添加验证标准和预期输出
5. 保存计划并交接给 executing-plans

概述

编写全面的实施计划时，假设工程师对我们的代码库一无所知，判断力也不太可靠。记录他们需要了解的一切：每项任务要修改哪些文件、需要编写什么代码、要运行哪些测试、可能需要查阅哪些文档，以及如何进行测试。将完整计划拆解为小任务。遵循 DRY、YAGNI、TDD，并频繁提交。

假设他们是熟练的开发者，但对我们的工具集或问题领域几乎一无所知。还要假设他们不太熟悉良好的测试设计。

开始时宣布：“我正在使用 writing-plans 技能来创建实施计划。”

**背景：**应在专用工作树中执行（由 brainstorming 技能创建）。

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

小任务的粒度

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

• “编写失败的测试”——一个步骤
• “运行测试，确认其失败”——一个步骤
• “实现最精简的代码，让测试通过”——一个步骤
• “运行测试，确认全部通过”——一个步骤
• “提交”——一个步骤

计划文档标题

每份计划都必须以以下标题开头：

# [Feature Name] Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

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

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

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

---

任务结构

### 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: 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"
```

请记住

• 始终提供准确的文件路径
• 在计划中写出完整代码（不要写“添加验证”）
• 提供准确的命令和预期输出
• 使用 @ 语法引用相关技能
• 遵循 DRY、YAGNI、TDD，并频繁提交

执行交接

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

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

1. 子 Agent 驱动（当前会话）——我会为每项任务派遣新的子 Agent，并在任务间进行审查，以快速迭代

2. 并行会话（独立会话）——在新会话中使用 executing-plans，分批执行并设置检查点

你想采用哪种方式？”

如果选择子 Agent 驱动：

• **必需的子技能：**使用 superpowers:subagent-driven-development
• 留在当前会话
• 每项任务都使用新的子 Agent，并进行代码审查

如果选择并行会话：

• 引导他们在工作树中开启新会话
• 新会话必须使用的子技能： superpowers:executing-plans

关键规则

• 始终包含准确的路径和准确的命令。
• 始终为测试／验证步骤定义预期结果。
• 步骤不得含糊（避免使用“实现验证”这类表述，而不说明具体代码意图）。

示例用法

1. “使用 writing-plans 规划从 REST 迁移到 GraphQL。”
2. “使用 writing-plans 将身份验证重构拆解为 TDD 任务。”
3. “使用 writing-plans 为新的缓存层准备交接计划。”