Superpowers 中文操作手册

using-superpowers

触发条件：每次会话开始（system prompt 强制注入）。Agent 收到任何用户消息前，必须先 check 是否有相关 skill 适用。

具体行为：

• 注入"1% 规则"：哪怕只有 1% 可能某 skill 适用，也必须 invoke
• 建立优先级：用户指令 > Superpowers skill > 默认 system prompt
• 提供 platform tool 映射（Claude / OpenCode / Gemini 各自的工具名）

为什么这样设计：

Skill 默认是被动的——Agent 想用才用。但 AI 经常"觉得不需要"而跳过 brainstorming，直接写出错误代码。using-superpowers 把"是否使用 skill"从偏好变成强制，关闭了 Agent "走捷径"的退路。

这样用的好处：

• ✅ 方法论真的会被执行：不是"AI 想起来才用"
• ✅ 用户指令永远最高：你说"skip TDD"，立即生效
• ✅ 跨平台一致：同样的 skill 在 Claude/OpenCode/Gemini 行为相同

writing-skills

触发条件：用户要求"创建新 skill"或"修改现有 skill"时自动激活。

具体行为：

• 引导你写符合 Superpowers 规范的 SKILL.md
• 强制包含 frontmatter（name + description）
• 提供测试方法论（怎么验证 skill 有效）
• 检查 skill 是否会与现有 14 个冲突

为什么这样设计：

Superpowers 官方不接受社区贡献新 skill（维护成本高）。但 Jesse 提供了 writing-skills 让你在自己的项目 / 团队内写私有 skill。这是一种"授人以渔"——核心 14 个 skill 不变，但你可以扩展。

这样用的好处：

• ✅ 团队规范代码化：把"我们项目的约定"写成 skill
• ✅ 跨项目复用：在 A 项目写的 skill 拷到 B 项目
• ✅ 方法论沉淀：踩过的坑写成 skill，团队不再重复踩

brainstorming · 入口 Skill

触发条件：你说"做一个 X"、"加一个 Y"、"改一下 Z" 时必须激活。HARD-GATE 规则：「在你完成 brainstorming 并获得用户对设计的确认前，禁止调用任何实现 skill、写任何代码、scaffold 任何项目。」

具体行为（9 步 checklist）：

1. 探索项目上下文（读文件 / docs / 最近 commit）
2. （如有视觉问题）单独发一条消息"是否要开 visual companion"
3. 苏格拉底式追问（一次只问一个）：理解目的 / 约束 / 成功标准
4. 提议 2-3 个方案，含 trade-off 和推荐
5. 分章节展示设计，每节让用户确认才继续
6. 写 design doc 到 docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md 并 commit
7. Spec 自检（看是否有占位符、矛盾、模糊、范围问题）
8. 让用户 review 写好的 spec
9. 转交 writing-plans skill

为什么这样设计：

Jesse 的核心洞察："简单"项目恰恰是浪费工作最多的地方——因为它太简单，所以没人 brainstorm，所以隐藏的假设没暴露，所以做出来不是用户想要的。HARD-GATE 把"先 brainstorm"从建议变成宪法。

"一次问一个问题" 是认知科学——人脑同时回答多问题会变烂。"分章节确认" 是为了让用户能具体反馈而不是笼统地"看着差不多"。

这样用的好处：

• ✅ 错误前置发现：在 design 阶段（5 分钟）发现 = 在代码阶段（5 小时）发现
• ✅ 有 design doc 可追溯：commit 进 git，未来可查
• ✅ 用户参与感强：每章确认 → 用户真的在共建
• ✅ 下游 skill 输入清晰：design doc 直接喂给 writing-plans

writing-plans

触发条件：brainstorming 完成后自动衔接，或你说"为这个 spec 写计划"时。

具体行为：

• 把 design doc 拆成2-5 分钟粒度的 task
• 每个 task 包含：完整代码、文件路径、测试、验证步骤
• Plan header 强制写明：Goal / Architecture / Tech Stack
• 用 checkbox（- [ ]）标记，方便后续追踪
• 保存到 docs/superpowers/plans/YYYY-MM-DD-<feature>.md

关键设计假设：执行的工程师"对项目零知识、品味差、不会写测试"。所以 plan 必须包含一切——这意味着子 Agent 拿到 plan 就能跑。

为什么这样设计：

