Superpowers 5.1.0 技能使用手册（中文版）

Superpowers 技能使用手册（中文版）

适用于日常开发的完整技能参考文档

版本：superpowers 5.1.0 | 更新日期：2026-06-14

概述
技能调用方式
核心工作流
技能详解
- [brainstorming --- 头脑风暴](#brainstorming — 头脑风暴)
- [test-driven-development --- 测试驱动开发](#test-driven-development — 测试驱动开发)
- [systematic-debugging --- 系统化调试](#systematic-debugging — 系统化调试)
- [writing-plans --- 编写计划](#writing-plans — 编写计划)
- [executing-plans --- 执行计划](#executing-plans — 执行计划)
- [subagent-driven-development --- 子代理驱动开发](#subagent-driven-development — 子代理驱动开发)
- [dispatching-parallel-agents --- 并行代理调度](#dispatching-parallel-agents — 并行代理调度)
- [using-git-worktrees --- Git 工作树](#using-git-worktrees — Git 工作树)
- [verification-before-completion --- 完成前验证](#verification-before-completion — 完成前验证)
- [requesting-code-review --- 请求代码审查](#requesting-code-review — 请求代码审查)
- [receiving-code-review --- 接收代码审查](#receiving-code-review — 接收代码审查)
- [finishing-a-development-branch --- 完成开发分支](#finishing-a-development-branch — 完成开发分支)
- [writing-skills --- 编写技能](#writing-skills — 编写技能)
- [using-superpowers --- 技能使用总则](#using-superpowers — 技能使用总则)
快速参考表

概述

Superpowers 是一套结构化的 AI 辅助开发技能体系，覆盖从需求分析到代码上线的完整开发周期。核心理念：

纪律优先：测试先行、根因分析、证据驱动
结构化流程：每个技能都有明确的步骤和检查清单
防合理化：内置识别和对抗"跳过流程"借口的机制

技能调用方式

在 Claude Code 中，通过斜杠命令调用技能：

复制代码

/superpowers:brainstorming
/superpowers:test-driven-development
/superpowers:systematic-debugging
/superpowers:writing-plans
/superpowers:executing-plans
/superpowers:subagent-driven-development
/superpowers:dispatching-parallel-agents
/superpowers:using-git-worktrees
/superpowers:verification-before-completion
/superpowers:requesting-code-review
/superpowers:receiving-code-review
/superpowers:finishing-a-development-branch
/superpowers:writing-skills
/superpowers:using-superpowers

核心规则：只要有 1% 的可能性某个技能适用，就必须先调用它检查。

核心工作流

典型开发流程中各技能的协作关系：

复制代码

需求/想法
  ↓
[brainstorming] --- 分析需求、设计方案
  ↓
[writing-plans] --- 编写实现计划
  ↓
[using-git-worktrees] --- 创建隔离工作区
  ↓
[subagent-driven-development] 或 [executing-plans] --- 执行实现
  ↓  (每个任务中)
[test-driven-development] --- TDD 编码
[systematic-debugging] --- 遇到 Bug 时
[requesting-code-review] --- 代码审查
[verification-before-completion] --- 验证完成
  ↓
[finishing-a-development-branch] --- 合并/PR/清理

技能优先级：流程类技能优先（brainstorming、debugging），实现类技能其次（TDD、frontend-design）。

技能详解

1. brainstorming --- 头脑风暴

触发场景：任何创造性工作之前 --- 新功能、新组件、新行为修改。

核心原则：先设计后实现，禁止未经审批就动手。

铁律：

不论项目看起来多简单，都必须先展示设计并获得用户批准。

流程清单：

步骤	说明
1. 探索项目上下文	检查文件、文档、近期提交
2. 提供可视化伴侣	如果涉及视觉问题，单独一条消息询问是否开启浏览器可视化
3. 逐个提问	一次只问一个问题，优先多选题
4. 提出 2-3 个方案	包含权衡分析和推荐
5. 展示设计	按复杂度分节呈现，每节确认
6. 编写设计文档	保存至 `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
7. 设计自审	检查占位符、矛盾、歧义、范围
8. 用户审核书面规格	等待用户确认
9. 过渡到实现	调用 `writing-plans` 技能

范围检查：如果需求涉及多个独立子系统（如"带聊天、文件存储、计费和分析的平台"），立即标记，帮助拆分为子项目。

反模式："这太简单了不需要设计" --- 简单项目恰恰是未审视假设导致最大浪费的地方。

设计原则：

拆分为边界清晰、接口明确的单元
每个单元能回答：做什么、怎么用、依赖什么
遵循现有代码库模式，不无故重构

2. test-driven-development --- 测试驱动开发

触发场景：实现任何功能或修复 Bug 之前，在编写实现代码之前使用。

铁律：

没有失败的测试，就不能写生产代码。先写代码再补测试？删掉，重来。

红-绿-重构循环：

复制代码

RED（红）→ 写一个失败的测试
  ↓
验证失败 → 确认测试因正确原因失败（功能缺失，非拼写错误）
  ↓
GREEN（绿）→ 写最少的代码让测试通过
  ↓
验证通过 → 确认测试通过、其他测试未破坏、输出干净
  ↓
REFACTOR（重构）→ 清理代码（去重、命名优化、提取辅助函数）
  ↓
验证仍然全绿 → 重复下一轮

好测试 vs 坏测试：

品质	好测试	坏测试
最小化	测试一件事	`test('验证邮件和域名和空格')`
清晰	名称描述行为	`test('test1')`
展示意图	演示期望的 API	模糊代码应做什么

关键要求：

每个测试只验证一个行为
使用真实代码（除非不得已才用 mock）
GREEN 阶段绝不添加计划外的功能
测试名称中含"和"则应拆分

常见借口与真相：

借口	真相
"太简单不需要测"	简单代码也会出 Bug，测试只要 30 秒
"我之后再补测试"	之后通过的测试什么也证明不了
"之后补测试效果一样"	后补测试回答"代码做了什么"，先写测试回答"代码应该做什么"
"我已经手动测过了"	手动测试不可重复、不可回归、容易遗漏
"删掉 X 小时的工作太浪费"	沉没成本谬误。不可信的代码才是真正的浪费

红旗 --- 必须重新开始：

先写代码后写测试
测试立即通过（说明测的不是新行为）
找借口"就这一次"
"保留作参考，再重写测试" --- 必须删除

3. systematic-debugging --- 系统化调试

触发场景：遇到任何 Bug、测试失败或异常行为时，在提出修复方案之前使用。

铁律：

不找到根因，就不允许修。修症状是失败。

四阶段流程：

阶段 1：根因调查（必须完成才能进入阶段 2）

仔细阅读错误信息 --- 完整阅读堆栈跟踪，注意行号、文件路径、错误码
稳定复现 --- 能否可靠触发？精确步骤是什么？
检查近期变更 --- git diff、新依赖、配置变更、环境差异
多组件系统收集证据 --- 在每个组件边界添加诊断日志，运行一次定位断点层
追踪数据流 --- 从错误值向上追溯源头，在源头修复而非症状处

阶段 2：模式分析

找到代码库中类似的正常工作的代码
完整阅读参考实现（不要略读）
列出工作代码和损坏代码之间的所有差异
理解依赖关系（配置、环境、假设）

阶段 3：假设与测试

明确陈述假设："我认为 X 是根因，因为 Y"
最小化测试 --- 一次只改一个变量
验证后决定：有效 → 阶段 4；无效 → 新假设
不确定时坦诚说"我不理解 X"

阶段 4：实现

创建失败的测试用例（使用 TDD 技能）
实施单一修复 --- 不搭带"顺便"的改进
验证修复 --- 测试通过？其他测试未破坏？问题真正解决？
修复无效时：如果已尝试 ≥3 次修复，停止并质疑架构

3 次修复失败规则：如果每次修复都暴露新的耦合/问题，这不是假设错误，而是架构错误。停止并与用户讨论。

常见合理化借口：

借口	真相
"先快速修一下，稍后调查"	系统调试比盲目试错更快
"就改一下 X 试试"	第一刀的模式决定后续走向
"同时改多处节省时间"	无法隔离哪个有效，且引入新 Bug
"再试一次修复"（已试 2+ 次）	3 次失败 = 架构问题，别再修了

辅助技术（同一目录下）：

root-cause-tracing.md --- 从调用栈反向追踪 Bug
defense-in-depth.md --- 在多层添加验证
condition-based-waiting.md --- 用条件轮询替代任意超时

4. writing-plans --- 编写计划

触发场景：有了规格或需求后、动手写代码之前。

核心原则：编写详尽的实现计划，假定执行者对代码库零了解。

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

计划头部格式：

markdown 复制代码

# [功能名] 实现计划

> **给代理工作者：** 必须使用 superpowers:subagent-driven-development 或 superpowers:executing-plans 逐任务执行。

**目标：** [一句话描述]
**架构：** [2-3 句方法概述]
**技术栈：** [关键技术/库]

任务粒度：每个步骤是一个 2-5 分钟的动作：

复制代码

- [ ] 步骤 1：写失败的测试（附完整测试代码）
- [ ] 步骤 2：运行测试确认失败（附命令和预期输出）
- [ ] 步骤 3：写最小实现（附完整实现代码）
- [ ] 步骤 4：运行测试确认通过（附命令和预期输出）
- [ ] 步骤 5：提交（附 git 命令）

绝对禁止的占位符（出现即计划失败）：

"TBD"、"TODO"、"稍后实现"、"填充细节"
"添加适当的错误处理"/"添加验证"/"处理边界情况"
"为上述编写测试"（但不附测试代码）
"类似于任务 N"（必须重复代码）
描述做什么但不展示怎么做

自审检查：

规格覆盖 --- 每个需求都有对应任务？
占位符扫描 --- 搜索上述禁止模式
类型一致性 --- 后续任务中的函数名/签名与前面定义的一致？

执行选择：计划完成后提供两种执行方式：

子代理驱动（推荐） --- 每任务一个新子代理，两阶段审查
内联执行 --- 当前会话中用 executing-plans 执行

5. executing-plans --- 执行计划

触发场景：有了书面实现计划需要在独立会话中执行。

流程：

加载并审查计划
- 读取计划文件
- 严格审查 --- 发现问题先提出
- 无问题则创建 TodoWrite 任务列表
逐任务执行
- 标记为进行中
- 严格按步骤执行
- 运行验证
- 标记为完成
完成开发
- 调用 finishing-a-development-branch 技能

何时停下来求助：

遇到阻塞（缺失依赖、测试失败、指令不清）
计划有关键缺口
不理解某个指令
验证反复失败

规则：不要猜测，停下来问。

6. subagent-driven-development --- 子代理驱动开发

触发场景：执行实现计划，任务基本独立，在当前会话中工作。

核心模式：每个任务派发一个新子代理 + 两阶段审查（规格合规 + 代码质量）。

流程：

复制代码

读取计划，提取所有任务文本，创建 TodoWrite
  ↓
对每个任务：
  ├─ 派发实现子代理
  │   ├─ 子代理提问？→ 回答问题
  │   └─ 子代理实现、测试、提交、自审
  ├─ 派发规格审查子代理 → 不合规？→ 实现子代理修复 → 重新审查
  └─ 派发代码质量审查子代理 → 不通过？→ 实现子代理修复 → 重新审查
  ↓
标记任务完成
  ↓
全部完成后 → 最终代码审查 → finishing-a-development-branch

模型选择策略：

任务类型	模型选择
机械实现（1-2 个文件，规格完整）	快速/廉价模型
集成与判断（多文件协调、模式匹配）	标准模型
架构、设计、审查	最强模型

子代理状态处理：

状态	处理方式
DONE	进入规格审查
DONE_WITH_CONCERNS	阅读担忧，正确性/范围问题先处理再审查
NEEDS_CONTEXT	提供缺失信息后重新派发
BLOCKED	提供上下文/更强模型/拆分任务/上报用户

红旗：

不可跳过审查（规格合规和代码质量缺一不可）
不可在规格合规 ✅ 之前开始代码质量审查
不可并行派发多个实现子代理（会冲突）
不可让实现者自审替代正式审查

7. dispatching-parallel-agents --- 并行代理调度

触发场景：面对 2+ 个独立任务，彼此无共享状态或顺序依赖。

适用条件：

3+ 个测试文件因不同根因失败
多个子系统独立损坏
每个问题无需其他问题的上下文
调查间无共享状态

不适用：

失败互相关联（修一个可能修好其他）
需要理解完整系统状态
代理会互相干扰（编辑相同文件）

模式：

识别独立域 --- 按损坏对象分组
创建聚焦的代理任务 --- 每个代理获得：具体范围、明确目标、约束条件、预期输出
并行派发 --- 所有代理同时运行
审查与整合 --- 阅读摘要、检查冲突、运行全量测试

好的代理提示：

聚焦 --- 一个明确的问题域
自包含 --- 理解问题所需的所有上下文
明确输出 --- 代理应返回什么

常见错误：

太宽泛："修复所有测试" → 应指定具体文件
无上下文："修复竞态条件" → 应附错误信息和测试名
无约束：代理可能大范围重构 → 应限制"只修测试"
模糊输出："修复它" → 应要求"返回根因和修改摘要"

8. using-git-worktrees --- Git 工作树

触发场景：开始需要隔离的功能开发，或执行实现计划之前。

核心原则：先检测现有隔离，再用原生工具，最后回退到 git。

步骤 0：检测现有隔离

bash 复制代码

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)

GIT_DIR != GIT_COMMON（且非子模块）→ 已在工作树中，跳过创建
GIT_DIR == GIT_COMMON → 需要创建工作树，先征得用户同意

步骤 1：创建隔离工作区

1a. 优先使用原生 Worktree 工具（如 EnterWorktree）

1b. 无原生工具时用 git worktree add 回退

目录选择优先级：

用户声明的偏好
已存在的 .worktrees/ 或 worktrees/
全局目录 ~/.config/superpowers/worktrees/<project>
默认 .worktrees/

安全验证 ：创建前必须确认目录在 .gitignore 中。

步骤 3：项目设置 --- 自动检测并安装依赖（npm/cargo/pip/go）

步骤 4：验证干净基线 --- 运行测试确保起点无问题

9. verification-before-completion --- 完成前验证

触发场景：即将声称工作完成、修复生效或测试通过时，在提交或创建 PR 之前使用。

铁律：

没有新鲜验证证据，就不允许声称完成。

门控函数：

复制代码

声称任何状态之前：
1. 识别：什么命令能证明这个声称？
2. 运行：执行完整命令（新鲜的、完整的）
3. 阅读：完整输出、检查退出码、计数失败
4. 验证：输出是否确认声称？
   - 否 → 用证据陈述实际状态
   - 是 → 带证据陈述声称
5. 然后才能做出声称

常见失败：

声称	必须有	不充分
测试通过	测试命令输出：0 失败	之前的运行、"应该通过"
Lint 干净	Linter 输出：0 错误	部分检查、推测
构建成功	构建命令：exit 0	Linter 通过、日志看起来不错
Bug 已修	测试原始症状：通过	代码改了，假定修好了

红旗：

使用"应该"、"大概"、"似乎"
在验证前表达满意
准备提交/推送/PR 但未验证
信任代理的成功报告

关键模式：

复制代码

✅ [运行测试] [看到：34/34 通过] "所有测试通过"
❌ "现在应该通过了" / "看起来正确"

10. requesting-code-review --- 请求代码审查

触发场景：完成任务、实现主要功能、或合并前验证工作。

何时必须审查：

子代理驱动开发中每个任务之后
完成主要功能后
合并到主分支前

如何请求：

获取 git SHA：

bash 复制代码

BASE_SHA=$(git rev-parse HEAD~1)  # 或 origin/main
HEAD_SHA=$(git rev-parse HEAD)

派发代码审查子代理（使用 code-reviewer.md 模板）
处理反馈：
- Critical 问题立即修复
- Important 问题在继续之前修复
- Minor 问题记录待后处理
- 审查者有误时用技术理由反驳

11. receiving-code-review --- 接收代码审查

触发场景：收到代码审查反馈时，在实施建议之前使用。

核心原则：先验证再实施，先提问再假设，技术正确性优先于社交舒适。

响应模式：

复制代码

1. 阅读：完整阅读反馈，不反应
2. 理解：用自己的话重述需求（或提问）
3. 验证：对照代码库现实检查
4. 评估：对 THIS 代码库技术合理吗？
5. 响应：技术性确认或有理有据的反驳
6. 实施：一次一个，逐个测试

禁止的回应：

"你说得完全对！"
"好观点！" / "很好的反馈！"（表演性赞同）
"让我现在就实现"（未经验证）

不清晰的反馈：

复制代码

如果任何条目不清楚：
  停止 --- 不要实施任何内容
  对不清楚的条目请求澄清
  原因：条目可能互相关联，部分理解 = 错误实施

何时反驳：

建议破坏现有功能
审查者缺乏完整上下文
违反 YAGNI（未使用的功能）
对此技术栈不正确
与用户的架构决策冲突

确认正确反馈的方式：

复制代码

✅ "已修复。[简述修改了什么]"
✅ [直接修复并在代码中展示]

❌ "你说得完全对！"
❌ "谢谢！"
❌ 任何感谢表达

12. finishing-a-development-branch --- 完成开发分支

触发场景：实现完成、所有测试通过后，决定如何整合工作。

流程：

步骤 1：验证测试 --- 必须全部通过才能继续

步骤 2：检测环境 --- 判断是普通仓库、命名分支工作树还是分离 HEAD

步骤 3：确定基分支

步骤 4：呈现选项

普通仓库 / 命名分支工作树 --- 4 个选项：

本地合并回基分支
推送并创建 Pull Request
保持分支现状（稍后自行处理）
丢弃工作

分离 HEAD --- 3 个选项：

推送为新分支并创建 PR
保持现状
丢弃工作

步骤 5：执行选择

步骤 6：清理工作区 --- 仅选项 1 和 4 需要清理工作树

红旗：

测试失败时不继续
不在未验证测试的情况下合并
不在无确认的情况下删除工作
不从工作树内部运行 git worktree remove

13. writing-skills --- 编写技能

触发场景：创建新技能、编辑现有技能、或部署前验证技能。

核心原则：编写技能就是 TDD 应用于流程文档。

技能类型：

类型	说明	示例
技术	有步骤的具体方法	condition-based-waiting, root-cause-tracing
模式	思考问题的方式	flatten-with-flags, test-invariants
参考	API 文档、语法指南	office-docs

SKILL.md 结构：

markdown 复制代码

---
name: skill-name-with-hyphens
description: Use when [具体触发条件和症状]
---

# 技能名称

## 概述
核心原则，1-2 句

## 何时使用
触发条件和症状列表
何时不使用

## 核心模式
前后代码对比

## 快速参考
常见操作扫描表

## 实现
内联代码或链接到文件

## 常见错误
出什么错 + 修复方式

CSO（Claude 搜索优化）：

description 字段只写"何时使用"，不写"做什么"
使用具体触发词、症状、工具名
动词优先命名：creating-skills 而非 skill-creation

TDD 映射：

TDD 概念	技能创建
测试用例	用子代理的压力场景
生产代码	技能文档
RED	无技能时代理违反规则（基线）
GREEN	有技能时代理遵守规则
REFACTOR	堵住漏洞同时保持合规

14. using-superpowers --- 技能使用总则

核心规则：在做出任何响应或操作之前，先调用可能相关的技能。

指令优先级：

用户的明确指令（CLAUDE.md、直接请求）--- 最高优先
Superpowers 技能 --- 覆盖默认行为
默认系统提示 --- 最低优先

合理化红牌：

想法	现实
"这只是个简单问题"	问题也是任务，检查技能
"我先多了解点上下文"	技能检查在澄清问题之前
"我先看看代码库"	技能告诉你怎么看
"这不需要正式技能"	如果技能存在就用
"我记得这个技能"	技能会演进，读当前版本
"技能大材小用了"	简单的事会变复杂，用它
"我先做这一件事"	在做任何事之前先检查

技能类型：

刚性技能（TDD、调试）：严格遵循，不偏离纪律
弹性技能（模式）：根据上下文适配原则

快速参考表

技能	斜杠命令	何时使用	核心铁律
brainstorming	`/superpowers:brainstorming`	任何创造性工作之前	不审批不实现
TDD	`/superpowers:test-driven-development`	写功能/Bug 修复前	没有失败测试不写生产代码
调试	`/superpowers:systematic-debugging`	遇到 Bug/失败/异常时	不找到根因不修
写计划	`/superpowers:writing-plans`	有规格后、写代码前	不允许占位符
执行计划	`/superpowers:executing-plans`	有计划要执行时	不猜测，停下来问
子代理开发	`/superpowers:subagent-driven-development`	执行计划、任务独立时	不跳过两阶段审查
并行代理	`/superpowers:dispatching-parallel-agents`	2+ 独立问题可并行时	相关问题不要并行
Git 工作树	`/superpowers:using-git-worktrees`	功能开发需隔离时	先检测再创建
完成验证	`/superpowers:verification-before-completion`	声称完成/通过/修复前	无证据不声称
请求审查	`/superpowers:requesting-code-review`	完成任务/功能/合并前	Critical 问题立即修
接收审查	`/superpowers:receiving-code-review`	收到审查反馈时	先验证再实施
完成分支	`/superpowers:finishing-a-development-branch`	实现完成、测试通过后	测试不过不合并
编写技能	`/superpowers:writing-skills`	创建/编辑/验证技能时	没有失败测试不写技能
使用总则	`/superpowers:using-superpowers`	任何对话开始时	1% 可能就先调用