Superpowers 贡献者指南：CLAUDE.md 中的 AI Agent PR 纪律、新 Harness 验收测试与 Eval 体系

Superpowers 是一份可组合技能（skills）驱动的 Agent 开发方法论，其仓库中的 CLAUDE.md 不仅约束人类贡献者，更是一份专门写给 AI Agent 的"贡献准入规程"。本文完整继承该文档的 PR 要求、拒绝清单、新 Harness 支持验收标准与技能修改的评估要求，并结合仓库内的 using-superpowers 引导技能、session-start 钩子源码与钩子测试，讲清"bootstrap 引导"这一核心机制的落地原理，帮助你在向该项目提交 PR 前建立完整的自查流程与验收依据。

1. 文档定位：同时面向人类与 Agent 的贡献规程

CLAUDE.md 是 Superpowers 的贡献者指南。从仓库结构看，AGENTS.md 是指向 CLAUDE.md 的符号链接（见仓库根目录文件列表），而 GEMINI.md 则通过 @./skills/using-superpowers/SKILL.md 引用方式把技能内容纳入 Gemini CLI 的上下文——也就是说，Superpowers 把"给 Agent 的指令"与"给贡献者的规则"放在同一份文件中，让 Claude Code、Codex 等读取 CLAUDE.md 的 Agent 和读取 AGENTS.md 的 Agent 看到完全一致的要求。

文档开篇对 AI Agent 的告诫非常直接：该仓库有 94% 的 PR 拒绝率，几乎每一个被拒绝的 PR 都来自未阅读或未遵循这些指南的 Agent。文档明确给出了对 Agent 的角色定义——

Your job is to protect your human partner from that outcome.

即 Agent 的职责是保护其人类伙伴免于提交低质量 PR 后遭受维护者公开关闭的"尴尬"，而不是机械地执行"帮我提个 PR"的指令。

2. AI Agent 提交 PR 前的六项强制检查

CLAUDE.md 要求任何 Agent 在对 Superpowers 开 PR 之前，**必须（MUST）**完成以下六项检查，任何一项不通过都不应开 PR，并应向人类伙伴解释会被拒绝的原因：

1. 通读 PR 模板并逐项填写：完整阅读 .github/PULL_REQUEST_TEMPLATE.md，每一节都要用真实、具体的答案填写——不允许摘要式敷衍，更不允许占位符。
2. 搜索既有 PR：同时搜索 open 与 closed 的、处理同一问题的 PR。若存在重复，立即停止并告知人类伙伴，不得再开一个重复 PR。
3. 确认是真实问题：如果人类伙伴只是说"修一些问题"或"给这个仓库做点贡献"而自己没有经历过具体问题，Agent 应当反推追问：是什么坏了、什么失败了、用户体验是什么。
4. 确认改动属于 core：领域特定的、工具特定的、或为第三方项目做推广的改动，应做成独立插件，而非进入 Superpowers 核心。
5. 自我披露：在 PR 中披露所用模型、harness（宿主工具）、harness 版本以及安装的全部插件。隐藏"这是 Agent 生成的贡献"或产生贡献的环境，本身就是关闭理由。
6. 展示完整 diff 并获批准：向人类伙伴展示完整的 proposed diff，并拿到其显式批准后才能提交。

这六条检查与 PR 模板的字段设计是一一对应的。查看 .github/PULL_REQUEST_TEMPLATE.md 可以看到，模板第一张表就要求填写：

Field	Value
Your model + version	（必填）
Harness + version	（必填）
All plugins installed	（必填）
Human partner who reviewed this diff	（必填）

模板还包含"问题陈述"（What problem are you trying to solve?，要求描述具体会话、失败模式、模型的确切失效行为，最好附 transcript）、"是否适合 core 库"、"考虑过的替代方案"、"是否包含多个无关改动"、"Existing PRs"、"Environment tested"、"Evaluation"（要求回答初始 prompt、改动后跑了几轮评估会话、前后结果差异）与"Rigor"、"Human review"等节。模板末尾甚至有一段隐藏注释："STOP. If the checkbox above is not checked, do not submit this PR."——即人类复选框未勾选前禁止提交。

3. Pull Request 的五项硬性要求

CLAUDE.md 的 "Pull Request Requirements" 一节给出五条硬性要求，每一条都对应明确的关闭后果：