2-5 分钟粒度不是随意定的——这是子 Agent 不偏离的最优颗粒。粒度太大（30 分钟）→ subagent 中途偏离；太小（30 秒）→ 调度开销大于实际工作。Jesse 的实测：2-5 分钟是甜点。

"假设工程师品味差" 是为了让 plan self-contained——subagent 在隔离 context 下能完成，不用回头问主 Agent。

这样用的好处：

• ✅ 每个 task 是原子的：完成 = commit，失败 = 回滚
• ✅ 可暂停可恢复：tasks.md 的 checkbox 即进度
• ✅ 多人接力友好：A 做完 1-3，B 接 4-7
• ✅ 是 subagent-driven 的输入：粒度不对则下游崩

subagent-driven-development · 招牌

触发条件：plan 已写好，用户说"开始"或"go"。需要满足：① 有 plan ② 任务多数独立 ③ 同一 session 执行。

具体行为（每 task 一个循环）：

1. 主 Agent 派 implementer subagent（带 implementer-prompt.md）
2. subagent 实现 + 测试 + commit + 自我 review
3. 主 Agent 派 spec reviewer subagent（独立 context）
4. spec reviewer 检查代码是否匹配 spec → 不匹配则 implementer 修
5. 主 Agent 派 code quality reviewer subagent（再独立 context）
6. quality reviewer 审代码质量 → 有问题则 implementer 修
7. TodoWrite 标记 task 完成，下一个 task 重复

关键纪律：连续执行不停顿。"Should I continue?" 类的提问被禁止——用户说了"开始"就一直跑到完。

为什么这样设计：

核心问题：为什么不让主 Agent直接做？答案——上下文污染。主 Agent 跑 1 小时积累的对话历史会让它后续判断变差（"我之前是不是说过 X"）。Subagent 每次拿全新 context，精确构造它需要的信息（plan + 当前 task），跑完即销毁。

两阶段 review（spec 合规 → 代码质量）也是独立 context——避免 reviewer 被 implementer 的"自圆其说"带偏。这相当于三人轮岗盯一个 task。

这样用的好处：

• ✅ 长时无人值守：可以连续 2-4 小时不偏离
• ✅ 主 Agent context 干净：保留给协调而非实现
• ✅ 三重审查：implementer + spec reviewer + quality reviewer
• ✅ 失败可定位：哪个 subagent 崩了哪个 task 失败

executing-plans

触发条件：plan 已写好，但你想"换 session 执行"或"加人工 checkpoint"。

具体行为：

• 批量执行 task 但每批后停下问用户
• 适合"开新窗口、用新 agent 跑别人写的 plan"
• 慢于 subagent-driven（有人工 checkpoint）
• 但更可控（人工干预点多）

为什么这样设计：

不是所有场景都适合 subagent-driven。比如：

• 团队成员 A 写了 plan，团队成员 B 要在自己的 session 执行
• 高风险变更需要每隔几个 task 人工 review
• token 预算紧张（subagent 多消耗 token）

这时用 executing-plans。

这样用的好处：

• ✅ 跨 session 友好：plan 写一次执行多次
• ✅ 人工 checkpoint：高风险场景安全感
• ✅ token 节约：相比 subagent-driven 省 30-50%

dispatching-parallel-agents

触发条件：你面对 2+ 个独立任务（无共享状态、无顺序依赖）。

具体行为：

• 检测任务是否真独立（如有依赖会拒绝并行）
• 用 using-git-worktrees 创建多个隔离工作区
• 派多个 subagent 同时跑各自的 worktree
• 主 Agent 等所有完成后汇总结果

为什么这样设计：

大多数 sprint 末期有 5-10 个独立小 feature（404 页 / favicon / 健康检查端点）。串行做要 6 小时，并行做 1.8 小时。独立性是关键——如果 task 2 依赖 task 1 的某个 util 函数，并行会失败。所以这个 skill 先做依赖分析。

这样用的好处：

• ✅ 3-4× 加速：相比串行
• ✅ worktree 隔离：失败的 subagent 不影响其他
• ✅ 资源利用率高：CPU 闲着不如多线程跑

using-git-worktrees

触发条件：开始 feature 工作需要隔离时；或 executing-plans 之前。

具体行为（3 步检测）：

