Superpowers：writing-plans技能详解

一、定位与作用

writing-plans 是 Superpowers 技能系统中的任务分解专家，专门负责将设计规范转化为详细的实施计划。它的核心定位是：

"在动手写代码之前，为多步骤任务创建全面的实施计划"

一句话总结：把大任务拆成可执行的小步骤

---

二、核心原则

writing-plans 技能遵循以下核心原则：

原则	含义	重要性
TDD	测试驱动开发，先写测试再写代码	⭐⭐⭐⭐⭐
DRY	不要重复自己，避免代码重复	⭐⭐⭐⭐
YAGNI	不要过度设计，只实现当前需要的功能	⭐⭐⭐⭐
Frequent Commits	频繁提交代码，每次完成一个小任务就提交	⭐⭐⭐⭐
Bite-Sized Tasks	任务粒度要小，每个步骤 2-5 分钟完成	⭐⭐⭐⭐⭐

---

三、使用场景

什么时候使用 writing-plans：

• 有了详细的设计规范后
• 在开始任何代码实现之前
• 对于需要多个步骤完成的任务

使用前提：

• 应该在专门的工作树中运行（由 brainstorming 技能创建）
• 已经完成了 brainstorming 阶段，有了清晰的设计规范

---

四、计划文档结构

1️⃣ 保存位置

默认保存到：

Plain Text

docs/superpowers/plans/YYYY-MM-DD-.md

例外：如果用户在 CLAUDE.md 中有偏好设置，按用户的设置来

2️⃣ 计划文档头部

每个计划必须以以下头部开始：

Markdown

# [Feature Name] Implementation Plan

> **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:** [One sentence describing what this builds]

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

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

---

关键点：

• 明确目标
• 简要描述架构
• 列出技术栈
• 指明执行所需的子技能

3️⃣ 任务结构

每个任务都应该按照以下结构编写：

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: Write the failing test**

