古法编程

提交 SuperPowers 的 PR，你和你的 AI 编码代理必须接受一个现实：该项目有高达 94% 的 PR 拒绝率。几乎所有被拒 PR 都源于未阅读或遵守其严格贡献指南。核心答案是：提交前必须完成五项强制检查（读模板、搜重复、验真实、判归属、人审 diff），并逐字填写 PR 模板的每个字段，否则将直接关闭。本文基于仓库的 CLAUDE.md、PULL_REQUEST_TEMPLATE.md 等源文件，拆解这套严苛规则、模板细节以及必须避开的反模式。

如何给 SuperPowers 提交高质量 PR：贡献规则、模板与反模式

为 SuperPowers 项目贡献代码或技能，是一个要求极度严谨的过程。项目的维护者在 CLAUDE.md 开头就用醒目的红字警告所有 AI 代理：“这个仓库的 PR 拒绝率是 94%。几乎每一个被拒绝的 PR 都是由一个没有阅读或没有遵守这些指南的代理提交的。” 提交一个低质量的 PR 不仅会被迅速关闭，还可能损害你（人类合作伙伴）的声誉。因此，你的首要任务是遵循既定规则，保护你和你的团队。

第一步：提交前必须完成的五项检查

在向此仓库发起 PR 之前，你（或你的 AI 代理）必须完成以下五步。任何一步失败都应停止提交，并向你的人类合作伙伴解释原因。

  1. 完整阅读并填写 PR 模板：仓库的 .github/PULL_REQUEST_TEMPLATE.md 文件明确指出：“在提交前：逐字阅读此模板的每个字。留空部分、包含多个不相关更改或没有人类参与证据的 PR 将不予审查。” 你不能留空任何部分，也不能用占位符文本填写。
  2. 彻底搜索重复 PR：必须搜索已开启和已关闭的 PR，看是否有人处理过相同的问题。CLAUDE.md 指出：“如果存在重复，请停止并告知你的人类合作伙伴。不要开启另一个重复的 PR。” 如果找到已关闭的相关 PR，你需要在模板的“现有 PR”部分解释你的方法有何不同以及为什么这次能成功。
  3. 验证问题的真实性：你不能为了贡献而贡献。CLAUDE.md 要求：“验证这是一个真实的问题。如果你的合作伙伴让你‘修复一些问题’或‘为此仓库贡献’而没有经历具体的问题，请拒绝。询问他们是什么坏了、什么失败了、用户体验是什么。” 提交“投机性或理论性修复”是明确禁止的。
  4. 确认变更属于核心库：SuperPowers 核心库只包含对所有用户都有益的通用技能和基础设施。如果你的变更针对特定领域、工具或工作流，它应作为独立的插件发布。你需要在 PR 模板的“此变更是否适用于核心库？”部分自问：“这会对一个与你项目完全不同的人有用吗？”
  5. 人类审查完整差异：在提交前，必须向你的人类合作伙伴展示完整的差异（diff）并获得他们的明确批准。CLAUDE.md 强调：“没有人类参与的 PR 将被关闭。” PR 模板底部的“人类审查”部分有一个必须勾选的复选框。

第二步：详解 PR 模板的每个字段

PR 模板是你的 PR 能否进入审查流程的“准考证”。以下是核心部分及其填写要求：

  • 你试图解决什么问题？ 这是最重要的部分。你需要描述具体的、你自己遇到的问题。CLAUDE.md 给出了反面例子：“‘改进’某物不是一个问题陈述。什么坏了？什么失败了？是什么样的用户体验促使了此变更？” 如果这是会话问题，应包含你在做什么、出了什么错、模型的确切失败模式，并最好附上转录或会话日志。

  • 此 PR 变更了什么？ 用 1-3 句话说明“是什么”，而不是“为什么”（“为什么”属于上面的部分）。

  • 此变更是否适用于核心库？ 引导你思考此变更的普适性。如果它集成了第三方服务、只对特定项目或团队有益，那么它不属于核心。

  • 你考虑过哪些替代方案？ 你尝试或评估过哪些其他方法？为什么它们更差？如果你没有考虑过替代方案，这是一个危险信号。

  • 此 PR 是否包含多个不相关的变更？ 如果回答“是”，必须停止。将其拆分为单独的 PR。捆绑的 PR 将被关闭。

  • 现有 PR 勾选“我已查看所有开启和关闭的 PR 以查找重复或先前工作”，并列出相关 PR 编号或注明“未找到”。

  • 环境测试 提供一个表格，说明你在哪个编程代理（如 Claude Code、Cursor）、什么版本、什么模型、什么模型版本/ID 下进行了测试。

  • 评估 描述启动导致此变更的会话时使用的初始提示。在变更后运行了多少次评估会话？结果与变更前相比有何变化？CLAUDE.md 指出：“‘它能工作’不是评估。描述你跨多次会话观察到的前/后差异。”

  • 严谨性 如果这是技能变更，你必须勾选“我使用了 superpowers:writing-skills 并完成了对抗性压力测试（在下方粘贴结果）”。同时，你必须勾选“此变更已进行对抗性测试，而不仅仅是快乐路径测试”以及“我没有修改精心调整的内容（如红旗表、合理化列表、‘人类合作伙伴’语言），除非有大量评估证明此变更是一种改进”。记住，技能不是散文，而是塑造代理行为的代码。

  • 人类审查 最后的关卡，必须勾选。

