superpowers-overview

一、概述

Superpowers 是一套作用于 coding agent 的行为约束系统，针对 agent 在软件开发中的特定失败模式施加流程性门禁。

Superpowers 不提供 API 或运行时校验。它通过提示词层面的行为塑形来改变 agent 的默认倾向：从”先行动再修正”转为”先确认流程再行动”。

---

二、核心机制

2.1 启动注入

会话启动时，系统将 using-superpowers 技能注入 agent 上下文。Agent 在接收用户消息之前，已被要求遵守以下规则：

• 开场必须先检查是否有相关技能适用
• 用户显式点名某技能时必须加载
• 若认为某技能有 ≥1% 可能适用，则必须加载
• 禁止以”问题很简单””先查看文件”等理由绕过技能检查
• 用户指令说明”要做什么”（WHAT），不构成”可以跳过方法论”的理由（HOW）

2.2 硬门禁

部分技能构成断言式门禁：

• brainstorming：创造性工作前必须完成设计并获批准，禁止直接实现
• test-driven-development：生产代码前必须先观测到失败测试（RED）
• verification-before-completion：声称完成前必须有新鲜的验证证据
• using-git-worktrees：实现前必须建立隔离工作空间

---

三、技能目录

Superpowers 当前包含 14 个技能，按用途分四组。

3.1 启动

using-superpowers

• 时机：每个会话开始时自动加载
• 职责：强制 agent 在响应前完成技能检查
• 规则：≥1% 可能性即需加载；用户说 WHAT 不等于可以跳过 HOW

3.2 需求至计划

brainstorming

• 时机：新功能、行为修改、方案设计前
• 职责：防止 agent 未理解需求便着手实现
• 流程：探索项目上下文 → 逐一提问澄清 → 提供 2-3 方案并说明取舍 → 分段展示设计 → 用户批准后方可进入实现阶段
• 门禁：无已批准设计，禁止任何实现动作

writing-plans

• 时机：设计已批准、需制定实现计划时
• 职责：将设计拆解为粒度可执行的任务，消除执行阶段的自由发挥空间
• 规则：
  • 假设执行者不具备项目上下文（因执行者可能为仅持有局部任务的 subagent）
  • 每步单一动作，粒度 2-5 分钟
  • 禁止 TBD、TODO 或任何占位内容

3.3 实施

using-git-worktrees

• 时机：开始实现计划前
• 职责：保护当前工作目录不受实验性变更污染
• 流程：检测是否已处于隔离环境 → 优先使用平台原生隔离工具 → 回退至 git worktree → 执行基线测试

test-driven-development

• 时机：任何新功能、缺陷修复、重构、行为变化
• 职责：防止先实现后补测试导致的假测试与需求遗漏
• 门禁：未观测到 RED（测试失败），禁止编写生产代码；若先编写实现，则删除实现重新开始

subagent-driven-development

• 时机：当前会话执行实现计划，任务彼此独立
• 职责：通过每任务独立 agent 与两阶段审查维持实现质量与上下文隔离
• 流程：主 agent 调度 → implementer 实现并自测 → spec reviewer 检查计划符合性 → code quality reviewer 审查实现质量 → 通过后进入下一任务，期间不中断询问用户

executing-plans

• 时机：已有计划但无需或不支持 subagent 时
• 职责：由同一 agent 按计划逐项执行
• 规则：执行前须批判性审查计划；严格执行每步；阻塞时停止并上报而非猜测推进

dispatching-parallel-agents

• 时机：存在两个及以上彼此独立且互不阻塞的问题域
• 职责：通过并行处理缩短执行周期
• 规则：每个并行 agent 仅接收其任务域说明，不继承主会话上下文；主 agent 在并行 agent 返回后执行整合与验证

3.4 质量保障

systematic-debugging

• 时机：缺陷、测试失败、构建失败、异常行为
• 职责：阻止无根因分析的猜测式修复
• 流程：稳定复现 → 根因调查 → 模式分析 → 单一假设提出与验证 → 修复并追加回归测试
• 规则：未完成根因调查不得开始修复；连续三次修复失败应质疑当前因果模型的正确性

requesting-code-review

• 时机：任务完成、重大功能完成、合并前
• 规则：reviewer 接收的上下文须为主会话历史的精炼子集，而非完整历史；关键问题立即修复

receiving-code-review

• 时机：收到审查反馈后
• 职责：防止无技术判断地执行 reviewer 建议
• 规则：反馈是需要评估的建议而非命令；实施前须进行技术判断与代码库现实核对；对无人调用的功能增量应执行 YAGNI 检查

verification-before-completion

• 时机：声称”已完成、已修复、可合并”前
• 门禁：无新鲜验证证据不得声称完成
• 证据递进关系：linter 通过 ≠ 编译器无告警 ≠ 构建成功 ≠ 全部测试通过。各级证据不可相互替代

finishing-a-development-branch

• 时机：全部任务完成且测试通过后
• 流程：验证测试 → 检测环境状态 → 展示选项（本地合并 / 创建 PR / 保留分支 / 丢弃）→ 执行选择 → 清理工作区
• 规则：测试未通过不得继续；创建 PR 后保留 worktree 以备后续迭代

3.5 元技能

writing-skills

• 时机：创建、修改或验证技能时
• 方法论：技能写作是作用在流程文档上的 TDD。先构造压力场景并观察无技能状态下 agent 的失败模式，再编写规则针对性堵截。验证的不是函数输出，而是 agent 行为
• 流程：构造压力场景 → 无技能执行并观察失败 → 编写最小规则集 → 有技能执行同一场景 → 验证行为是否纠正 → 搜索新绕过方式并迭代
• 规则：description 仅定义触发条件，不描述执行流程

---

四、工作流

4.1 完整流水线

[想法]
    │
    ▼
brainstorming ───────── 需求澄清,设计,审批
    │
    ▼
writing-plans ───────── 拆解为 2-5 分钟任务
    │
    ▼
using-git-worktrees ─── 隔离工作区,基线测试
    │
    ▼
subagent-driven-development / executing-plans
    │
    ├── test-driven-development: RED → GREEN → REFACTOR
    ├── requesting/receiving-code-review: 规格审查 → 质量审查
    │
    ▼
verification-before-completion ──── 分层验证[lint → build → test]
    │
    ▼
finishing-a-development-branch ──── merge / PR / cleanup

4.2 设计依据

该流水线中的每个阶段对应 agent 的一种已知失败模式：

阶段	目标失败模式
brainstorming	未理解需求即开始实现
writing-plans	计划粒度不足导致执行阶段偏移
using-git-worktrees	污染当前工作目录
test-driven-development	事后补测导致假阳性测试
subagent-driven-development	长上下文导致的关注点漂移
code review	偏差层叠累积至后期方暴露
verification-before-completion	无证据的主张式完成声明
finishing-a-development-branch	带失败合并或误删分支

4.3 实施路径选择

subagent-driven-development 与 executing-plans 为该流水线的两种实施路径：

• SDD（推荐）：主 agent 承担调度与审查职责，实施任务委托给持有新鲜上下文的 subagent。适用于任务相对独立且平台支持 subagent 的场景。
• Executing-plans：由单一 agent 按计划顺序执行。适用于计划规模较小或平台不支持 subagent 代理的场景。

两种路径共享前置约束：执行前须批判性审查计划，识别路径错误、需求遗漏或任务排序缺陷，而非盲目执行。