企业官网建设流程全解析

Superpowers 贡献指南深度解读：AGENTS.md 中的 Agent 门禁、新 Harness 验收测试与 Skill 修改评估体系

【免费下载链接】superpowersAn agentic skills framework & software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers

Superpowers 仓库根目录的 AGENTS.md 是一份专门写给 AI Agent（以及人类贡献者）的贡献者指南，它用近乎“防御性编程”的姿态定义了本仓库 94% PR 拒绝率背后的完整规则体系：Agent 提交 PR 前的六项强制检查、PR 模板的必填约束、九类明确拒收的 PR、新增 Harness 支持的“验收测试”，以及修改 Skill 内容必须附带评估证据的硬性要求。读完本文，你将理解这份指南中每条规则对应的仓库证据（PR 模板、SessionStart 钩子、输出形状测试、版本清单文件），并掌握在 Superpowers 生态中合规贡献、移植新 Harness、修改 Skill 行为的完整方法论。

AGENTS.md 的定位：一份“为 Agent 而写”的门禁文档

仓库文件系统中可以看到，AGENTS.md 是指向 CLAUDE.md 的符号链接——同一份内容通过不同文件名被 Claude Code（读 CLAUDE.md）和其他遵循 AGENTS.md 约定的 Agent（读 AGENTS.md）同时加载。这正是 Superpowers “平台中立”思路在自身仓库上的体现。

文档开宗明义设定了基调：

This repo has a 94% PR rejection rate. Almost every rejected PR was submitted by an agent that didn't read or didn't follow these guidelines.

随后给出了 Agent 的核心定位——你的工作是保护你的人类伙伴免受被拒 PR 的羞辱（“burns your human partner's reputation”）。这不是修辞，而是把“低质量 PR 会损害谁的利益”直接写进了规范。

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

文档 “If You Are an AI Agent” 一节列出了提交 PR 前必须完成的六项检查，任何一项失败都不应开 PR：

1. 通读 PR 模板并逐节填写真实、具体的答案（对应 .github/PULL_REQUEST_TEMPLATE.md）——不接受摘要，不接受占位符；
2. 检索已存在的 PR——包括 open 和 closed 两种状态——如果存在重复，停下来告知人类伙伴，不要再开一个重复 PR；
3. 验证这是真实问题。如果人类伙伴只是说“修一些问题”或“给这个仓库贡献点东西”，而没有经历过具体故障，Agent 应当反问：什么坏了？什么失败了？用户体验如何？
4. 确认改动属于 core。领域专属、工具专属、或为第三方项目打广告的改动，应作为独立插件发布；
5. 披露身份。PR 中必须声明所用模型、harness、harness 版本以及所有已安装插件。隐瞒贡献是 Agent 生成的——或是在什么环境中生成的——是关闭 PR 的理由；
6. 展示完整 diff 并获得人类伙伴的明确批准后才能提交。

这六条与 PR 模板形成了严格的对应关系。从模板源码可以看到，它用注释对每节都做了“审讯式”的追问，例如：

• Who is submitting this PR?一节要求填写一个四列表格：模型及版本、harness 及版本、全部已安装插件、审阅此 diff 的人类伙伴。模板注释明确写道：“We assume an agent wrote this PR — tell us which one and where it ran.”（我们默认这个 PR 是 Agent 写的——告诉我们是哪个、在哪里跑的。）
• What problem are you trying to solve?一节的注释直接判定：“'Improving' something is not a problem statement.”（“改进某物”不构成问题陈述），要求给出具体会话、错误现象和失败模式。
• Does this PR contain multiple unrelated changes?一节的注释甚至直接说 “If yes: stop. Split it.”（如果是：停下，拆分。）
• 结尾的 “Human review” 复选框下写着 “STOP. If the checkbox above is not checked, do not submit this PR.”

模板还硬性规定了分支目标：PR 必须指向dev分支而非main。main是发布分支，活跃开发先落在dev上；对main开的 PR 会被要求改目标后再审。

九类明确拒收的 PR

文档 “What We Will Not Accept” 一节把拒收标准细化为九个子类，每一条都值得逐条理解：

这份清单与 PR 模板底部的关闭条件注释（no evidence of human involvement、multiple unrelated changes、promote third-party services、placeholder text、modifying behavior-shaping content without eval evidence）完全互锁——模板里留白或写占位符的 PR 会“closed without review”。

