Agent 方法论框架 superpowers 的技能文本为何写得强硬
本文基于 superpowers 仓库 commit 44c9b2d（2026-07-27）梳理，该项目仍在持续迭代，具体行为以仓库 https://github.com/obra/superpowers 最新代码与文档为准。
你写给 Agent 的规则之所以被绕过，多数时候不是它没看懂，而是你的措辞留了讨价还价的空间。 superpowers 这个 MIT 许可的开源仓库把这件事挑明了：它在 skills/writing-skills/persuasion-principles.md 里单独放了一份说服原理清单，开门见山地说 LLM 对说服手段的反应和人一样，因此”建议式”写法在需要守纪律的场合基本无效。这份文件不是营销话术，它服务的对象是这个仓库自己的技能作者——写出来的技能文本要能在压力下被真正执行。
站内已经有两篇讲通用方法论的：输出约束怎么写才会被 Agent 当回事 讲约束语句的一般规律，AI 编程提示词怎么写 讲提示词的整体结构。本篇不重复这些，它讲的是一个真实开源项目怎么把这套思路落成可核对的文件、可复制的段落形态和可执行的测试流程——你能打开仓库逐行验证的那种落地。
一、它想解决的问题：Agent 知道规则，然后在压力下把规则谈没了
先看这个项目的技能入口文件 skills/using-superpowers/SKILL.md。它的措辞强度可能会让第一次读的人不太适应：文件顶部用一个 <EXTREMELY-IMPORTANT> 标签包住一段话，大意是只要有百分之一的可能某个技能适用于当前任务，就必须调用它；如果技能适用，你没有选择权；这一条不可协商，也不能用理由绕过去。
为什么要写到这个份上？这份文件后面给了答案。它列了一张叫 Red Flags 的表，左边是 Agent 心里冒出来的念头，右边是对这个念头的直接回击。比如”这只是个简单问题”对应”问题也是任务，先查技能”；“我得先了解上下文”对应”查技能在提问之前”；“让我先看看代码库”对应”技能会告诉你怎么看，先查”；“这个技能有点小题大做”对应”简单的事会变复杂，照做”；“我记得这个技能的内容”对应”技能会更新，读当前版本”。
这张表的信息量在于：它不是凭空设想的反面案例，而是把实际观察到的开脱理由一条条钉住。文本要对抗的不是无知，是合理化。一个能写代码的模型完全有能力给”这次跳过”编出一套听起来很专业的说辞，而”建议""酌情""在可行的情况下”这类词，恰恰是给这套说辞留的接口。
| 组成部分 | 它负责什么 | 对应仓库位置 | 你什么时候会碰到它 |
|---|---|---|---|
| 说服原理清单 | 解释七条原理各自适合哪类技能、哪两条不要用 | skills/writing-skills/persuasion-principles.md | 决定一段规则该用什么语气时 |
| 技能写作主文档 | 技能的结构、命名、描述字段写法、检查清单 | skills/writing-skills/SKILL.md | 新建或修改任何一个技能时 |
| 压力场景测试方法 | 怎么设计让 Agent 想违规的场景、怎么补漏洞 | skills/writing-skills/testing-skills-with-subagents.md | 技能写完还没部署时 |
| 技能调用入口规则 | 规定回应之前必须先查技能，并给出红旗清单 | skills/using-superpowers/SKILL.md | 每次会话开始 |
| 纪律型技能范例 | 铁律 + 无例外清单 + 借口对照表的完整样本 | skills/test-driven-development/SKILL.md | 想照抄一个强硬文本的骨架时 |
| 证据型技能范例 | 把”声称完成”改造成必须先跑命令的闸门函数 | skills/verification-before-completion/SKILL.md | 想约束 Agent 别谎报成功时 |
| 平台适配参考 | 不同运行环境的工具差异说明 | skills/using-superpowers/references/ | 换到非 Claude Code 的环境时 |
顺带说一句结构规模：仓库 skills/ 目录下共有 14 个技能目录，本文引用的三份写作类文档都归在 writing-skills 一个目录里（那个目录下还有别的参考文件和脚本），references 目录下放了四个平台参考文件（antigravity、codex、gemini、pi），而入口文件正文只点名了其中三个平台——这类小的不同步在活跃迭代的仓库里很常见，你自己读的时候以目录实际内容为准。
二、七条原理，以及项目明说不要用的那两条
persuasion-principles.md 列的七条来自 Cialdini 的说服心理学框架，文件把每条都翻译成了技能文本里的具体写法，并给出正反例。
权威（Authority）：用祈使语气和不可谈判的措辞，“YOU MUST""Never""Always""No exceptions”。文件给的正例是”先写代码再写测试？删掉，重来，没有例外”，反例是”在可行的时候可以考虑先写测试”。它对这条的解释很实在——绝对化的措辞消除了决策疲劳，Agent 不用再花心思判断”这算不算例外”。
承诺（Commitment）：要求 Agent 先做出声明或显式选择，再让后续行为与声明保持一致。落地写法包括”必须宣告：我正在使用某某技能”，以及强制在 A、B、C 之间选一个，还有用待办清单逐条追踪。反例是”可以考虑告诉你的伙伴你在用哪个技能”。
稀缺（Scarcity）：把要求绑在时间点上。“在继续之前""紧接着 X 之后立刻”，用于阻止”我待会儿再做”。正例是任务完成后立刻请求代码评审再往下走，反例是”方便的时候评审一下代码就行”。
社会认同（Social Proof）：用普遍性措辞建立规范，“每一次""总是”，以及”没有 Y 的 X 就是失败”这种失败模式陈述。正例是”检查清单不配待办追踪，步骤必然被跳过，每次都是”。
同一性（Unity）：用”我们是同事""我们的代码库”这类共同体语言，适合协作型而非命令型的场景。正例是”我们是一起工作的同事，我需要你诚实的技术判断”，反例是”如果我错了你或许可以告诉我”。
剩下两条是这份文件里最值得单独拎出来的部分，因为它们讲的是不要用什么。
互惠（Reciprocity）：文件建议少用，理由是容易显得像操纵，在技能场景里几乎用不上。
好感（Liking）：文件直接写了大写的”不要用于换取服从”，理由是它与诚实反馈的文化冲突，会制造迎合。在需要执行纪律的地方，永远避免。
这两条其实解释了很多提示词失效的原因。用”拜托你一定要……""你做得很棒，接下来请……”这种口吻去要求 Agent 守规则，得到的往往是更顺从的语气和同样跑偏的行为。文件还配了一张按技能类型选原理的表：纪律型用权威 + 承诺 + 社会认同，避开好感与互惠；技巧指导型用适度权威 + 同一性，避开重权威；协作型用同一性 + 承诺，避开权威与好感；纯参考型只讲清楚就行，不用任何说服手段。最后一行尤其重要——API 文档式的内容强行加祈使语气，只会让它变得难读。
至于为什么这套对模型有效，文件给的解释是”LLM 是类人的（parahuman）“：训练语料里权威语气后面往往跟着服从，承诺序列（先声明后行动）被反复示范，社会认同的句式本身就在确立规范。它引用的实证依据是 Meincke 等人 2025 年的研究，称在两万八千组对话上测试这七条原理后，服从率从 33% 升到 72%。这是文件里原样写的引用，你要用来支撑决策的话，建议自己回去看原始论文。
三、原理落到文本上，只有四种形态
原理本身不能直接写进技能。writing-skills/SKILL.md 的”Bulletproofing Skills Against Rationalization”一节给出的是可以照抄的段落形态，test-driven-development/SKILL.md 则是一份把这四种形态全用上的完整样本。
第一种是铁律（The Iron Law），用代码块单独框起来的一句话。TDD 技能里是”NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST”，验证技能里是”NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE”。写成代码块是有意的——它在视觉上把这句话从周围的说明文字里拎出来，让它不像建议。
第二种是无例外清单，紧跟在铁律后面，逐条堵死具体的变通路径。TDD 技能的写法是：先写了代码再写测试？删掉，重来。没有例外：不要留着当”参考”；不要在写测试时”改造”它；不要去看它；删掉就是删掉。文件专门对比了改造前后——只写”删掉”是不够的，因为”留着当参考”这条路没被堵。
第三种是借口对照表，两列，左边是从测试里逐字记下来的开脱理由，右边是回击。TDD 技能那张表里有”太简单了不用测""我待会儿补测试""已经手动测过了""都花了几小时，删掉太浪费”这些条目。右边的回应不讲大道理，讲机制：事后写的测试写完就通过，什么都证明不了；事后写的测试被你已经写好的代码带偏，你只会验证你记得的情况；沉没成本已经花了，真正的选择是重写还是在不可信的代码上补测试。
第四种是红旗清单，把”你正要违规”的信号列成一排短句，方便 Agent 自查。TDD 技能列的包括”测试立刻就通过了""说不清测试为什么失败""就这一次""这次不一样，因为……”，收尾统一是一句”以上任何一条都意味着：删掉代码，用 TDD 重来”。
还有一条容易被忽略的配套要求：技能的 description 字段里要写”你即将违规时的症状”，而不是写这个技能干了什么。writing-skills/SKILL.md 明确说描述字段只描述触发条件，绝不概括流程，并给了原因——测试中发现，当描述里概括了流程，Agent 会照着描述执行而不去读技能正文，一个写着”任务之间做代码评审”的描述导致 Agent 只做了一次评审，而技能正文的流程图里明明是两次。改成只写触发条件之后，Agent 才去读了正文。
四、什么时候不该用强硬语气
这是这套材料里最反直觉、也最实用的一段。writing-skills/SKILL.md 有一节叫”Match the Form to the Failure”，意思是动笔之前先给失败分类，因为让某一类失败无懈可击的形式，会在另一类失败上明显起反效果。
它给的分类是四种。第一种，Agent 明知规则却在压力下跳过——用禁令 + 借口对照表 + 红旗清单，别用”建议""考虑”这种软措辞。第二种，Agent 照做了，但产出的形状不对（提示词臃肿、结论被埋在中间、把需求原样复述一遍）——这时候要给正面配方或者输出契约，直接说明产出由哪几部分按什么顺序组成，不要用禁令清单。第三种，Agent 在已有产出里漏掉了某个必需元素——用结构性手段，在模板里加一个必填字段或槽位，而不是在模板旁边写提示语。第四种，行为应当取决于某个条件——写成挂在可观察谓词上的条件句（“如果简报存在，就引用它”），而不是”无条件规则 + 豁免条款”。
关于第二种为什么禁令会反噬，文件给了具体依据：在针对派发提示词写法的对照测试中，用禁令的那一组产出的不需要内容明显多于用配方的那一组，两组分布完全分开，而且相对不给任何指导的对照组还呈现出变差的趋势。文件同时提醒这个结论别照单全收，拿你自己的用例微测一遍。它对此的解释是，在有竞争性动机的情况下（比如”让提示词自包含”），Agent 会跟”不要做 X”谈判；而配方没有可谈判的东西——产出要么符合陈述的形状，要么不符合。
文件还补了两条通用规则，都很锋利。一是不要加细微差别条款：“别做 X，除非它很重要”会重新打开谈判，在同一组措辞测试里，给一个本来有效的配方追加一句这样的条款，结果从稳定退化成了不稳定。真的存在例外，就把它写成挂在可观察条件上的独立条件句。二是豁免条款不会生效：“这条长度限制不适用于代码块”这种写法，仍然会压制代码块；如果产出的某一部分必须豁免，就重新组织结构，让规则够不到它。
五、边界与代价
这套东西不是免费的，项目自己在文档里就承认了不少代价，剩下的是读的时候能推出来的边界。
它明确划出了不该用技能来解决的那一片。 writing-skills/SKILL.md 讲什么时候该建技能的那一节，反面清单写得比正面还具体：一次性方案不写、别处已有充分文档的标准做法不写、项目专属约定放到你的指令文件里而不是技能里、能用正则或校验器机械约束的东西直接自动化——文档留给需要判断力的事情。这条界限画得很清楚：能用程序卡住的，不要用文字劝。
它对小改动是过度设计。 入口文件要求任何回应之前先查技能，并且规定技能里带检查清单的就得逐项建待办；写技能本身则要求先跑基线场景再动笔。改一个错别字、调一个常量，这套流程的开销远大于收益。项目自己也留了口子——入口文件末尾写明用户指令优先于技能，只有在你的人类伙伴明确要求时才跳过技能流程；<SUBAGENT-STOP> 标签也让被派去执行具体任务的子代理直接忽略这条入口规则。
它会让开发变慢，也会让 Agent 更啰嗦。 强制宣告”我正在使用某某技能”、强制逐条建待办、强制在声称完成前跑一遍验证命令——这些都会占用输出篇幅和上下文。验证技能里那个闸门函数要求识别命令、完整执行、读全部输出、核对退出码和失败数，然后才允许说”通过”。它换来的是不谎报，代价是每一步都更重。上下文窗口紧张的长任务里，这笔账得自己算。
写技能这件事本身有硬性前置。 项目给技能写作定的铁律是”没有失败的测试就没有技能”，而且明确说这条同样适用于对既有技能的编辑，不为”只是加一节""只是更新文档”开例外。测试方法在 testing-skills-with-subagents.md 里：跑压力场景，文件给的压力类型有七种（时间、沉没成本、权威、经济、疲惫、社交、实用主义），并要求一个场景里至少叠加三种，逐字记录 Agent 的开脱说辞，再针对这些说辞补文本。这套流程要真做，成本不低。
强硬措辞不是万能的。 前面第四节已经说了，用错地方会反效果。而且这套材料的证据来源是该项目自己的测试和它引用的研究，你的模型、你的任务、你的上下文都不一样。文件自己给的建议是：微测试你自己的用例，别想当然。
六、上手与避坑清单
从只读一份文件开始，别一次搬整套流程。 会踩的坑是：看到 14 个技能觉得都有用，一口气全塞进配置，结果每次会话都在读技能，正事的上下文被挤掉。避法是先只读 persuasion-principles.md 那张按技能类型选原理的表，把你现有提示词里最容易被绕过的那一条重写一遍，看有没有变化。
动笔前先给失败分类，别默认用禁令。 会踩的坑是：看完权威那一节，把所有提示词都改成”YOU MUST”和”绝不”，结果格式类问题不但没改善还更糟——这正是文件里对照测试观察到的现象。避法是先问自己：Agent 是知道规则不做（纪律问题），还是做了但形状不对（形状问题）？前者用禁令，后者写配方。
借口对照表必须来自真实观察，不能自己编。 会踩的坑是：凭想象写一排”常见错误”，Agent 实际用的说辞根本不在表里，表就成了摆设。避法是先不给规则跑几次，把 Agent 实际说出口的话原样记下来再填表——testing-skills-with-subagents.md 反复强调的就是”逐字记录”。
别在描述字段里概括流程。 会踩的坑是：为了让描述更清楚，把技能干什么写进去，结果 Agent 照着描述执行、跳过正文，多步流程被压成一步。避法是描述只写触发条件，用”Use when……”开头。这个坑在自定义技能上很常见，配套可看 Claude Code Skills 怎么用。
给规则留的例外要挂在可观察条件上。 会踩的坑是：写”除非情况特殊""在合理的范围内”，这些词没有判定依据，Agent 每次都能判自己特殊。避法是把例外写成”如果某个文件存在""如果测试数为零”这类能当场核验的条件。这和验收标准的写法是一个道理，见 Agent 验收标准怎么定。
别把项目专属约定写成技能。 会踩的坑是：把”我们团队用四空格缩进”这种约定包装成技能，技能库迅速膨胀，真正需要判断力的内容被淹没。避法照文档的分工来：项目约定放指令文件（怎么写见 CLAUDE.md 怎么写），能机械校验的直接自动化，技能只留判断题。
收尾：先改一句，再决定要不要改一套
这套材料最能立刻用上的，其实是一个自检动作。翻出你最常用的那份提示词，逐条问：
- 这一条是纪律要求还是格式要求？纪律用禁令，格式用配方。
- 这一条留了哪些没堵死的变通路径？把它们逐条写出来，附在规则后面。
- 这一条里有没有”酌情""尽量""除非必要”？有就删掉，或者换成可核验的条件。
- 这一条的例外，Agent 能不能自己判定成立？能就不算例外，算漏洞。
- 我是不是在用讨好的语气要求它守规则？是就改掉。
想继续往下读，顺序建议是：skills/writing-skills/persuasion-principles.md 看原理，skills/test-driven-development/SKILL.md 看这些原理组合成完整文本长什么样，skills/writing-skills/testing-skills-with-subagents.md 看怎么验证你改的措辞真的有用。三份都不长，读完你会对自己提示词里的每一个”建议”重新起疑——这大概就是它想达到的效果。
本文属于 superpowers 方法论专题（共 30 篇，含三篇与其它开源 Agent 项目的对照）。想看把资产铺满的另一种取向，见 ECC 开源 Agent 套件专题。