Agent 方法论框架 superpowers 的支点：哪怕 1% 可能相关也必须调用技能
本文基于 superpowers 仓库 commit 44c9b2d（2026-07-27）梳理，该项目仍在持续迭代，具体行为以仓库 https://github.com/obra/superpowers 最新代码与文档为准。
大多数人给 Agent 写的规则失效，不是因为规则写得不对，而是因为规则给模型留下了「本次情况特殊」的判断空间——只要留了这个口子，模型每次都会从这个口子钻出去。 superpowers 这个 MIT 协议的开源项目，把整套开发方法论压在一条不留判断空间的规则上：只要你觉得某个技能有 1% 的可能相关，就必须调用它。更关键的是，它还附了一张表，把模型用来说服自己不调用的十二句原话逐条列出来，并在旁边写好反驳。
这篇讲的是这条规则和这张表本身：它长什么样、为什么必须写成这个形状、靠什么机制保证每次会话都生效，以及它换来了什么代价。本站已有的让 Agent 的输出约束真正被遵守和CLAUDE.md 到底该怎么写讲的是通用方法论——约束该怎么设计、项目规则文件该放什么；本篇则是一个具体项目把这套方法论落到实处的样本，看它在真实仓库里落成了哪些文件、哪些字句、哪个钩子。两边对着读会更清楚。
一、它要解决的问题：模型会给自己找台阶
技能库这种东西，绝大多数团队都建过。真正的失败点不在于技能写得好不好，而在于「该用的时候没用」。模型面对一个任务时，最自然的行为是直接动手：先问一句澄清、先翻一下代码库、先看看 git 状态。每一步单独看都合理，合起来的结果就是技能库躺在磁盘上从没被打开过。
skills/using-superpowers/SKILL.md 的开头没有铺垫，直接是一段带 <EXTREMELY-IMPORTANT> 标签的正文：
If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill.
IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
This is not negotiable. You cannot rationalize your way out of this.
注意最后那句：「你没法靠讲道理绕出去」。这句话不是修辞。它预设了读者（模型）接下来一定会尝试讲道理绕出去，并提前把这条路封死。这种写法和常见的「请优先考虑使用相关技能」是两种东西——后者是建议，前者是把判断权整个收走。
紧接着的 The Rule 一节把触发时机也钉死了：调用技能要发生在任何回应或动作之前，明确点名了三种典型的抢跑——澄清问题、探索代码库、检查文件。文档给出的反驳理由很实在：技能本身会告诉你该怎么探索、怎么收集信息，所以你不能先探索再想起技能。规则末尾留了唯一一个出口：If it turns out wrong for the situation, you don't have to use it.——事后发现不合适可以不用，但必须先打开看。这个设计很讲究：它把成本从「判断要不要用」降到了「读一遍」，于是「用不上白读了」这个借口也就没了分量。
二、那张十二行的表：把借口当作 bug 来修
规则底下是一节 ## Red Flags，一句引导语——这些念头意味着停下，你正在给自己找借口——然后是一张两列表，左列是念头，右列是现实。整张表十二行，我把其中几行照抄如下：
| Thought | Reality |
|---|---|
| ”This is just a simple question” | Questions are tasks. Check for skills. |
| ”I need more context first” | Skill check comes BEFORE clarifying questions. |
| ”The skill is overkill” | Simple things become complex. Use it. |
| ”I remember this skill” | Skills evolve. Read current version. |
| ”I know what that means” | Knowing the concept ≠ using the skill. Invoke it. |
这些句子读起来平平无奇，但请注意它们的语气：全是第一人称、口语化、带引号。这不是有人坐在桌前头脑风暴出来的「常见误区」，这是抄下来的。
证据在 skills/writing-skills/SKILL.md 里。那篇技能开宗明义：写技能就是把 TDD 用在流程文档上。它给了一张 TDD 概念映射表，其中两行直接解释了红旗表的来历——「Write test first」对应「在写技能之前先跑基线场景」，「Watch it fail」对应「记录 agent 使用的确切借口原话」（原文 Document exact rationalizations agent uses）。同一份文档的核心原则写得更直白：如果你没有亲眼看过 agent 在没有该技能时怎么失败，你就不知道这个技能教的对不对。
所以那十二行是失败会话的产物。模型说了什么，就被原样贴进表里，再配一句反驳。这也解释了为什么仓库的 CLAUDE.md 里专门有一条：不要在没有 eval 证据的情况下修改红旗表、借口清单这类「经过仔细调校的内容」（原文点名 Red Flags tables, rationalization lists）。对维护者来说，这些字句是测试用例的固化结果，不是文案。
这个模式不止用在入口技能上。在仓库的 skills/ 目录下，我数了一下，共有十四个技能目录，其中六个的 SKILL.md 里带有 Red Flags 小节。test-driven-development 那份列的是「代码写在测试前」「我已经手动测过了」「TDD 太教条了我这是务实」，而处置意见直接写在小节标题里——停下，从头来过；verification-before-completion 那份更狠，把「使用 should、probably、seems to 这类词」和「在验证之前先表达满意（Great!、Perfect!、Done!）」直接列为红旗，并在下面的借口表里回一句 Confidence ≠ evidence。同一套手法，换个场景复用。
三、支点要接上电源：会话一开始就注入
一条规则再硬，模型看不到也等于零。superpowers 解决这件事的方式是钩子。
hooks/hooks.json 注册了一个 SessionStart 钩子，matcher 写的是 startup|clear|compact——启动、清屏、上下文压缩这三个时刻都触发。它配置的命令并不直接指向脚本，而是先调一个叫 hooks/run-hook.cmd 的包装器，再由它转调同目录下的 hooks/session-start。这个包装器是个 bat 与 shell 双解的文件：Windows 上按几个固定位置去找 Git Bash，找不到就静默退出而不是报错——注入没做成，插件其余部分照常能用。被转调的 hooks/session-start 做的事非常朴素：把 skills/using-superpowers/SKILL.md 整份读出来，转义成 JSON 字符串，包进一段以 You have superpowers. 开头的 <EXTREMELY_IMPORTANT> 里，输出给宿主。
值得看的是脚本末尾那段分支。同一份内容，它按环境变量判断该用哪个字段名输出：检测到 CURSOR_PLUGIN_ROOT 就用 additional_context，检测到 CLAUDE_PLUGIN_ROOT 且不是 Copilot CLI 就用嵌套的 hookSpecificOutput.additionalContext，其余走顶层 additionalContext。脚本注释解释了为什么不能一次全发：Claude Code 会同时读取两个字段且不做去重。这类细节就是「让规则真的到达模型」要付的工程成本，想理解钩子这套机制本身的，可以配合Claude Code hooks 怎么用看。
这也是为什么仓库的 CLAUDE.md 在「新增 harness 支持」一节把话说得很重：手动把技能文件拷进 harness、用运行时 shim 包一层、需要用户每次会话手动开启——这三类都不算真集成，会被关掉。它给了一条任何人都能复现的验收测试：开一个干净会话，只发一句 Let's make a react todo list，如果 brainstorming 技能没有自动触发，集成就是假的。这条测试的价值在于它绕开了所有自我评估，直接看行为。
四、拼起来看：四个部件各管一段
| 组成部分 | 它负责什么 | 对应仓库位置 | 你什么时候会碰到它 |
|---|---|---|---|
| 1% 硬规则与 Red Flags 表 | 取消模型的跳过权，并逐条封死已知借口 | skills/using-superpowers/SKILL.md | 每次会话开头，以及你想「就这一次直接干」的时候 |
| 会话启动注入钩子 | 把入口技能全文塞进上下文，并按 harness 选对输出字段 | hooks/hooks.json、hooks/session-start | 装插件、换 harness、排查「技能怎么不触发」时 |
| 技能库本身 | 承接被触发的流程：头脑风暴、写计划、TDD、代码评审等 | skills/ 下十四个目录 | 规则触发之后的每一步实际工作 |
| 技能写法与贡献规则 | 规定技能必须由失败基线推导，并保护调校过的字句 | skills/writing-skills/SKILL.md、CLAUDE.md | 你想改一句话、或者想提 PR 的时候 |
四者之间是有依赖顺序的：钩子保证规则被看见，规则保证技能被调用，技能写法保证技能内容不是拍脑袋写的，贡献规则保证前三者不被好心人改坏。少任何一环，整套就退化成一个没人打开的文档目录。
顺带说两个容易被忽略的设计。一是入口技能最顶上还有一个 <SUBAGENT-STOP> 块：如果你是被派去执行某个具体任务的 subagent，就忽略这条规则。没有这道闸，每个子任务都会重新走一遍完整流程，直接递归爆炸。二是文末的 User Instructions 一节明确了优先级：用户指令（CLAUDE.md、AGENTS.md、GEMINI.md 以及直接要求）高于技能，技能高于默认行为。也就是说这套东西并不打算凌驾于你的项目规则之上——你写在项目规则文件里的东西仍然是最高优先级，这个分层顺序值得在部署前确认一遍。
五、边界与代价：它明确不管的那些事
它会让开发变慢，而且是设计如此。 README 只用散文交代了主线——先逼出规格、再出计划、然后让 subagent 逐任务推进；完整链条得看 skills/ 目录里那一串各自独立的技能：brainstorming 谈出规格、using-git-worktrees 开隔离工作区、writing-plans 把计划切到「一步一个动作（2-5 分钟）」、subagent-driven-development 派实现者并在每个任务后做一次评审、整条分支结束时再做一次大范围评审、test-driven-development 在实现期压着走 RED-GREEN-REFACTOR、finishing-a-development-branch 收尾。改一个拼写错误也要走完这一串，显然是过度设计。项目本身并没有提供「小改动豁免」的开关——1% 规则的强度恰恰来自不设豁免。
它会让 Agent 变啰嗦。 规则要求调用技能后先宣告一句「Using [skill] to [purpose]」，并且如果技能里有清单，就给每一项建一个 todo。你会看到大量流程性输出挤在真正的代码变更前面。上下文预算紧张、按 token 计费的场景，要提前把这笔开销算进去。
它不管领域知识。 仓库的 CLAUDE.md 明确列了不接受的贡献类型：领域专用技能、工具专用技能、只对某个项目或团队有用的配置，一律归到独立插件里去。它还是零依赖设计，需要外部工具或服务的改动同样被挡在门外。所以它不会帮你写业务逻辑、不会替你选框架，它只管「流程有没有被触发、被执行」。
它不保证结果正确。 这套机制解决的是「技能没被调用」，不是「技能内容是对的」。技能本身写错了，规则只会让错误更坚决地被执行。真正的兜底在 verification-before-completion 那类技能里——先跑验证再下结论——而那又依赖模型老老实实执行。这一层的通病可以对照Agent 谎报成功怎么办。
过度触发是它主动接受的成本。 1% 阈值必然意味着大量「打开了发现用不上」。规则给的解法是事后可以不用，但读的开销省不掉。如果你的会话大多是短问答，这笔开销的占比会相当难看。
六、上手与避坑清单
只把 skills/ 目录拷进去。 会踩是因为这个目录看起来就是全部内容，拷过去似乎就能用。结果是技能永远不触发——真正让它们活起来的是会话启动时注入的那份入口技能。避法：按 README 里对应 harness 的安装方式装，然后跑那句验收测试，只发 Let's make a react todo list，看 brainstorming 是否自动出现。
照着 Claude Code 的 JSON 格式给别的 harness 接钩子。 会踩是因为字段名看着大同小异。实际上 hooks/session-start 对 Cursor、Claude Code、Copilot CLI 输出的是三种不同结构，脚本注释还特意说明了 Claude Code 会同时读两个字段且不去重，所以必须只发一个。避法：先读那段分支逻辑，确认自己的 harness 消费的是哪个字段，再动手。
把红旗表当成可以随手润色的文案。 会踩是因为那些句子确实又长又啰嗦，看着像是能压缩。但它们是从失败会话里抄的原话，删掉一行等于放掉一个已知借口。仓库的贡献规则直接把这类内容列为需要 eval 证据才能改。避法：真要改就按 writing-skills 的路子来——先跑不带技能的基线场景，记录模型的原话，再改，再验证。
打算按「官方最佳实践」重构技能格式。 会踩是因为这看起来是纯粹的好意。CLAUDE.md 里有专门一条回应：项目的技能哲学与 Anthropic 公开的技能写作指南存在差异，为了「合规」而重排、改写、重新格式化技能的 PR，在没有 eval 证据的情况下不会被接受。避法：先理解为什么现在是这个形状，再谈改。
PR 提到 main 分支。 会踩是因为大多数项目默认分支就是收 PR 的分支。这里 main 是已发布分支，所有 PR 要求打到 dev。避法：贡献前完整读一遍 CLAUDE.md 和 .github/PULL_REQUEST_TEMPLATE.md——后者是仓库明确要求逐节填满、不许留空或占位符的。
默默让 Agent 替你提 PR。 CLAUDE.md 里有一条硬要求：提交者必须披露模型、harness、harness 版本和所有已安装插件，隐藏这些信息的贡献会被关闭；同时要求人类看过完整 diff 才能提交。避法：把这两件事当成提交流程的一部分，而不是可选的礼貌。
忘了关遥测。 README 说明，头脑风暴技能的可选可视化伴随功能会从项目网站加载一个 logo，其中包含所使用的 superpowers 版本号。要关掉的话，把环境变量 SUPERPOWERS_DISABLE_TELEMETRY 设为任意真值即可，它也遵守 DISABLE_TELEMETRY 和 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC。企业环境里这属于上线前该确认的项。
收束：先读哪两个文件
把这套东西抽象一层，它给出的其实是一个可迁移的判断：约束的强度不取决于你写了多少条，而取决于你有没有把模型的退路一条条堵上；而退路清单不能靠想，只能靠观察真实失败会话抄下来。 你现在给 Agent 写的规则里，只要还留着「视情况」「必要时」「建议优先」这类词，就等于给了它一个从来不会不用的出口。
想自己验证这篇讲的东西，按这个顺序读两个文件就够：先看 skills/using-superpowers/SKILL.md，它短到几分钟能读完，规则、红旗表、平台适配、优先级全在里面；再看 skills/writing-skills/SKILL.md 的 TDD 映射表，那张表解释了红旗表是怎么被「测」出来的。看完这两份，再回头看你自己项目里的规则文件，大概率能立刻指出哪几条是摆设。
如果你更关心「怎么防止 Agent 在长任务中偏离既定目标」这类相邻问题，Agent 目标漂移的识别与纠正是另一个角度的补充。
本文属于 superpowers 方法论专题（共 30 篇，含三篇与其它开源 Agent 项目的对照）。想看把资产铺满的另一种取向，见 ECC 开源 Agent 套件专题。