第三步：规避常见的反模式

基于 CLAUDE.md 的“我们不接受什么”部分，以下行为会直接导致你的 PR 被关闭：

  1. 添加第三方依赖：除非是添加对新代理（如一个新 IDE 或 CLI 工具）的支持，否则不接受。SuperPowers 是一个设计上零依赖的插件。如果你的变更需要外部工具或服务，它应属于自己的插件。
  2. “合规性”技能修改：维护者有自己的技能编写哲学，且内容经过大量测试和调整。仅为“符合”其他文档而重构、重写或重排格式技能的 PR，除非有广泛的评估证据表明变更能改善结果，否则不会被接受。
  3. 项目特定或个人配置：仅对特定项目、团队、领域或工作流有益的技能、钩子或配置，不属于核心。请作为单独插件发布。
  4. 批量或“扫射式” PR：不要浏览问题跟踪器并在一个会话中为多个问题开启 PR。每个 PR 都需要对问题有真正的理解、对先前尝试的调查以及人类对完整差异的审查。
  5. 推测性或理论性修复：如前所述，必须解决真实问题。
  6. 领域特定技能：SuperPowers 核心包含通用技能。针对特定领域（如构建投资组合、预测市场、游戏）、特定工具或特定工作流的技能，属于它们自己的独立插件。
  7. 包含捏造内容的 PR：包含虚构声明、捏造问题描述或幻觉功能的 PR 将立即关闭。
  8. 捆绑不相关变更：必须拆分。

此外，在提交 Issue 前，也应先搜索现有 Issue。例如，.github/ISSUE_TEMPLATE/bug_report.md 就警告道：“在归档前：搜索开启和关闭的 issue。仅 Windows 的 SessionStart 钩子问题就被报告了 29 次。如果你的问题已存在，请改为在现有问题上添加评论或反应。”

第四步：遵循社区行为规范

所有贡献者都必须遵守项目的 CODE_OF_CONDUCT.md。该规范旨在营造一个无骚扰、开放、欢迎和包容的环境。它定义了正面行为标准（如展现同理心和善意、尊重不同意见）和不可接受的行为（如使用性化语言、侮辱性评论、骚扰）。维护者有权对不合规的评论、提交、代码编辑和 Issue 进行删除、编辑或拒绝。

FAQ

Q: 94% 的 PR 拒绝率是真的吗？我该如何看待这个数字？ A: 是的，这个数字直接来自项目维护指南 CLAUDE.md。它反映了项目对质量的极致追求和对 AI 生成“低质量 PR”泛滥的严峻现实。你应将其视为一个强烈的警示，要求你的每一份贡献都必须深思熟虑、证据充分且由人类严格把关。

Q: 如果我只是想为 SuperPowers 添加一个适合我自己项目的特定工作流技能，应该怎么做？ A: 根据规则，这类技能不属于核心库。你应该遵循插件开发文档，将其创建为一个独立的插件并单独发布。这样既能满足你的需求，又不会违反项目的核心贡献原则。

Q: 我在使用 writing-skills 进行对抗性压力测试时，具体要测试什么？ A: 你需要验证你的技能修改在多种会话场景下，尤其是非“快乐路径”或故意刁难、模糊不清的提示下，都能按预期引导或约束 AI 代理的行为。这通常包括测试代理是否会“合理化”绕过技能中的规则，并需要提供评估证据。