新 Harness 支持：验收测试与 bootstrap 机制

“New Harness Support” 一节是 AGENTS.md 中最具技术含量的部分。它的核心论断是：真正的集成必须在会话开始时加载using-superpowersbootstrap；bootstrap 是让 skill 在正确时机自动触发的机制，没有它，skill 就是“死重量”——文件在磁盘上，但永远不会被调用。

验收测试（acceptance test）极其具体：

在新 harness 中开一个干净会话，只发送这条用户消息：Let's make a react todo list合格的集成会在写任何代码之前自动触发brainstormingskill。把完整转录粘贴进 PR。

同时给出了四类“不算真正集成、会被关闭”的做法：

• 手动把 skill 文件复制进 harness；
• 用npx skills之类的运行时 shim 包裹；
• 任何需要用户每个会话手动启用 skill 的方案；
• 验收测试中brainstorming没有自动触发的方案。

最后有一句近乎格言的收尾：“If you are not sure whether your integration loads the bootstrap at session start, it does not.”（如果你不确定你的集成在会话开始时加载了 bootstrap，那就没有。）

仓库中的实现证据

这套验收标准不是空话，仓库中的钩子系统就是它的具体实现。hooks/hooks.json 注册了SessionStart事件（matcher 为startup|clear|compact），命令是：

"command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start"

run-hook.cmd 是一个 polyglot 包装器（同时是合法的 Windows batch 和 Unix shell 脚本），负责定位 bash 并分派具名脚本；真正干活的是 hooks/session-start。它的逻辑分三步：

1. 读取 bootstrap 内容（hooks/session-start#L10-L11）：cat出 skills/using-superpowers/SKILL.md 全文；
2. 包装并 JSON 转义（hooks/session-start#L26-L27）：把 SKILL.md 包进<EXTREMELY_IMPORTANT>标签，加上 “You have superpowers… For all other skills, use the 'Skill' tool” 的前言，然后用 bash 参数替换做单遍 JSON 转义；
3. 按 harness 输出对应 JSON 形状（hooks/session-start#L38-L47）——这是最容易踩坑的部分，三个分支互斥：

源码注释点明了这是一个陷阱：Claude Code 会同时读取additional_context和hookSpecificOutput两个字段且不去重，所以脚本必须只输出当前平台消费的那一个，否则要么不注入、要么双重注入（hooks/session-start#L29-L37）。

测试对每条形状做回归验证

tests/hooks/test-session-start.sh 对上面三种形状逐一做断言。它的assert_command_output辅助函数在干净环境中运行钩子，再用内嵌 node 脚本校验 JSON：例如 “nested” 形状要求存在hookSpecificOutput且hookEventName === "SessionStart"，同时断言顶层不得再出现additional_context/additionalContext（tests/hooks/test-session-start.sh#L77-L116）；“cursor” 形状要求只有顶层additional_context；“sdk” 形状要求只有顶层additionalContext。测试还验证了hooks.json必须声明"shell": "bash"——为了让 Claude Code 在 Windows 上经由 Git Bash 分派，而不是被 PowerShell/cmd.exe 的解析器破坏引号（tests/hooks/test-session-start.sh#L144-L165）。

对照 AGENTS.md 的要求，新 harness 贡献者的路径就很清晰了：为 harness 增加一个输出分支（或独立的session-start-<harness>脚本）、匹配该 harness 自己的事件 matcher 字符串，然后按tests/hooks/的风格补测试——这正是 PR 模板 “New harness support” 一节所要求粘贴的验收转录背后的工程闭环。

Skill 变更必须经过评估

“Skill Changes Require Evaluation” 一节的定义值得单独强调：Skill 不是散文，而是塑造 Agent 行为的代码。对 skills/ 内容的修改，AGENTS.md 要求：

• 使用superpowers:writing-skills（即 skills/writing-skills/SKILL.md）来开发和测试变更；
• 跨多个会话做对抗性压力测试；
• 在 PR 中展示 before/after 的 eval 结果；
• 没有证据不得修改精心调优的内容——Red Flags 表格、合理化（rationalization）列表、“human partner” 措辞。

