Superpowers 技能体系
深度解析

一句话：任何对话开始时必须先检查是否有适用的技能，即使只有 1% 的可能性也必须调用 Skill 工具。

核心规则：

• 铁律如果某个技能有1%的可能性适用于当前任务，你必须调用它。不可协商。
• 优先级链用户明确指令（CLAUDE.md）→ Superpowers技能 → 系统默认行为
• 技能顺序流程技能（brainstorming、debugging）优先于实现技能（frontend-design、mcp-builder）

一句话：在任何实现动作之前，必须先完成设计并取得用户批准。即使是最简单的 Todo List 也要走这个流程。

九步工作流程：

1. Step 1探索项目上下文（文件、文档、最近提交）
2. Step 2如果涉及视觉问题，提供可视化伴侣（需单独一句询问）
3. Step 3一次只问一个澄清问题，优先多选题
4. Step 4提出 2-3 种方案，带利弊权衡和推荐
5. Step 5分段呈现设计，每段取得用户确认
6. Step 6将设计写入设计文档并 git commit
7. Step 7设计文档自审（占位符扫描、一致性检查、范围检查、歧义检查）
8. Step 8用户审查书面规格说明
9. Step 9过渡到 writing-plans 技能

一句话：没有先看到测试失败，就不知道它是否测试了正确的东西。先写测试→看它失败→写最少代码→看它通过→重构。

Red-Green-Refactor 循环：

• RED写一个最小的失败测试——清晰的名称、一个行为、真实代码（避免 mock）
• Verify RED运行测试确认失败，且失败原因必须是"功能缺失"而非拼写错误
• GREEN写最少代码让测试通过——YAGNI，不添加未测试的功能
• Verify GREEN运行测试确认通过，所有其他测试也保持通过
• REFACTOR清理重复、改善命名、提取辅助函数，保持测试绿色

为什么测试必须先写？实现后写的测试立即通过，这证明不了任何事——测试可能有 Bug、可能测了实现细节而非行为、可能遗漏了你在实现时忘记的边缘情况。只有看着测试先失败，你才知道它真正捕获了 Bug。

一句话：随机修复浪费时间并产生新 Bug。必须先找到根因再实施修复——治疗症状就是失败。

四阶段法：

• Phase 1 根因仔细读错误信息→稳定复现→检查最近变更→多组件系统加诊断埋点→追踪数据流
• Phase 2 模式找工作样例→对比参考实现→识别差异→理解依赖
• Phase 3 假设形成单一假设→最小化测试→一次一个变量→不知道就说"我不知道"
• Phase 4 实现先写失败测试→单一修复→验证通过→修复无效？回到Phase 1

一句话：声称工作完成而没有运行验证命令，是欺骗而非效率。证据先行，永远如此。

验证对照表：

一句话：假设执行者对我们代码库一无所知、品味可疑。记录他们需要知道的一切——每个文件的精确路径、每行代码、每条命令及预期输出。

计划文档必须包含精确的：文件路径、完整代码、完整命令和预期输出、测试代码。不允许"添加适当的错误处理"或"写测试"这样的模糊指令。

一句话：执行计划的首选方式——每个任务派一个干净上下文的子Agent实现，然后通过规格合规审查→代码质量审查两阶段门控。

实现Agent四种返回状态处理：

• DONE正常进入规格合规审查
• DONE_WITH_CONCERNS先阅读Agent的疑虑再决定
• NEEDS_CONTEXT补充缺失上下文后重新派发
• BLOCKED诊断原因：上下文不足？需要更强模型？任务太大？计划本身有误？

一句话：当没有子Agent支持时，在当前会话中按步骤执行计划，完成后用 finishing-a-development-branch 收尾。

注意：如果平台支持子Agent，subagent-driven-development 的质量会显著更高。

一句话：当面对 3 个以上互不依赖的独立问题时，派发多个Agent并行解决，将总耗时压缩到单个任务的时长。

真实案例：一次重构后6个测试失败分布在3个文件中，3个Agent并行调查——最终全部独立修复、零冲突、全量测试通过。

一句话：派发一个代码审查子Agent，给它精确审慎的上下文（而非你的会话历史），在问题扩散之前捕获它们。

一句话：收到审查反馈后，先验证再实现。永远禁止表演性感谢（"You're absolutely right!"、"Great point!"），用技术回应代替社交客套。

一句话：在开始任何功能开发前，先检测是否已在隔离环境→优先使用平台原生工具→fallback 到 git worktree。

关键安全检查：创建 worktree 前必须用 git check-ignore 验证目录已在 .gitignore 中，防止将 worktree 内容提交到仓库。

一句话：实现完成后，先验证测试→检测环境→呈现结构化选项→执行选择→清理。

一句话：创建技能就是用 TDD 写文档——先用子Agent跑压力场景（RED），看到它违规，再写技能（GREEN），然后堵住所有漏洞（REFACTOR）。

防绕过设计（Bulletproofing）：

• 关闭每个漏洞不仅说"不能这样"，还要列举具体禁止的变通方案
• 精神vs文字在开头声明"违反规则的文字就是违反规则的精神"
• 借口反驳表从基线测试中捕获Agent实际使用的借口，逐个反驳
• 红旗信号列表让Agent能自检是否正在自我合理化

Description 字段的核心教训：Description 只描述触发条件，绝不总结工作流程。测试发现——当 Description 包含流程摘要时，Agent 会按照摘要行事而不阅读完整技能。subagent-driven-development 技能因此被触发只做一次审查而非规定的两次。

Superpowers 没有教 AI 任何新技术。它教的是当压力出现时不走捷径。 几乎所有技能的"红旗信号"都是同一种模式——"快速修复"、"这个太简单了"、"之后再做"—— 这些是人类工程师在截止日期前的典型行为，而 AI 毫无保留地继承了这些坏习惯。

TDD 技能包含 10+ 种常见借口及其反驳；debugging 有 8 种；verification 也有 8 种。 这些不是装饰——它们来自与 AI Agent 的真实交互中捕获的实际借口。 Agent 在被压力测试时确实会说出"这太简单了不需要测试"，对应反驳就写在技能里。 这是 writing-skills 方法论的核心——每个借口都必须被堵住。

普通的 README 或 CLAUDE.md 给人类阅读，依赖人类的判断力判断何时应用。 Superpowers 技能是给 AI Agent 的系统提示注入——通过触发条件自动激活、 通过铁律强制执行、通过红旗信号自检。Description 字段的 "Use when..." 格式就是为了让 AI 在任务开始时自动匹配而非等人类手动调用。