```python

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

Plain Text

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

Plain Text

- [ ] **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"

Plain Text

undefined

关键要素：

• 明确的文件路径：精确到具体文件
• 完整的代码：每一步都要展示实际代码
• 具体的命令：包括测试命令和预期输出
• 提交步骤：完成后立即提交

---

五、任务分解原则

1️⃣ 任务粒度

每个步骤应该是一个 2-5 分钟就能完成的动作：

• "写失败的测试" - 一步
• "运行测试确保失败" - 一步
• "实现最小代码使测试通过" - 一步
• "运行测试确保通过" - 一步
• "提交" - 一步

为什么这么小：

• 降低复杂性
• 便于跟踪进度
• 减少错误
• 可以频繁提交

2️⃣ 文件结构规划

在定义任务之前，先规划哪些文件会被创建或修改，以及每个文件的职责：

文件设计原则：

• 设计有清晰边界和定义良好接口的单元
• 每个文件应该有一个明确的职责
• 偏好小而专注的文件，而不是做太多事情的大文件
• 一起变更的文件应该放在一起
• 按职责拆分，而不是按技术层拆分
• 在现有代码库中，遵循已建立的模式

注意：如果正在修改的文件变得难以管理，在计划中包含拆分是合理的。

---

六、范围检查

如果规范涵盖多个独立子系统：

• 应该在 brainstorming 期间就分解成子项目规范
• 如果没有，建议将其分解为单独的计划 - 每个子系统一个
• 每个计划都应该产生可独立工作、可测试的软件

---

七、禁用占位符

计划失败的标志 - 绝对不要写：

• "TBD"、"TODO"、"implement later"、"fill in details"
• "Add appropriate error handling" / "add validation" / "handle edge cases"
• "Write tests for the above"（没有实际测试代码）
• "Similar to Task N"（重复代码 - 工程师可能会乱序阅读任务）
• 描述做什么但不展示如何做的步骤（代码步骤需要代码块）
• 引用未在任何任务中定义的类型、函数或方法

记住：

• 始终使用精确的文件路径
• 每一步都要有完整的代码
• 要有确切的命令和预期输出
• 遵循 DRY、YAGNI、TDD、频繁提交

---

八、自检步骤

编写完完整计划后，用新的视角检查计划：

检查项	内容	行动
1. 规范覆盖	浏览规范中的每个部分/需求，能否指出实现它的任务？	列出任何缺口并添加任务
2. 占位符扫描	搜索计划中的红旗 - 任何来自"禁用占位符"部分的模式	修复它们
3. 类型一致性	后面任务中使用的类型、方法签名和属性名是否与前面任务中定义的匹配？	修复不一致

行动：发现问题就立即修复，不需要重新审查。如果发现规范需求没有对应的任务，添加任务。

---

九、执行交接

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

"计划已完成并保存到 docs/superpowers/plans/<filename>.md。有两种执行选项：

1. 子代理驱动（推荐）  - 我为每个任务分派一个新的子代理，任务之间进行审查，快速迭代

2. 内联执行 - 使用 executing-plans 在当前会话中执行任务，批量执行并设置检查点

您选择哪种方法？"

如果选择子代理驱动：

• 必需子技能：使用 superpowers:subagent-driven-development
• 每个任务一个新的子代理 + 两阶段审查

如果选择内联执行：

• 必需子技能：使用 superpowers:executing-plans
• 批量执行并设置检查点进行审查

---

十、与其他技能的关系

关系	说明
前置于	subagent-driven-development 或 executing-plans
后置与	brainstorming（必须先完成 brainstorming）
依赖	清晰的设计规范（来自 brainstorming）
为	具体的代码实现提供详细的步骤指导

---

十一、实际应用示例

示例：添加用户认证功能的计划

计划头部：

Markdown

# User Authentication Implementation Plan

> **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:** Implement user authentication with email/password and JWT tokens

**Architecture:** Use bcrypt for password hashing, JWT for token generation, and middleware for authentication

**Tech Stack:** Node.js, Express, bcrypt, jsonwebtoken, mongoose

---

任务示例：

Markdown

### Task 1: User Model

**Files:**
- Create: `src/models/User.js`
- Test: `tests/models/User.test.js`

- [ ] **Step 1: Write the failing test**

```javascript

const User = require('../../src/models/User');

test('User model should create a new user', async () => { const user = await User.create({ email: 'test@example.com', password: 'password123' }); expect(user.email).toBe('test@example.com'); expect(user.password).not.toBe('password123'); // Should be hashed });

Plain Text

- [ ] **Step 2: Run test to verify it fails**

Run: `npm test tests/models/User.test.js`
Expected: FAIL with "Cannot find module '../../src/models/User'"

- [ ] **Step 3: Write minimal implementation**

```javascript

const mongoose = require('mongoose'); const bcrypt = require('bcrypt');

const userSchema = new mongoose.Schema({ email: { type: String, required: true, unique: true }, password: { type: String, required: true } });

userSchema.pre('save', async function(next) { if (this.isModified('password')) { this.password = await bcrypt.hash(this.password, 10); } next(); });

module.exports = mongoose.model('User', userSchema);

Plain Text

- [ ] **Step 4: Run test to verify it passes**

Run: `npm test tests/models/User.test.js`
Expected: PASS

- [ ] **Step 5: Commit**

```bash

git add src/models/User.js tests/models/User.test.js git commit -m "feat: add user model with password hashing"

Plain Text

undefined

---

十二、核心价值总结

writing-plans 技能的核心价值在于：

1. 降低复杂性：将大任务分解成小步骤
2. 确保质量：通过 TDD 确保代码质量
3. 提高效率：明确的步骤减少犹豫和错误
4. 便于协作：详细的计划可以被任何人执行
5. 可追溯性：留下完整的实施记录
6. 减少返工：提前规划避免方向错误