这些“调优内容”可以在仓库中直接看到。skills/using-superpowers/SKILL.md 就有一张 12 行的 “Red Flags” 表格，把 “This is just a simple question”“Let me explore the codebase first” 等典型合理化念头逐条映射为反事实（“Questions are tasks. Check for skills.”）；using-superpowers的 frontmatter description 则直接要求 “skill invocation before ANY response including clarifying questions”——这就是验收测试中 “Let's make a react todo list” 能自动触发brainstorming的行为源头（brainstorming技能位于 skills/brainstorming/SKILL.md）。

两层测试体系：drill eval 与插件基础设施测试

AGENTS.md 的 “Eval harness” 一节说明了本仓库的两层测试分工：

• Skill 行为评估存放在独立的superpowers-evals仓库，克隆到evals/目录（该目录不入本仓库，需按evals/README.md另行克隆配置）。其中的Drill是一个驱动 harness：它拉起 Claude Code / Codex / Gemini CLI 的真实 tmux 会话，用一个LLM 验证器判定 skill 是否被正确遵循；
• 插件基础设施测试则留在本仓库的 tests/ 目录下，例如前文的tests/hooks/test-session-start.sh，以及按 harness 划分的tests/claude-code/、tests/codex/、tests/opencode/、tests/pi/、tests/kimi/、tests/antigravity/、tests/explicit-skill-requests/等目录，通过对应的run-*.sh或npm test运行。

这个分工恰好对应 PR 模板中的 “Evaluation” 与 “Rigor” 两节：前者要求回答 “改完后跑了多少 eval 会话、结果相比之前有何变化”（模板注释：“'It works' is not evaluation.”）；后者要求勾选 “若涉及 skill 改动：已使用superpowers:writing-skills并完成对抗性压力测试（粘贴结果）”“未在无充分 eval 的情况下修改 Red Flags 表格、合理化列表或 'human partner' 措辞”。

“理解项目再贡献”：连术语都是刻意的

文档倒数第二节 “Understand the Project Before Contributing” 提出了一条容易被忽视但极具项目特色的规则：在提议修改 skill 设计、工作流哲学或架构之前，先读现有 skill，理解项目的设计决策。它特别点出 Superpowers 有一套经过测试的自有哲学——skill 设计、Agent 行为塑造，以及术语（例如 “your human partner” 是刻意的措辞，不能随手替换成 “the user”）。任何不理解缘由就重写项目语气或重构其方法的改动都会被拒。

这与 “What We Will Not Accept” 中的 “Compliance changes” 一节互为表里：外部指南（包括 Anthropic 公开的 skill 写作文档）与本仓库实测调优的内部哲学冲突时，内部哲学优先，推翻它需要 eval 证据，而不是引用外部规范。

通用规则与贡献流程

AGENTS.md 最后 “General” 一节收敛为四条日常规则：

1. 提交前先读 .github/PULL_REQUEST_TEMPLATE.md；
2. 一个 PR 只解决一个问题；
3. 至少在一种 harness 上测试，并把结果填进模板的 “Environment tested” 表格（harness 名称 / harness 版本 / 模型 / 模型版本或 ID）；
4. 描述你解决了什么问题，而不只是你改了什么。

结合 README.md 的 Contributing 一节，完整流程是：Fork 仓库 → 切到dev分支 → 建工作分支 → 遵循writing-skillsskill 创建和测试新/改的 skill → 填好模板提交 PR。README 同时提醒：维护者通常不接受新 skill 的贡献，且任何 skill 更新必须在我们支持的所有 coding agent 上都能工作——这解释了为什么 AGENTS.md 对 “领域专属 skill” 和 “harness 兼容性” 如此苛刻。

规则与仓库证据的对照速查

写在最后

AGENTS.md 与其说是一份贡献规范，不如说是一套针对 LLM 行为的约束契约：它假定读者很可能是一个 Agent，并提前封堵了已知的所有失败模式——重复 PR、臆测性修复、隐藏生成环境、批量灌 PR、无 bootstrap 的假集成、无 eval 的行为改动。仓库中的 PR 模板、SessionStart 钩子及其输出形状测试、writing-skills 方法论与 drill eval 体系，则为每条规则提供了可执行、可验证的落点。对准备向该仓库提交贡献（尤其是新 harness 支持或 skill 修改）的 Agent 与人类伙伴而言，这份文档与上述证据文件构成了完整的合规路线图。

【免费下载链接】superpowersAn agentic skills framework & software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers