planning-and-task-breakdown

planning-and-task-breakdown Skill 多维度简评

类别:规划 / 任务拆解 仓库:obra/superpowers 维护者:Jesse Vincent / Prime Radiant

一、核心定位与价值

writing-plans + executing-plans 是 Superpowers 中强制”先规划后编码”的姊妹技能,解决 AI 编程最常见的反模式:“看到需求直接动手 → 写到一半发现架构错”。

核心原则:为工程师创建详细的实施计划,假设他们对代码库零上下文 任务大小:2-5 分钟一个(不能更长,不能更短) 文档要求:Goal / Architecture / Tech Stack / 文件列表 / 测试策略 / 文档需求

适用场景

• 多步骤任务实施
• 跨多个文件修改
• 新增一整套功能
• API / 前端 / 测试联动
• 中大型重构

不适用场景

• 1 行 typo 修复
• 纯查询
• 探索性原型

二、writing-plans 完整工作流

2.1 触发条件

Use when you have a spec or requirements for a multi-step task, before touching code.

翻译:有 spec 或多步骤任务需求时,在接触代码前使用。

2.2 文档结构

# [Feature Name] Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
> **Goal:** [一句话描述这个 plan 构建什么]
> **Architecture:** [2-3 句话描述方法]
> **Tech Stack:** [关键技术和库]

## Tasks (bite-sized, 2-5 minutes each)

### Task 1: Write the failing test
**Files:**
- `src/services/user_service.py`

**Step 1: 写测试**
```python
def test_get_user_returns_user_from_db():
    user = user_service.get_user("user-1")
    assert user.name == "Alice"

Step 2: 跑测试看失败

pytest tests/services/test_user_service.py
# 期望: FAILED (因为还没实现)

Task 2: 实施最小代码

Files:

• src/services/user_service.py

Step 1: 写最小实现

def get_user(id):
    return db.find_user(id)

Step 2: 跑测试看通过

pytest tests/services/test_user_service.py
# 期望: PASSED

Task 3: 跑全量测试

pytest --tb=short
# 期望: 全部通过

Task 4: 提交

git add .
git commit -m "feat(user): implement get_user service"

### 2.3 必须包含的元素

| 元素 | 作用 |
|---|---|
| **Goal** | 一句话目标,避免方向跑偏 |
| **Architecture** | 2-3 句架构概述 |
| **Tech Stack** | 关键依赖 / 库 |
| **文件列表** | 每个任务改哪些文件 |
| **测试策略** | 如何验证 |
| **文档需求** | 需更新的文档 |

### 2.4 任务粒度原则

| 粒度 | 适用 | 风险 |
|---|---|---|
| **< 1 分钟** | 过度拆解,难 review | 浪费 |
| **2-5 分钟** | **最佳** | 低 |
| **5-15 分钟** | 可接受 | 中(需有检查点) |
| **> 15 分钟** | 太大,易卡 | 高(任务失败率高) |

---

## 三、executing-plans 工作流

### 3.1 5 步执行

Step 1: Load and Review Plan(加载并审查)

• 读取 plan 文件
• 识别问题或疑问
• 如有问题,开始前先问

Step 2: Execute Batch(执行批次,默认前 3 个任务)

• 标记 task 为 in_progress
• 严格按步骤
• 跑验证
• 标记完成

Step 3: Report(汇报)

• 展示实施了什么
• 展示验证输出
• 说”Ready for feedback”

Step 4: Continue(继续)

• 应用反馈
• 下一批
• 重复直到完成

Step 5: Complete Development(完成开发)

• 调用 finishing-a-development-branch

### 3.2 何时停止并询问

| 情况 | 行动 |
|---|---|
| 批次中途遇到阻碍 | 立即报告,不强行继续 |
| 计划有严重缺陷 | 停止,回到 writing-plans |
| 不理解指令 | 询问,不猜测 |

### 3.3 与 subagent-driven-development 关系

| 维度 | executing-plans | subagent-driven-development |
|---|---|---|
| **谁执行** | 主 Agent | 子 Agent |
| **适用** | 手动 / 协作 | 自动 / 大任务 |
| **Review 频率** | 每 3 任务 | 每 1 任务 |
| **上下文隔离** | 共享 | 全新 |

---

## 四、与其他 Skill 配合

| Skill | 配合方式 |
|---|---|
| **brainstorming** | 先 brainstorm 出设计,再 writing-plans |
| **test-driven-development** | 每个 task 内部用 TDD |
| **subagent-driven-development** | 大规模任务用子 agent 派发 |
| **requesting-code-review** | 每 3 任务请团队 review |
| **verification-before-completion** | 完成后 verification |
| **finishing-a-development-branch** | 最终合并 / PR |

完整工作流:

brainstorming(设计) ↓ writing-plans(规划) ↓ subagent-driven-development(执行) ↓ test-driven-development(每 task) ↓ requesting-code-review(每 3 task) ↓ verification-before-completion(验证) ↓ finishing-a-development-branch(收尾)

---

## 五、5 大反模式

### 5.1 计划过于粗略

```markdown
# ❌ BAD
## Tasks
- 实现用户认证
- 实现数据库
- 部署