1. Step 0：检测已有隔离 — 通过 git rev-parse --git-dir 判断当前是否已在 worktree。注意排除 submodule 误判。
2. Step 1a：用平台原生 worktree 工具 — 如果你的 IDE / harness 自带 EnterWorktree、WorktreeCreate、/worktree 命令、--worktree flag，用它而不是 git
3. Step 1b：fallback 到 git worktree add — 没有原生工具时才退回 git CLI

为什么这样设计：

"never fight the harness" 是 Jesse 的设计原则。如果你的 IDE 已经有 worktree 管理（如 Conductor），用 git worktree add 会创建幻象状态——IDE 看不见、管不了。先尊重 harness，没有时才 fallback。

Submodule 排除是真实坑——很多 setup 在 submodule 内被误判为 worktree，导致疯狂创建嵌套。

这样用的好处：

• ✅ 主分支永远干净：feature 在隔离环境跑
• ✅ 失败可丢弃：worktree 删除即回归
• ✅ 多 feature 并行：每个 worktree 一个 feature

requesting-code-review

触发条件：完成 task / 实现完功能 / 准备合并前。

具体行为：

• 对照 plan 检查每条要求是否完成
• 测试覆盖度核对（每个新功能有对应 test 吗？）
• 边界条件 checklist（empty / null / overflow）
• 错误处理 checklist（每个 await 有 catch 吗？）
• 按严重度分类问题：CRITICAL / HIGH / MEDIUM / LOW

为什么这样设计：

"自检"和"互检"差别巨大——人写完代码后倾向于"看着对"，因为大脑模式补全。requesting-code-review 强制 Agent 把 plan 当 checklist 逐条核对，而不是凭感觉。

这样用的好处：

• ✅ 客观标准：plan 写了什么必须做到
• ✅ 分级反馈：CRITICAL 的拦截合并，LOW 的可后续
• ✅ 覆盖盲区：边界条件 / 错误处理是 AI 最容易漏的

receiving-code-review

触发条件：收到 code review 反馈，特别是反馈不清楚或技术上可疑时。

具体行为：

• 不立即认错
• 验证 reviewer 的论点（reviewer 也会犯错）
• 如果反馈错误：用技术严谨性反驳
• 如果反馈正确：实现修复 + 解释思路
• 区分"主观偏好"和"客观错误"

为什么这样设计：

AI 默认是讨好型人格——人类一反对，AI 就改。这导致很多正确的代码被改坏，因为 reviewer 自己也错了但 AI 不反驳。receiving-code-review 教 Agent "performative agreement is worse than disagreement"。

这样用的好处：

• ✅ 避免"改坏"：reviewer 错时 AI 不会盲从
• ✅ 提升 review 质量：reviewer 也会更严谨
• ✅ 团队学习机会：技术分歧公开化讨论

finishing-a-development-branch

触发条件：所有 task 完成，准备做最后处置时。

具体行为：

1. 跑完整测试套件
2. 验证 baseline（之前通过的还在通过）
3. 展示 4 个选项让用户选：
   • Merge：合并到主分支
   • PR：开 Pull Request
   • Keep：保留 worktree（继续做）
   • Discard：丢弃工作（实验失败）
4. 如选 merge/PR：清理 worktree

为什么这样设计：

没这个 skill 的常见问题：feature 做完后worktree 留在那，一周后 git worktree list 里有 8 个孤儿。finishing-a-development-branch 把"收尾"变成不可跳过的最后步骤。

4 个选项覆盖所有真实情况——包括"丢弃"（PoC 失败也是常见结局）。

这样用的好处：

• ✅ 没有孤儿 worktree：项目目录干净
• ✅ "丢弃"被合法化：不需要为失败 PoC 强行 merge
• ✅ 测试 baseline 校验：合并前最后一道检查

test-driven-development · 铁律

触发条件：实现任何 feature / bugfix 之前。

具体行为（RED-GREEN-REFACTOR）：

1. RED：写一个测试（必须失败，因为函数还不存在 / 行为还没实现）
2. 验证 RED：跑测试，看到它失败。如果意外通过 = 测试有 bug
3. GREEN：写最少代码让测试通过（即使是 hardcoded）
4. 验证 GREEN：跑测试，看到全绿
5. REFACTOR：重构代码（可能从 hardcoded 改成真正算法），保证测试还绿
6. commit，进入下一个 task

违反铁律的处理：

如果你违反顺序先写了实现代码：

Don't keep it as "reference"
Don't "adapt" it while writing tests
Don't look at it
Delete means delete