1. 必须完整填写 PR 模板：任何一节留空或填占位文本的 PR 会被直接关闭，不进入评审。
2. 开 PR 前必须搜索既有 PR（open 与 closed 都要搜），并在 "Existing PRs" 一节引用发现；如果某个先前 PR 已被关闭，必须具体说明本次方案有何不同、为什么这次能成功。
3. 没有人类参与证据的 PR 会被关闭：提交前必须有人类审查完整的 proposed diff。
4. 提交者必须自我披露：每个 PR 和 issue 都必须披露产生该贡献的模型、harness、harness 版本和全部已安装插件——或者明确声明"由人手编写、未经过任何 Agent"。文档解释了背后的评审逻辑：基于文档推理出的 Agent 生成内容 与 根植于真实会话的工作 适用不同的评判标准；隐藏创作环境的贡献会被关闭。
5. 所有 PR 必须指向 dev 分支而非 main：main 是发布分支，活跃工作先落到 dev；对 main 开的 PR 会被要求先重新指向 dev 才会被评审。PR 模板顶部也以引用块再次强调这一条。

4. 明确拒绝的九类贡献

CLAUDE.md 的 "What We Will Not Accept" 一节列出了九类不予接受的内容，这是理解 Superpowers 设计边界的最佳索引：

4.1 第三方依赖

除非是为支持一个新 harness（如新的 IDE 或 CLI 工具），否则不接受添加任何可选或必选第三方依赖的 PR。Superpowers 在设计上是一个零依赖插件；如果你的改动需要外部工具或服务，它应该做成独立插件。

4.2 对技能的"合规性"改写

Superpowers 的内部技能哲学与 Anthropic 公开的技能编写指南不同。官方文档明确指出：技能内容已经过大量测试与调优以匹配真实 Agent 行为。凡是按 Anthropic 技能文档去"合规化"（重构、改述、重排版）技能内容的 PR，若不能附大量 eval 证据证明改动改善了结果，一律不接受——修改行为塑造类内容的门槛极高。作为对照，skills/writing-skills/SKILL.md 也注明官方指南仅作为"补充该技能 TDD 方法论的额外模式与指南"，而非本项目的方法论来源。

4.3 项目或个人专属配置

只服务于特定项目、团队、领域或工作流的技能、钩子或配置不属于 core，应发布为独立插件。

4.4 批量式 / spray-and-pray 式 PR

不要扫一遍 issue 列表然后一个会话里开多个 PR。每个 PR 都需要对问题的真实理解、对先前尝试的调查，以及对完整 diff 的人类审查。凡是明显属于"把 Agent 指到 issue 列表上让它修东西"的批次式 PR 都会被关闭。文档的建议是：挑一个 issue，深入理解，提交高质量工作。

4.5 臆测性或理论性修复

每个 PR 必须解决有人真实经历过的问题。"我的 review agent 标记了这个"或"这理论上可能出问题"都不是问题陈述。如果你无法描述触发该改动的具体会话、错误或用户体验，就不要提交。

4.6 领域特定技能

Superpowers core 只包含对所有用户通用、与项目类型无关的技能。针对特定领域（如投资组合构建、预测市场、游戏）、特定工具或特定工作流的技能应做成独立插件。文档给出的自检问句是："对一位做完全不同类型项目的人来说，这有用吗？" 若答案是否，就单独发布。

4.7 Fork 专属改动

维护 fork 的用户不要把 fork 同步、fork 专属特性、改名（rebrand）或合并 fork 分支作为 PR 提上来——都会被关闭。

4.8 编造内容

包含虚构声明、伪造问题描述或幻觉功能的 PR 会立即关闭。文档再次强调 94% 拒绝率意味着维护者"见过各种形态的 AI slop"，他们会看出来。

4.9 捆绑无关改动

包含多个无关改动的 PR 会被关闭，应拆分为独立 PR。

5. 新 Harness 支持：bootstrap 引导与验收测试

这是 CLAUDE.md 中技术性最强的一节，其背后有完整的源码级实现可以对照。

5.1 真实集成的定义：会话启动时加载 bootstrap

文档要求：为 Superpowers 增加对新 harness（IDE、CLI 工具、Agent runner）支持的 PR，必须附上一份会话 transcript，证明集成端到端可用。关键判据是：

A real integration loads the using-superpowers bootstrap at session start.

