Superpowers 工作流使用教程
以 /version 端点 demo 为实例，讲解如何对新需求使用 superpowers 流程。
一、流程全景
设计 → 规划 → 开发 → 测试 → 审查 → 收尾
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
brain writing TDD / pytest code verification
storm plans subagent -q review -before
ing -driven +fix -completion
核心原则：每个技能只做自己的事，输出是下一个技能的输入。不跳步，不混着做。
二、第一步：设计（brainstorming）
何时用
任何新功能、改行为、修 Bug 之前------先把模糊想法变清晰设计。
怎么用
对 Claude 说：用 brainstorming 帮我设计 <需求描述>
技能内部做了什么
- 分类你的需求为三种之一：
| 分类 |
条件 |
后续路径 |
| Spike |
可行性探测，答案比代码重要 |
2-3 句话探测 → 报告结论 |
| Bounded |
在已有代码上加小改动（新端点、新 flag） |
问几个问题 → 短设计 → 批准 → 直接实现 |
| Architectural |
新子系统、改架构、改接口 |
完整设计文档 → writing-plans |
- 你参与什么 ：回答技能的澄清问题，批准设计后才开工
Demo 回放
我：用 brainstorming 设计 /version 端点
技能：这是 Bounded 任务（在已有 FastAPI app 加小端点）
技能：问了一个问题------commit hash 怎么获取？
我：选"构建时环境变量注入"
技能：呈现短设计（3 文件、端点逻辑、免鉴权）
我：yes
→ 进入下一步
⚠️ 红线
- 不批准不开工------哪怕设计只有两句话，也要你说了 yes
- 发现隐藏复杂度 → 升级到更重的路径（Bounded → Architectural）
三、第二步：规划（writing-plans）
何时用
- Architectural 任务：brainstorming 输出设计文档后，自动接 writing-plans
- Bounded 任务：可以跳过（设计够简单），也可以写（想更规范）
怎么用
对 Claude 说：用 writing-plans 把设计拆成开发计划
技能内部做了什么
- 映射文件结构：哪些文件新建、哪些修改
- 拆 bite-size Task：每个 Task 自带测试周期，可独立 review
- 每个 Task 内用 TDD 步骤：写失败测试 → 跑红 → 最小实现 → 跑绿 → commit
- 自审：检查占位符、类型一致性、需求覆盖
- 保存 到
docs/superpowers/plans/YYYY-MM-DD-<name>.md
Demo 回放
我：用 writing-plans 拆计划
技能：3 个 Task：
Task 1: /version 端点 + 测试（7 步 TDD）
Task 2: Dockerfile GIT_SHA（3 步）
Task 3: CI 传 --build-arg（3 步）
→ 保存到 docs/superpowers/plans/2026-08-16-version-endpoint.md
计划文档的目录结构
docs/superpowers/
├── plans/ ← 实现计划
│ └── 2026-08-16-version-endpoint.md
└── specs/ ← 设计文档（Architectural 路径才有）
└── 2026-08-16-xxx-design.md
四、第三步：开发
有三种开发技能，按场景选：
| 技能 |
场景 |
特点 |
subagent-driven-development |
有计划、任务基本独立、同一会话执行 |
每任务派子代理 + 两阶段审查 |
executing-plans |
有计划、需隔离工作区（worktree）执行 |
批量执行 + 检查点 |
dispatching-parallel-agents |
多个完全独立的任务，无顺序依赖 |
并行派发 |
怎么用
对 Claude 说：用 subagent-driven-development 执行计划
对 Claude 说：用 executing-plans 按计划执行
对 Claude 说：用 dispatching-parallel-agents 并行处理 <任务列表>
Demo 回放（Inline TDD）
Task 1 Step 1: 写 test_version.py（5 个测试） ← 🔴 Red
Task 1 Step 2: pytest → 5 failed (404 Not Found) ← 🔴 确认红
Task 1 Step 3: 加 /version 端点 + exempt_paths ← 🟢 实现
Task 1 Step 4: pytest → 5 passed ← 🟢 确认绿
Task 1 Step 5: pytest -q → 79 passed ← 全量确认
Task 1 Step 6: ruff + mypy → clean ← 静态检查
Task 1 Step 7: git commit ← 提交
...同理 Task 2、Task 3
TDD 的 Red-Green-Refactor 循环
🔴 Red: 先写测试，跑它，确认失败（证明测试能抓到问题）
🟢 Green: 写最小实现让测试通过，不多写
🔄 Refactor: 清理代码，测试保护你不会改坏
五、第四步：测试
何时用
- 开发完后跑全量测试
- 遇到 Bug / 测试失败 / 意外行为 → 用
systematic-debugging
怎么用
对 Claude 说：跑一下全量测试
对 Claude 说：用 systematic-debugging 调查 <Bug 描述>
systematic-debugging 四阶段
- 根因调查：收集证据，不猜
- 模式分析：找规律
- 假设和验证：提出修复，用测试验证
- 实现：最小修复 + 测试保护
六、第五步：审查（requesting-code-review）
何时用
- subagent-driven 每个任务完成后
- 完成重要功能后
- 合并前
怎么用
对 Claude 说：用 requesting-code-review 审查代码
技能内部做了什么
- 派一个审查子代理（独立上下文，不受你的会话历史影响）
- 子代理对照 AGENTS.md 红线 + 代码质量 + 测试覆盖
- 报告 Strengths / Issues（Critical / Important / Minor）/ Assessment
Demo 回放
审查报告：
Strengths: 最小实现、模式一致、Dockerfile 最佳实践、CI 正确...
Issues:
Important #1: bare except Exception 违反 fail-fast → 收窄到 PackageNotFoundError
Important #2: fallback 路径未测试 → 补 test
Assessment: Needs fixes
→ 修了两个问题 → 80 passed → commit
七、第六步：收尾（verification-before-completion）
何时用
声称完成之前------提交前、创建 PR 前
怎么用
对 Claude 说：用 verification-before-completion 做最终验证
验证清单
| 检查项 |
命令 |
| 测试全绿 |
uv run pytest -q |
| Lint 通过 |
uv run ruff check src tests |
| 类型检查 |
uv run mypy src |
| 改动范围合理 |
git diff --stat |
八、常见场景速查
| 你要做什么 |
技能链 |
| 新建功能 |
brainstorming → writing-plans → subagent-driven-development → verification-before-completion |
| 修 Bug |
systematic-debugging → test-driven-development → verification-before-completion |
| 有实现计划 |
using-git-worktrees → subagent-driven-development 或 executing-plans |
| 声称完成前 |
verification-before-completion |
| 合并前 |
requesting-code-review → finishing-a-development-branch |
| 多个独立问题 |
dispatching-parallel-agents |
| 收到评审反馈 |
receiving-code-review |
九、辅助技能
| 技能 |
用途 |
using-git-worktrees |
创建隔离工作区，在并行开发时避免互相干扰 |
writing-skills |
创建或编辑自定义技能 |
finishing-a-development-branch |
实现完成、测试通过时，决定如何集成工作（合并/PR） |
receiving-code-review |
收到评审反馈后处理修改 |
十、本次 Demo 完整时间线
brainstorming ← 分类 Bounded，问 1 个问题，短设计，批准
↓
writing-plans ← 3 个 Task × TDD 步骤，自审通过
↓
TDD Red ← 5 tests FAIL (404)
↓
TDD Green ← 5 tests PASS (endpoint 实现)
↓
全量测试 ← 79 passed
↓
Lint + Type ← ruff ✅, mypy 不退化
↓
Commit ×4 ← feat / feat(docker) / feat(ci) / docs
↓
requesting-code-review ← 子代理审查，报 2 个 Important
↓
修审查问题 ← except 收窄 + 补 fallback test
↓
全量验证 ← 80 passed, ruff ✅
↓
Commit fix ← fix: narrow fallback + add test
↓
✅ 完成（5 commits, 本地待推）
Git 提交记录
fde3786 fix: narrow version fallback to PackageNotFoundError + add fallback test
7ac806e docs: add /version endpoint implementation plan
e92a3e9 feat(ci): pass GIT_SHA build arg for /version endpoint
59ad9d9 feat(docker): add GIT_SHA build arg for /version endpoint
ee92565 feat: add /version endpoint (version + git_sha + mode)
改动文件
| 文件 |
改动 |
src/main.py |
+importlib.metadata import, +/version endpoint, +/version exempt |
deploy/Dockerfile |
+ARG/ENV GIT_SHA (两阶段) |
.cnb.yml |
+GIT_SHA=$(git rev-parse HEAD), +--build-arg |
tests/test_version.py |
新建，6 个测试 |
docs/superpowers/plans/2026-08-16-version-endpoint.md |
新建，实现计划 |