→ Implement fresh from tests. Period.

Skill 会强制 Agent 删除你写的代码，重新先写 test。

为什么这样设计：

核心原则："If you didn't watch the test fail, you don't know if it tests the right thing."

这听起来教条，但有深刻原因：测试代码本身也会有 bug。如果你先写实现再写"测试"，你的测试可能是"凑出来"匹配实现的，根本不是真测——比如测试了 add(1,1) 但其实你写的是 add(a,b) { return 2 }，测试还是过！

"看到 RED" 是验证测试有效的唯一方式——只有先看到失败，才能保证 GREEN 是真的修复了问题。

这样用的好处：

• ✅ 测试有效性保障：每个测试都被验证过能 catch bug
• ✅ 设计从外向内：先想"怎么用"再想"怎么实现"
• ✅ 覆盖率自然高：每行实现代码都有对应测试
• ✅ 重构信心：32 个 test 全绿 = 行为快照锁定

systematic-debugging · 铁律

触发条件：遇到 bug / 测试失败 / 意外行为时必须激活，特别是：

• 时间紧（紧急情况下乱猜诱惑大）
• "应该改一下就好"看起来很明显
• 已经试了几次修复
• 之前的 fix 没生效
• 你不完全理解问题

具体行为（4 阶段，每阶段必须完成才能进下一阶段）：

Phase 1: ROOT CAUSE INVESTIGATION

1. 仔细读错误信息：完整读 stack trace，记下 line / file / error code
2. 稳定复现：写脚本一定能触发，否则没法验证修复
3. 追数据流：从输入到错误点，每一步状态是什么
4. 列假设：H1 / H2 / H3，每个写"如何验证"
5. 逐个验证假设：直到找到真正根因

Phase 2: ISOLATE

• 用 root-cause-tracing 子技术：反向追踪到最早的"错误注入点"
• 不是症状（页面白），是根因（getServerSideProps 用模块级变量）

Phase 3: FIX

• 用 defense-in-depth 子技术：多层防御
• L1：根因修复（最重要）
• L2：断言或 invariant，防止类似 bug 再现
• L3：监控告警，未来出问题能马上发现

Phase 4: VERIFY

• 用 condition-based-waiting：可靠等待异步条件
• 触发 verification-before-completion skill 强制出示证据
• 跑 1000 次复现脚本看是否还崩

为什么这样设计：

"症状修复"是软件工程最大祸根——表面修了，根因还在，过几天换种症状再爆。systematic-debugging 的 4 阶段是消除症状修复诱惑的护栏。

"越紧急越要慢"是反直觉但正确的——慌乱中乱试更可能引入新 bug，把 5 分钟问题拖成 5 小时。

这样用的好处：

• ✅ 真正修复：根因消除而非症状缓解
• ✅ 纵深防御：L2/L3 防御让类似 bug 不再现
• ✅ 调试可复现：每个假设和验证都记录

verification-before-completion · 铁律

触发条件：你要声称"work is complete / fixed / passing"前；或要 commit / PR 前。

具体行为（5 步 Gate Function）：

1. IDENTIFY：什么命令能证明这个声明？
2. RUN：执行完整命令（不是部分、不是上次缓存的）
3. READ：读完整输出，检查 exit code，统计失败数
4. VERIFY：输出是否真支持声明？
   • 如果否：陈述实际状态 + 证据
   • 如果是：陈述声明+ 证据
5. ONLY THEN：才能说"完成"

禁用词（红旗 - 看到 STOP）：

• "should" / "probably" / "seems to"
• "Great!" / "Perfect!" / "Done!"（验证前的满意表达）
• "trust the agent's report"（信子 Agent 的报告）
• "just this once"（只此一次）

不充分的证据：

为什么这样设计：

"声称完成而不验证 = 不诚实，不是高效"。这是 Jesse 的核心信念。AI 经常说"已修复"但实际没跑——因为它"觉得应该好了"。这种认知幻觉是软件 bug 的最大来源之一。

Gate Function 把"我觉得对"变成"我有证据证明"。这种思维习惯一旦养成，会贯穿你所有工程动作。

这样用的好处：

• ✅ 消除"AI 装作完成"：必须出示运行证据
• ✅ 消除"我觉得过了"：用客观输出代替主观感受
• ✅ 训练工程严谨：长期使用会改变你的工程直觉