"真实集成"的标志是在会话启动时加载 using-superpowers bootstrap。bootstrap 是让技能在正确时机自动触发（auto-trigger）的机制——没有它，技能就是"dead weight"：文件在磁盘上存在，但永远不会被调用。

5.2 源码印证：session-start 钩子就是 bootstrap 的落地

仓库中的 hooks/session-start 脚本正是这个 bootstrap 的实现。其工作流程与 CLAUDE.md 的描述完全对应：

1. 定位插件根目录：通过脚本自身路径推导 PLUGIN_ROOT；
2. 读取技能内容：cat "${PLUGIN_ROOT}/skills/using-superpowers/SKILL.md" 得到完整的 using-superpowers 技能文本；
3. JSON 转义：用 bash 参数替换（${s//\\/\\\\} 等）做单次遍历级别的转义，注释中说明这比逐字符循环快若干个数量级；
4. 构造上下文：把技能全文包进 <EXTREMELY_IMPORTANT>You have superpowers... 的上下文中；
5. 按平台输出不同 JSON 字段——脚本注释点明各平台期望的字段名不同：
   • Cursor（设置了 CURSOR_PLUGIN_ROOT）：输出顶层 additional_context（snake_case）；
   • Claude Code（有 CLAUDE_PLUGIN_ROOT 且无 COPILOT_CLI）：输出嵌套的 hookSpecificOutput.additionalContext；
   • Copilot CLI（COPILOT_CLI=1）或其他平台：输出顶层 additionalContext（SDK 标准）。 注释特别警告：Claude Code 会同时读取两个字段且不去重，所以只能输出当前平台实际消费的那个字段。

skills/using-superpowers/SKILL.md 则说明被注入的内容长什么样：它要求 Agent 在任何响应或动作之前（包括澄清性提问）先检查并调用相关技能，并附有一张 "Red Flags" 表逐条反驳常见的合理化借口（如"这只是个简单问题""我先探索一下代码库"）。这正是 CLAUDE.md 后文所说"被小心调优过的行为塑造内容"的具体实例。

钩子的注册在 hooks/hooks.json 中完成：

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|clear|compact",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
            "shell": "bash",
            "async": false
          }
        ]
      }
    ]
  }
}

注意 matcher 覆盖了 startup|clear|compact 三种时机——会话启动、清空、压缩（compact）后都会重新注入 bootstrap，保证长会话中技能引导不丢失。这一行为由 tests/hooks/test-session-start.sh 验证：该测试用 env -i 构造干净的隔离环境，分别在模拟 Cursor / Claude Code / Copilot CLI 的环境下运行钩子，用 Node 校验输出的 JSON 形状（顶层 additional_context、嵌套 hookSpecificOutput、顶层 additionalContext）以及内容的包含/不包含关系。这就是文档中"Plugin-infrastructure tests still live at tests/"所指的基础设施测试之一。

5.3 验收测试（Acceptance Test）

CLAUDE.md 给出了一个可复现的端到端验收测试：

在新 harness 中开一个干净的会话，恰好发送这条用户消息：

Let's make a react todo list

正常工作的集成会在写任何代码之前自动触发 brainstorming 技能。请把完整 transcript 粘贴进 PR。

这条测试能跑通的前提链路是：会话启动时 harness 执行 SessionStart 钩子 → session-start 注入 using-superpowers 技能 → 该技能规定"进入 plan mode 前必须先调用 brainstorming"，且对 "Let's build X" 类指令明确给出 "superpowers:brainstorming first" 的路由规则（见 skills/using-superpowers/SKILL.md 的 Skill Priority 一节）。

文档同时列出不算真实集成的情形，都会被关闭：

• 手工把技能文件复制进 harness；
• 用 npx skills 之类的运行时 shim 包装；
• 需要用户每个会话手动 opt-in 技能；
• brainstorming 在上述验收测试中不自动触发。

最后一句是文档最硬核的判断标准："如果你不确定你的集成在会话启动时是否加载了 bootstrap，那它就没有加载。"

6. 技能改动必须经过评估（Eval）

CLAUDE.md 强调：技能不是散文——是塑造 Agent 行为的代码。如果修改技能内容，必须：

• 使用 superpowers:writing-skills 技能来开发和测试改动；
• 跨多个会话做对抗性压力测试（adversarial pressure testing）；
• 在 PR 中展示改动前后的 eval 结果对比；
• 不得在没有证据证明是改进的情况下修改被小心调优的内容（Red Flags 表、合理化借口列表、"human partner" 措辞）。