# ✅ GOOD
### Task 1.1: 写 user_repository 测试
### Task 1.2: 实现 user_repository
### Task 1.3: 写 service 测试
### Task 1.4: 实现 service
### Task 2.1: 写 POST /register handler 测试
...

5.2 计划过于详细

# ❌ BAD(每行代码都写)
### Task 1.1
**Step 1: 在文件 src/foo.py 第 42 行添加 import os**
**Step 2: 在 43 行写 def foo():**
**Step 3: 在 44 行写 return 1**

解决:给方向,不给具体实现。让 AI 自己写。

5.3 没有测试策略

解决:每个 task 必含测试。

5.4 没有文件路径

解决:明确 Files: 字段。

5.5 没有 Goal

解决:第一行就是 Goal。

六、实战示例:用户认证系统

6.1 Plan 头

# User Authentication System Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans
> **Goal:** 实现邮箱密码登录,支持 JWT token,30 分钟过期
> **Architecture:** 前后端分离;后端 FastAPI + JWT;前端 React + httpOnly cookie
> **Tech Stack:** Python 3.11, FastAPI, SQLAlchemy 2.0, PostgreSQL 16, React 18, jose (JWT)

## Tasks

### Task 1: 数据库 schema
**Files:**
- `migrations/001_create_users.sql`

**Step 1: 写 migration**
```sql
CREATE TABLE users (
  id BIGSERIAL PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  password_hash VARCHAR(255) NOT NULL,
  created_at TIMESTAMPTZ DEFAULT now()
);

Step 2: 跑 migration

psql -d myapp -f migrations/001_create_users.sql

Step 3: 验证

psql -d myapp -c "\d users"

Step 4: 提交

git add migrations/
git commit -m "feat(db): add users table"

### 6.2 Spec 自查

写完后 AI 会自审：
- [ ] 没有占位符（"TODO"、"稍后实现"）
- [ ] 没有内部矛盾（前后不一致）
- [ ] 完整覆盖 spec
- [ ] 类型一致性：后续任务与前面定义的类型/签名匹配
- [ ] 每步都有验证命令
- [ ] 每步都是 2-5 分钟可执行
- [ ] 文件路径精确
- [ ] 代码完整可运行

---

## 七、5 条反合理化

| 借口 | 反驳 |
|---|---|
| "我心里有 plan" | 写出来 = 显式思考,避免遗漏 |
| "写 plan 太慢" | 写 plan 10 分钟,省 3 小时返工 |
| "AI 比我懂怎么实现" | AI 不知道**你**项目惯例 |
| "任务小不用 plan" | 5 个小任务叠加 = 大任务 |
| "plan 写了没人看" | 团队 review 必备 |

---

## 八、Q&A

**Q: 跟 OpenSpec 区别?**
A: writing-plans 输出单一 plan;OpenSpec 输出 4 工件。

**Q: 必须用 Claude 吗?**
A: 工具层面任何 Agent 都行;Skill 推荐 Claude。

**Q: 跟 executing-plans 关系?**
A: writing-plans 写;executing-plans 跑。

**Q: 任务 2-5 分钟怎么估?**
A: 看修改 ≤ 1 文件 + ≤ 1 测试 + 跑测试 ≤ 30 秒。

**Q: Plan 写到哪?**
A: 建议 `docs/plans/YYYY-MM-DD-<feature>.md`。

**Q: 跟 brainstorming 关系?**
A: brainstorming 解决"做什么",writing-plans 解决"怎么做"。

---

## 九、总结

writing-plans Skill 是 **AI 编程从"设计"到"实现"的关键桥梁**。

**核心价值**：
- 2-5 分钟任务拆分
- 完整代码、精确路径
- 易审查、易回滚、易并行

**适用人群**：
- ✅ 严肃工程项目
- ✅ 团队协作
- ✅ 复杂功能

---

> **本文基于官方文档和公开资料整理，未经过 MagicNetWorld 实测。**

## 参考资料

- [obra/superpowers 官方仓库](https://github.com/obra/superpowers) — GitHub 官方仓库
- [writing-plans SKILL.md 源码](https://github.com/obra/superpowers/blob/main/skills/writing-plans/SKILL.md) — 官方 Skill 定义
- [skilld.dev: writing-plans Skill](https://skilld.dev/gh/obra/superpowers/writing-plans) — Skill 详情
- [CSDN: Superpowers 详解](https://blog.csdn.net/kakaZhui/article/details/157023912) — 中文技术文章
- [b-lab.team: Superpowers 深度解析](https://b-lab.team/en/content/05409d6e-6fb4-436f-a3d8-37d3be367139) — 方法论分析