# 治AI瞎改代码：superpowers「铁律型」Skill 逐段拆解 ## 概述 本期换个此前没做过的角度：不横评「帮你做事」的 Skill，而是深拆「拦着 AI 别做蠢事」的 Skill。这一品类目前没有公认中文名，本文称之为**约束型（guardrail）Skill**——它不提供新能力，只重塑 AI 的行为回路：禁止未定位根因就改代码、禁止没跑验证就宣布完成、禁止对 review 意见表演式认同。 拆解对象是 obra/superpowers 框架中最能体现这一设计流派的三份 SKILL.md：`systematic-debugging`、`verification-before-completion`、`receiving-code-review`（全文已逐段读取）。核心发现有两个：其一，在 SkillsMP 的类目统计里，Debugging 是全部 23 个领域中的最大单一类目（296,370 条，超过第二名 Sales & Marketing 之外的多数类目；全站共 2,495,308 条 Skill、219,300 个创作者）——但绝大多数是「怎么做」型，superpowers 这种「不 许 做 什 么」型是其中结构最激进的一支；其二，这三份文件共用一套可复用的写法模式（铁律代码块、反合理化表、红旗清单、阶段门升级规则），完全可以直接搬去写你自己的 Skill。 ## 一、生态坐标：约束型 Skill 在哪一格 ```mermaid mindmap root((开发者效率类
Skill 生态)) 流程型: 教AI按流程做 tdd (mattpocock, 72.2万安装) test-driven-development (superpowers) tdd-workflow (ECC, 80%覆盖率门禁) 架构型: 教AI怎么设计 improve-codebase-architecture (74.7万) hexagonal-architecture (ECC) codebase-design (43.6万) 诊断型: 教AI怎么查 diagnosing-bugs (43.0万) codehealth-mcp (CodeScene量化门禁) 约束型: 禁止AI乱来(本期) systematic-debugging verification-before-completion receiving-code-review 流转型: 交接与收尾 handoff (62.8万) triage (62.4万) finishing-a-development-branch ``` 先交代底盘数据（2026-08-29 抓取）：skills.sh 全量安装榜显示总安装量 1,273,375 次（All Time 标签计数），榜单前 12 名里 mattpocock 系占 9 席；obra/superpowers 的 `brainstorming` 出现在 SkillsMP「Popular picks」 curated 位，框架仓库描述为 "An agentic skills framework & software development methodology that works."，2025-10-09 创建，最近一次推送 2026-08-13，MIT 协议，主语言 Shell，`skills/` 目录下共 14 个 Skill。它的 14 个 Skill 里至少 6 个（brainstorming、writing-plans、executing-plans、subagent-driven-development、using-git-worktrees、finishing-a-development-branch）属于流程型，而本期拆的三个约束型是它区别于其他框架的「人格底座」——先装刹车，再装引擎。 ## 二、评测对比表 | Skill | 作者/来源 | 功能完整度 | 设计质量 | 实战效果 | 上手难度 | 社区活跃度 | 综合 | |---|---|---|---|---|---|---|---| | systematic-debugging | obra/superpowers | ★★★★★ | ★★★★★ | ★★★★☆ | ★★★★★ | ★★★★☆ | **4.6** | | verification-before-completion | obra/superpowers | ★★★★☆ | ★★★★★ | ★★★★☆ | ★★★★★ | ★★★★☆ | **4.4** | | receiving-code-review | obra/superpowers | ★★★★☆ | ★★★★☆ | ★★★★☆ | ★★★★☆ | ★★★★☆ | **4.1** | | hexagonal-architecture | affaan-m/ECC | ★★★★☆ | ★★★★☆ | ★★★☆☆ | ★★★☆☆ | ★★★☆☆ | **3.6** | | codehealth-mcp | affaan-m/ECC | ★★★★☆ | ★★★☆☆ | ★★★★☆ | ★★☆☆☆ | ★★★☆☆ | **3.5** | 评分依据：superpowers 三项基于 SKILL.md 全文逐段分析 + 仓库元数据（Issue 数 288、持续推送）；后两项基于 SkillsMP 收录的描述与更新时间，**未做全文拆读**，实战效果分为社区收录热度推断，仅供参考。社区活跃度对三者取框架整体数据（GitHub API 显示 27 万+ star、2.45 万 fork，2026-08-29 抓取；此数字为 API 返回值，与网页端展示存在缓存差异，量级供参考）。 ## 三、深度拆解：systematic-debugging ### 3.1 frontmatter：触发器设计是「时机」而非「关键词」 ```yaml name: systematic-debugging description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes ``` 注意这个 description 的构造：三个触发场景（bug / test failure / unexpected behavior）+ 一个**时序约束**（before proposing fixes）。它没有罗列任何关键词。对比同站收录的 `prompt-optimizer`（affaan-m/ECC）那种写法——显式罗列 "optimize prompt"、"优化prompt" 等十几个触发词和反向排除词——superpowers 选择把「什么时候必须用」压进一句话。这两种流派各有取舍：关键词列表触发更确定但易漏，时机描述覆盖面广但依赖模型对「encountering a bug」的自我判断。对于约束型 Skill，时机式写法是更优解，因为你的目标恰恰是「在 AI 自己没意识到需要约束的时刻」介入。 ### 3.2 The Iron Law：一个代码块挡住整条歪路 ```text NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST If you haven't completed Phase 1, you cannot propose fixes. ``` 这是全文最值得抄的设计。它用代码块（不可误译、不可复述变形的格式）承载一条**可判定的禁令**——不是「应该先找根因」这种软建议，而是「没完成 Phase 1 就不许提修复」的硬门禁。可判定性是关键：模型能自己检查「我做了没」，从而把外部约束转化为自我审查。 ### 3.3 When to Use：反向心理学写法 「Use this ESPECIALLY when」列表是全文最精彩的一段： - Under time pressure (emergencies make guessing tempting) - "Just one quick fix" seems obvious - You've already tried multiple fixes - Previous fix didn't work 常规 Skill 的适用场景列表回答「何时启用」，这一段回答的是「**何时你最想跳过我、而那一刻你最需要我**」。它把「时间压力大」「看起来有显然的快速修法」这些通常导致流程被绕过的情形，显式声明为流程的强触发条件。后面还补了三条 Don't skip（issue 看起来简单 / 你在赶时间 / 老板催），每一句都在封堵一条真实的绕路动机。 ### 3.4 四阶段流程与升级规则 ```mermaid flowchart TD A[Phase 1 根因调查
读错误/复现/查变更/埋点取证] -->|完成| B[Phase 2 模式分析
找同库可用样例·对比差异] B --> C[Phase 3 假设与最小验证
单一假设·一次改一个变量] C -->|假设成立| D[Phase 4 实现
先写失败测试·单一修复·回归验证] C -->|假设失败| A D -->|修复无效| E{已试几次?} E -->|< 3次| A E -->|≥ 3次| F[STOP: 质疑架构
与人类讨论 是否推翻模式] D -->|通过| G[完成·关联 verification-before-completion] ``` 两个工程细节值得注意。**其一，多组件系统的取证协议**：Phase 1 里给出了一段可直接照抄的 bash 埋点示例（对 CI → build → signing 这类多层链路，在每个组件边界打印进/出数据），并明确顺序——「Run once to gather evidence showing WHERE it breaks，THEN analyze」。这把「先取证再分析」从口号变成了操作手册。**其二，3 次失败升级规则**：同一 bug 修 3 次以上还没好，指令不是「再试一次」，而是强制升级为架构质疑（"This is NOT a failed hypothesis - this is a wrong architecture"），且必须先与人类讨论。这是全文里唯一一处允许打破流程的出口，而出口通向的是「停下来找人」，不是「换个姿势继续猜」。 ### 3.5 红旗清单与反合理化表：写给模型的「自查镜」 红旗清单用第一人称内心独白触发： - "Quick fix for now, investigate later" - "Just try changing X and see if it works" - "It's probably X, let me fix that" 紧接着的反合理化表逐条配对「借口 → 现实」，例如「Emergency, no time for process → Systematic debugging is FASTER than guess-and-check thrashing」。这两段本质是把人类 code review 里资深工程师对新人的口头纠正，预先写成模型可自查的触发词。`receiving-code-review` 里还有同款结构的进阶版（见第四节）。 ### 3.6 渐进披露与「实战数据」的边界 文件尾部引用了同目录三个支撑文件（`root-cause-tracing.md`、`defense-in-depth.md`、`condition-based-waiting.md`）和两个兄弟 Skill（`test-driven-development`、`verification-before-completion`）——主文件保持可装载的精炼度，深技术下沉到按需读取的子文件，这是对渐进披露原则的标准实现。 需要标注的一点：文末 "Real-World Impact" 给出的量化数字（系统化 15-30 分钟 vs 乱试 2-3 小时；一次修复率 95% vs 40%）**是作者自己 debug 会话的记录，未经独立验证**，引用时应当注明出处而非当作普适基准。 ### 3.7 安装 ```bash # 方式一：skills.sh CLI（支持 Claude Code / Cursor / Codex 等 20 个 agent） npx skills add obra/superpowers # 方式二：手动装入 Claude Code 全局技能目录 git clone https://github.com/obra/superpowers ~/.claude/skills-tmp cp -r ~/.claude/skills-tmp/skills/systematic-debugging ~/.claude/skills/ ``` ## 四、verification-before-completion：给「宣布完成」上锁 如果说 debugging 管「动手前」，这份管「收工前」。它的 Iron Law 是： ```text NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE If you haven't run the verification command in this message, you cannot claim it passes. ``` 三个设计点： **Gate Function 五步**：IDENTIFY（什么命令能证明这个结论）→ RUN（完整重跑）→ READ（读全量输出和退出码）→ VERIFY → ONLY THEN claim。第一步是最容易被忽略的——多数「AI 报喜不报忧」事故的根源是模型根本没想到「有一个命令可以证明这句话」。 **Claim/Requires 对照表**：把每种常见声明映射到充分证据。「Tests pass」要求本次运行 0 failures，上一次的运行结果和「should pass」都算数不足；「Bug fixed」要求**针对原始症状**的测试通过，而不是「代码改了就当修了」；「Agent completed」要求查 VCS diff，**不信子 agent 的成功汇报**——这一条在多 agent 工作流里价值极高。 **词汇级红线**：把 "should"、"probably"、"seems to" 以及 "Great!"、"Done!" 这类提前满足的感叹直接列为 STOP 信号。这是在词汇粒度上拦截「成功学话术」，配合反合理化表（"I'm tired → Exhaustion ≠ excuse"）构成双重防线。 短板也说清楚：这份文件对「验证什么」没有领域知识，它假设你已有正确的测试/构建命令；在一个没有测试套件的仓库里，它会退化为「跑个 build 就算验证」。它是门禁，不是测试策略——测试策略要靠 `test-driven-development` 那一份补位。 ```bash npx skills add obra/superpowers # 与上同源，随框架一起安装 ``` ## 五、receiving-code-review：把「您说得对」列为违规 三份里最有「性格」的一份。frontmatter 同样是时机式触发："Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable"。 核心禁令非常有辨识度： ```text NEVER: - "You're absolutely right!" (explicit instruction-file violation) - "Great point!" / "Excellent feedback!" (performative) - "Let me implement that now" (before verification) ``` 它针对的是对齐研究中公认的表演性顺从（sycophancy）问题，给出的替代行为是：复述技术要求、问澄清问题、用技术理由反驳、或者直接开工。几个实战向细节： **澄清优先于动手**：收到 1-6 条意见、看懂 4 条时，正确动作是先问清 2 条再动任何一条——"Items may be related. Partial understanding = wrong implementation."。这直接反直觉于「先做会的，边做边问」的默认习惯。 **YAGNI grep 检查**：reviewer 建议「把这个功能实现得专业点」时，先 `grep codebase for actual usage`，没人调用就反问要不要直接删。把抽象原则落成了一条具体命令。 **区分意见来源**：来自人类伙伴的反馈理解后即可执行（但仍需问清 scope）；来自外部 reviewer 的要先过五项检查（对本 codebase 是否正确/是否破坏现有功能/现状是否有历史原因/跨平台是否成立/reviewer 是否掌握全貌），有冲突且涉及既有架构决策时必须先停下来找人类。 **甚至管到了 GitHub API 用法**：回复 inline review 要用 `gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies` 回在评论串里，而不是顶层 PR 评论。约束型 Skill 里嵌一条具体到 API 端点的操作指令，这种「铁律 + 管道知识」混排是它的特色。 ## 六、设计模式提炼：抄这三份文件的五个套路 1. **铁律代码块**：全篇唯一不可协商的规则放进代码块，用大写祈使句，配一句可判定的执行语义（「没做 X 不得做 Y」）。 2. **反合理化表**：两列表格，左列是模型（和人）真实会冒出的借口原文，右列一句话拆掉。写法上要从你自己的失败会话里摘原话，越像内心独白越有效。 3. **第一人称红旗清单**：把「AI 即将跑偏时脑子里的那句话」列成清单，让模型在生成这类句式时自我察觉。与反合理化表互为正反面。 4. **阶段门 + 升级出口**：流程分阶段、逐段设完成判据；同时必须给一条逃生通道（如 3 次失败→质疑架构→找人类），否则模型会在死胡同里无限循环。没有出口的铁律会被模型自己合理化掉。 5. **兄弟 Skill 显式互链**：在流程节点处点名调用另一个 Skill（Phase 4 写失败测试时点名 test-driven-development），把单文件 Skill 组合成方法学。 这五个套路共同指向一个原则：**约束型 Skill 的质量取决于它对「失败模式」的想象力，而不是对「正确流程」的描述力**。你在写自己的版本时，最有价值的输入是你自己 transcript 里那些翻车记录——verification-before-completion 文末那句 "From 24 failure memories" 就是明证：这份文件是从 24 次真实事故里长出来的。 ## 七、横向参照：两个非 superpowers 的同类项 **hexagonal-architecture**（affaan-m/ECC，2026-08-12 更新）：定位是「设计、实现并重构 Ports & Adapters 系统」，触发场景写得很准——"when domain logic has become entangled with I/O"。它与 superpowers 属于不同物种：ECC 是知识型（告诉你六边形架构是什么、怎么分层），superpowers 是行为型（管住你动手的顺序）。值得借鉴的是它的触发描述把「症状」写进了 description（领域逻辑和 I/O 缠在一起时触发），这和 systematic-debugging 的时机式触发是同一思路在不同品类上的应用。 **codehealth-mcp**（affaan-m/ECC，2026-08-11 更新）：接 CodeScene MCP 做「结构性代码健康度」的实时门禁——编辑前看基线分、改完后看分数变化、commit/PR 前设阈值。这是约束型思路的**工具化路线**：superpowers 用纯提示词约束行为，codehealth-mcp 把约束外置到量化指标上。两者互补性大于竞争——前者管过程，后者管结果。短板也明显：强依赖外部 MCP 服务与 CodeScene 授权，上手成本比纯文本 Skill 高一档。 另外提一句避嫌：mattpocock 的 `tdd`（72.2 万安装）与 `improve-codebase-architecture`（74.7 万安装）属于流程型/架构型头部，此前已单独拆过，本文不再重复；它们与 superpowers 系的最大差异是 Matt 的 Skill 以「对话式引导」为主，superpowers 以「禁令式门禁」为主，可以按团队文化二选一或混装。 ## 八、分维度排行榜（本期五项） - **设计质量**：systematic-debugging > verification-before-completion > receiving-code-review > hexagonal-architecture > codehealth-mcp - **上手难度（越低越好）**：verification-before-completion ≈ systematic-debugging > receiving-code-review > hexagonal-architecture > codehealth-mcp（后两者一个要架构知识、一个要外部服务） - **立竿见影程度**：verification-before-completion > codehealth-mcp > systematic-debugging > receiving-code-review > hexagonal-architecture（验证门禁当次会话就生效，架构知识要长期复利） - **可移植性**：三者 superpowers Skill 均为纯 Markdown，随 skills.sh CLI 可装入 Cursor/Codex/Copilot/Windsurf/Gemini/Cline 等 20 个 agent；codehealth-mcp 最弱（绑 MCP） - **值得抄去写自己 Skill 的程度**：systematic-debugging（模式密度最高）> verification-before-completion > receiving-code-review ## 九、适配与不适配 **适合**：让 agent 自主跑长任务（自主时间越长，约束型 Skill 的复利越大）；多 agent 流水线（子 agent 汇报不可信，需要 VCS diff 门禁）；接手历史包袱重、改一处崩三处的代码库（3 次失败升级规则是为你准备的）。 **不适合**：纯探索性原型（铁律会拖慢 scratch 速度，此时该卸载或换 `prototype` 类流程）；没有测试基建的仓库（verification 门禁会退化为形式主义）；以及要意识到一个meta风险——禁令写得越狠，模型在灰色地带的规避行为越隐蔽，装了刹车不等于可以不看 diff。 ## 参考来源 1. [Skills Leaderboard — skills.sh](https://skills.sh) — 全量安装榜数据（find-skills 3.0M、grill-me 911.2K、tdd 722.0K 等）及 20 个支持 agent 列表，2026-08-29 抓取 2. [obra/superpowers — GitHub](https://github.com/obra/superpowers) — 框架仓库元数据：描述、创建时间 2025-10-09、最近推送 2026-08-13、MIT、14 个 Skill 目录 3. [systematic-debugging SKILL.md（原文）](https://raw.githubusercontent.com/obra/superpowers/main/skills/systematic-debugging/SKILL.md) — 第三节逐段拆解的全文依据 4. [verification-before-completion SKILL.md（原文）](https://raw.githubusercontent.com/obra/superpowers/main/skills/verification-before-completion/SKILL.md) — Gate Function、Claim/Requires 表出处 5. [receiving-code-review SKILL.md（原文）](https://raw.githubusercontent.com/obra/superpowers/main/skills/receiving-code-review/SKILL.md) — 禁令清单与 YAGNI 检查处 6. [SkillsMP — Agent Skills Library](https://skillsmp.com/skills) — 全站 2,495,308 条 Skill、219,300 创作者、Debugging 296,370 条等类目统计；brainstorming 入选 Popular picks 7. [SkillsMP 搜索 "refactoring"](https://skillsmp.com/search?q=refactoring) — hexagonal-architecture、codehealth-mcp、tdd-workflow、prompt-optimizer 的收录描述与更新时间 > [!tip] 51学通信知识星球 > **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 > **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 > **当前规模**：5200 篇主题 / 990 个回答，198 元/年。 > **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 > **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。