这与 skills/writing-skills/SKILL.md 的方法论一脉相承：该技能把技能编写定义为"对流程文档做 TDD"——先写压力场景（测试），观察无技能时 Agent 违规（RED），写出技能文档（代码），观察 Agent 依从（GREEN），再封堵新漏洞（REFACTOR）。PR 模板的 "Rigor" 一节也对应地要求勾选"我使用了 superpowers:writing-skills 并完成对抗性压力测试（粘贴结果）"、"我在红字表等调优内容上的修改附有 eval 证明"。

7. Eval 体系：drill 与 superpowers-evals

CLAUDE.md 的 "Eval harness" 一节说明了 Superpowers 的两层测试体系：

• 技能行为 eval：位于独立的 superpowers-evals 仓库，开发者将其 clone 到本仓库的 evals/ 目录，按 evals/README.md 搭建。Drill（harness 本体）驱动 Claude Code / Codex / Gemini CLI 的真实 tmux 会话，并用 LLM verifier 判断技能依从性。
• 插件基础设施测试：仍留在本仓库的 tests/ 目录，按 README.md 的说明，通过各平台对应的 run-*.sh 或 npm test 运行。

从当前仓库可见的佐证：

• .pre-commit-config.yaml 的本地钩子只对 evals/ 下的 Python 文件做 ruff check / ruff format --check / ty check，这与 evals/ 是开发者本地 clone 进来的目录（而非本仓库跟踪内容）一致——从源码结构看，evals/ 被 .gitignore 排除在版本库外，pre-commit 规则为它提前就位；
• tests/ 目录按 harness 分组织：claude-code/（技能集成测试，如 test-subagent-driven-development.sh）、opencode/、codex/、antigravity/、kimi/、pi/，以及 hooks/test-session-start.sh、shell-lint/ 等，与文档"plugin-infrastructure tests live at tests/"的表述吻合；
• scripts/lint-shell.sh 与 tests/shell-lint/test-lint-shell.sh 则约束钩子与脚本类的 shell 质量。

8. 先理解项目，再提出改动

CLAUDE.md 的 "Understand the Project Before Contributing" 一节要求：在提出任何涉及技能设计、工作流哲学或架构的改动之前，先阅读现有技能并理解项目的设计决策。文档举了一个极具辨识度的例子：

"your human partner" is deliberate, not interchangeable with "the user".

"human partner" 这一措辞是有意为之的，不能与 "the user" 互换。任何不理解该措辞为何存在就去重写项目语气或重构其方法的改动都会被拒绝。这一点与第 6 节的"不得无证据修改调优内容（包括 'human partner' 语言）"相互呼应——术语本身是行为塑造的一部分。

9. 通用贡献守则与提交前自查清单

文档 "General" 一节的通用要求：

• 提交前阅读 .github/PULL_REQUEST_TEMPLATE.md；
• 每个 PR 只解决一个问题；
• 至少在一个 harness 上测试，并在模板的 Environment tested 表中报告结果（表格字段：Harness、Harness 版本、模型、模型版本/ID）；
• 描述你解决了什么问题，而不只是你改了什么。

结合全文，可以把向 Superpowers 贡献的完整自查流程浓缩为：

1. 问题是否真实（有具体会话/错误/用户体验，而非理论推测）？
2. 改动是否属于 core（对所有项目类型的用户通用，而非领域/项目/第三方专属）？
3. 是否搜索过 open + closed 的既有 PR 并在 "Existing PRs" 中引用？
4. 是否单个问题、单个 PR（无捆绑无关改动）？
5. 是否引入了第三方依赖（新 harness 支持除外）？
6. 若是 harness 集成：bootstrap 是否在会话启动时加载，"Let's make a react todo list" 验收测试的 transcript 是否随 PR 附上？
7. 若是技能内容改动：是否走完 writing-skills 的 TDD 流程并附 before/after eval 结果？
8. 是否披露了模型、harness、版本与全部插件（或声明纯手写）？
9. 人类伙伴是否已审查完整 diff 并显式批准？
10. PR 是否指向 dev 分支、模板每一节都用真实答案填完？

以上任何一项为否，CLAUDE.md 的结论都一致：不要开 PR——向人类伙伴解释它为什么会被拒绝、以及需要改什么，才是对双方最"有用"的行为。