01 总览：把方法论装进 Agent¶

一、Superpowers 不是“另一个 Agent”¶

如果把 Claude Code、Codex、Cursor、Gemini CLI 等看成不同的 coding harness，那么 Superpowers 处在它们之上：它不替换宿主的模型调用、终端工具或文件系统，而是给宿主装上一套关于“怎样做软件开发”的过程约束。

上游 README 的定义是一个 “complete software development methodology for your coding agents”。源码进一步把这句话拆成了三个层次：

层次	代码载体	责任	不负责什么
Bootstrap	`hooks/`、各平台 manifest	在会话开始时注入入口规则	不执行实现任务
Process	`skills/*/SKILL.md`	规定何时触发、按什么顺序做、何时停下	不直接拥有宿主工具
Harness bridge	`.claude-plugin/`、`.codex-plugin/`、`.pi/` 等	把同一套过程翻译到不同宿主	不改变技能的核心思想

因此，Superpowers 更像一个过程编译器：输入是自然语言需求和当前会话，编译过程是调用一串技能，输出是设计、计划、代码、测试证据和可交付分支。

二、仓库地图：少量运行时文件，较多过程知识¶

仓库根目录可以分为五组：

superpowers-main/
├── skills/                 # 方法论主体：每个目录一个可发现技能
├── hooks/                  # 会话启动时的跨平台注入
├── .*-plugin/              # Claude/Codex/Cursor/Kimi 等 manifest
├── .opencode/ .pi/         # OpenCode 与 Pi 的适配实现
├── tests/                  # 技能、hook、平台加载和脚本的验证
└── docs/                   # 迁移说明、设计文档、计划和测试说明

有一个很值得注意的比例关系：真正负责运行时胶水的文件并不多，主要内容集中在 skills/ 下的 Markdown。这说明项目的产品不是一个运行时框架，而是对 Agent 决策过程的高密度编码。

三、核心对象之间怎么连接¶

flowchart TB
    U[用户需求] --> H[宿主 Harness]
    H -->|SessionStart| I[using-superpowers 入口规则]
    I --> D[Skill 工具 / 能力发现]
    D --> S[SKILL.md 过程协议]
    S --> T[宿主工具：读写文件 / 运行命令 / 调 Agent]
    T --> E[源码改动与测试证据]
    E --> V[verification / review]
    V --> F[finish branch]

这里的箭头不是普通函数调用，而是三种不同的连接：

Hook 用进程输出把文本送给宿主；
Skill 用名称和 description 让 Agent 知道“什么时候该调用”；
工具调用把协议落实为文件修改、命令执行、子 Agent 派发和 Git 操作。

把三种连接混在一起会造成误解。例如，using-superpowers 并不实现 TDD；它只强制 Agent 在适用时调用 TDD 技能。TDD 也不拥有测试命令；它规定红—绿—重构的证据顺序，具体命令仍由宿主根据项目选择。

四、一条完整的开发生命周期¶

源码中的技能并不是平铺的“技巧列表”，而是围绕一条生命周期排列：

发现问题：brainstorming 把想法澄清为设计，并要求分段让用户确认。
锁定方案：writing-plans 把设计变成按文件、接口、测试和提交划分的任务。
准备隔离环境：using-git-worktrees 检查是否已经隔离，再创建干净工作区并验证基线。
执行任务：简单任务使用 executing-plans，复杂任务使用 subagent-driven-development。
保证质量：新行为走 test-driven-development；异常走 systematic-debugging；完成前走 verification-before-completion。
协作审查：通过 requesting-code-review、receiving-code-review 和任务级 reviewer 形成反馈闭环。
收尾交付：finishing-a-development-branch 验证测试，随后合并、推 PR 或保留分支。

这个顺序的关键不是“每次必须调用所有技能”，而是把什么时候需要暂停、什么时候需要证据、什么时候允许并行写成显式规则。

五、最重要的设计取舍：过程优先于功能堆叠¶

1. 它把“停止条件”写进技能¶

很多 Agent 提示词只告诉模型“尽快完成任务”。Superpowers 反过来反复写“什么时候不能继续”：

设计没有获批，不能进入实施；
测试没有先失败，不能声称 TDD 完成；
根因没有确认，不能先写修复；
review 反馈没理解，不能机械改代码；
没有新鲜验证输出，不能声称完成。

这些停止条件比“请认真一点”更可执行，因为它们能映射到可观测事件：命令输出、测试状态、文件 diff、用户确认和 reviewer 报告。

2. 它把复杂性拆成多个小协议¶

subagent-driven-development 很长，但它不试图重新定义 TDD、调试或 Git worktree，而是组合这些技能。writing-skills/SKILL.md 也明确把 Skill 看作可复用技术、模式或参考，而不是一次性叙事。

这是一种典型的组合式架构：核心协议少而窄，流程编排负责把协议串起来。优点是每个技能可以独立测试和替换；代价是 Agent 必须拥有正确的发现和调用能力。

六、可以迁移到自己的 Agent 的三条方法¶

方法 1：把过程写成状态机¶

不要只写“先计划再实现”，而要写：

idea → design-draft → user-approved → plan → task-in-progress
     → tests-red → implementation → tests-green → reviewed → delivered

每个状态都应该有进入条件、退出条件和可验证证据。

方法 2：把“不会做什么”写出来¶

Superpowers 的力量不只来自步骤，还来自反模式表和 rationalization 防线。例如“这个改动太简单，可以跳过测试”正是需要被识别的风险信号。一个好的 Agent 方法论要预先回答模型最容易用来绕过流程的借口。

方法 3：把内容与宿主工具解耦¶

核心技能描述意图和流程；平台适配层只负责映射 Task、Skill、AskUserQuestion、hook 输出字段等方言。这样新增宿主时不必复制整套方法论。

小结¶

Superpowers 的“源代码”大部分是 Markdown，但它并不是普通文档。每一份 SKILL.md 都是一段面向 Agent 的可执行规约；hooks 和 manifest 把规约送进会话；测试则验证不同宿主是否能加载并遵守这些规约。理解了这个边界，后面所有章节都会变得更清晰。