企业官网建设流程全解析

Gumroad 的 CLAUDE.md 实践：面向 AI Agent 的仓库规范与技能体系

【免费下载链接】gumroadSee what sticks项目地址: https://gitcode.com/GitHub_Trending/gumr/gumroad

CLAUDE.md 是 Gumroad 仓库面向 AI 编码助手（Claude Code）的元指令文件，它只解决两件事：Agent Skills 的存放与维护约定，以及代码注释的写作规范。本文以该文件为主体，结合仓库中 6 个真实技能文件、.claude/settings.json权限配置与 CONTRIBUTING.md 的协作流程，完整拆解这套"AI 时代工程协作"的落地方式，读完后你可以直接复用到自己的仓库：如何组织 Agent 技能目录、如何写出让同事（包括 AI 同事）真正想读的注释，以及如何让规范在每次代码评审中被持续修正。

CLAUDE.md 的定位：一份"极简"的 AI 指令文件

Gumroad 仓库根目录下的 CLAUDE.md 全文只有 18 行，没有大段的架构介绍、没有命令清单、没有环境配置说明，它刻意只保留两条硬约束：

1. Agent Skills 的组织约定：技能本体存放在.agents/skills/<name>/SKILL.md，.claude/skills/<name>是供 Claude Code 兼容使用的符号链接，新增或更新技能时编辑.agents/skills并保持符号链接同步。
2. 代码注释规范：为已经了解代码库的读者写注释，只说出代码无法表达的那一件事，然后停止。

同时，文件第一行@CONTRIBUTING.md通过引用语法把完整的贡献流程文档引入上下文。值得注意的是，仓库中的 AGENTS.md 与 CLAUDE.md 内容完全一致——同一份规范以两份文件共存，分别服务于不同 Agent 工具链的自动发现机制，这是一种成本极低却非常实用的双轨做法。

从内容策略看，这份文件刻意把"规范"与"细节"分离：CLAUDE.md 只承载少量高杠杆的长期约定，而把 PR 结构、分支卫生、Sidekiq 队列优先级、迁移纪律等大量细节全部下沉到 CONTRIBUTING.md，避免指令文件自身变成一份没人读完的"巨型宪章"。

Agent Skills：.agents/skills与.claude/skills的双目录约定

目录结构与符号链接机制

仓库实际目录布局如下（通过ls -la验证）：

.agents/skills/ ├── commit/SKILL.md ├── create-issue/SKILL.md ├── email-blast/SKILL.md ├── gumroad-prod-console/SKILL.md │ ├── scripts/prod_runner_loop.rb │ ├── scripts/prod_query.sh │ ├── scripts/setup.sh │ └── references/common-queries.md ├── review-pr/SKILL.md │ └── references/review-guidance.md └── test-confidence/SKILL.md .claude/skills/ ├── commit -> ../../.agents/skills/commit ├── create-issue -> ../../.agents/skills/create-issue ├── email-blast -> ../../.agents/skills/email-blast ├── gumroad-prod-console -> ../../.agents/skills/gumroad-prod-console ├── review-pr -> ../../.agents/skills/review-pr └── test-confidence -> ../../.agents/skills/test-confidence

这份结构印证了 CLAUDE.md 的核心约定：.agents/skills是唯一的事实来源（source of truth），.claude/skills只是符号链接。这样做的收益是双重的——一方面与工具链无关的技能目录可以服务于任何 Agent（未来接入其他工具只需再建一层链接）；另一方面单一事实来源保证了同一技能只有一个可编辑副本，不会出现两份漂移。

SKILL.md 的元数据协议

从 .agents/skills/test-confidence/SKILL.md 和 .agents/skills/commit/SKILL.md 可以看到一致的 frontmatter 结构：

--- name: test-confidence description: AI-driven test execution. Opus decides what to run and how confident to be, based on your diff. argument-hint: "--full to run to 100% | --strict to halt on pre-existing failures" allowed-tools: Bash(git *), Bash(bundle exec rspec *), Bash(cat *), Bash(find *), Bash(wc *), Bash(head *), Bash(tail *), Bash(grep *), Bash(bin/test-confidence *) ---

四个字段各司其职：name是技能标识；description决定 Agent 在什么场景下自动选择该技能；argument-hint描述可传入的 CLI 参数；allowed-tools以白名单形式限定该技能能调用的 shell 命令——这是把"最小权限"原则落到 Agent 技能层面的具体实践。正文末尾统一以$ARGUMENTS占位，运行时由调用方注入实际参数，实现同一份技能文档在不同调用场景下的复用。

仓库中的 6 个实际技能

从仓库结构看，当前共维护 6 个技能，覆盖了日常开发的完整闭环：

• test-confidence：AI 驱动的测试执行——由模型分析 diff 判定风险等级、挑选测试并设定置信度里程碑，跑到 99%（绿色进度条）即可安全提交，--full可继续跑到 100%；脚本内部还实现了"预存失败检测"（路径启发式 + merge-base 复跑验证）来区分真实回归与历史失败。
• commit：规范化的提交流程——先看 status/diff/最近提交风格，跑 test-confidence 与 lint（含npx tsc --noEmit类型检查），按文件名精确暂存，最后按祈使语气写提交信息（明确禁止feat:这类 conventional commit 前缀和Co-Authored-Bytrailer）。
• create-issue：按 CONTRIBUTING.md 中"What / Why"结构创建 issue。
• review-pr：带着 references/review-guidance.md 评审指引做 PR 审查。
• email-blast：面向站内邮件群发场景的技能。
• gumroad-prod-console：生产环境查询技能，附带了scripts/setup.sh、scripts/prod_query.sh、scripts/prod_runner_loop.rb三个可执行脚本和 references/common-queries.md 常用查询参考——这说明一个技能并不局限于单个 Markdown 文件，而是可以携带脚本与参考资料成为一个完整的能力单元。

新增/更新技能的约定

CLAUDE.md 明确给出操作规则：当需要新增或更新项目技能时，编辑.agents/skills下的对应目录，并同步维护.claude/skills中的符号链接。这份约定的现实意义在于：技能文件会随业务演进（比如新增一个支付对账技能），如果只有一处存放，忘记同步链接就会导致某一类 Agent 发现不了新技能。此外 CONTRIBUTING.md 还有一个对应的"元规范"：凡是只修改文档或 Agent 技能文件的 PR，可以豁免"必须附演示视频"的 #1 规则——因为 diff 本身就是可评审的产物。

代码注释规范：写给知道代码库的同事

CLAUDE.md 的第二部分是一段完整的注释哲学，可以拆解为四个可执行准则。

读者假设：同事，不是学生

第一句话就划定了注释的目标读者——"a colleague, not a student"。注释不需要解释代码库的背景、不需要交代入门知识，读者能自行点击进入命名常量、能看懂当前文件上下文。这个假设直接决定了注释的取舍标准。

保留：三样"代码说不出"的东西

规范明确列出了值得保留的三类内容：

1. 非显而易见的原因（the non-obviouswhy）：某个设计决策背后的动机。例如一个看似多余的空检查为什么必须存在。
2. 顺序约束（ordering constraints）：这段代码必须在另一段之后/之前执行的原因，这类约束写在代码里会被执行顺序隐藏。
3. 会坑到下一个人的陷阱（traps that will bite the next person）：前人踩过的坑，不写下来下一个人会原样再踩一次。

这条准则与 CONTRIBUTING.md 中的"Comments are welcome when they earn their place. Keep them concise and focused on the why"完全呼应，属于同一套价值体系在不同文档中的两处表述。

删除：四类噪音

对应的删除清单同样明确：

• 厂商或公司历史（vendor or company history）——对当前代码理解无帮助的背景叙事；
• 重复代码本身已表达的内容（anything restating the line below it）——"递增计数器"这类注释；
• bug 被发现的经过叙述（narration of how the bug was found）——读者需要的是修复后的正确约束，不是调查过程；
• 对可点击查看的命名常量的重新解释（re-explanations of a named constant）——读者可以跳转查看定义，注释不需要转述。

两个可操作的检验标准

规范给出了两条"放之四海而皆准"的自检方法：

• 三行测试：如果一条注释超过三行，就问自己"我会删掉哪部分"——超过三行的注释几乎总是混入了可以删除的内容。
• 噪音测试：一位熟悉该文件的维护者会觉得这一行值得读吗？如果答案是"不会"，它就是噪音——而噪音正是教会人们跳过真正重要注释的元凶。

这套标准强调注释的质量守恒：注释总量越多，单位注释的注意力份额就越低；只有持续删除低信息密度注释，才能保住关键注释被读到的概率。这也解释了为什么 CLAUDE.md 如此精简——它本身就在示范自己倡导的写作原则。

规范如何与 CONTRIBUTING.md 形成闭环

CLAUDE.md 通过@CONTRIBUTING.md引用把两层规范衔接起来：注释怎么写由 CLAUDE.md 负责，改动怎么提交、PR 怎么评审由 CONTRIBUTING.md 负责。CONTRIBUTING.md 中与 AI 协作直接相关的机制包括：

• test-confidence 门槛：每次 commit 前运行bin/test-confidence跑到 99% 绿条才允许提交，AI 按 diff 临时决定测试数量（注释改动可能只需 2 个测试，支付模型重构可能要 100 个）；
• AI 披露义务：每个 PR 必须在---分隔符之后披露所用的具体模型与提示词；
• PR 结构模板：What / Why / Before-After / Test Results 四段式；
• 自愈机制："When you're corrected, fix the docs"——当评审中纠正了某个未被文档化的约定或坑点时，必须在同一 PR（或紧随其后）中修订这份贡献指南，让规范"每次有人被纠正就变得更聪明一点"。

这一条与 CLAUDE.md 的 Agent Skills 约定共同构成了文档的持续演进通道：新坑点写进 CONTRIBUTING.md，新技能写进.agents/skills，规范因此不是静态文本而是随评审迭代的活系统。

落地证据：权限配置与技能协作链

仓库中的 .claude/settings.json 为整套体系提供了运行时的权限底座——它以permissions.allow白名单形式放行git *、bundle *、rails *、rake *、rspec *、rubocop *、bin/*等命令，并显式授予Read/Write/Edit。这份配置与各 SKILL.md 内的allowed-tools白名单形成两级权限控制：外层限定 Agent 总体可用的工具集，内层再按技能收窄。从源码结构看，test-confidence脚本会依赖ANTHROPIC_API_KEY（未导出时自动从.env读取）、在tmp/test-confidence/缓存 diff 哈希对应的测试计划、并借用 git worktree 在 merge-base 上复跑失败用例——这些都对应着 CONTRIBUTING.md 中"AI 决定风险曲线形状"的描述，属于仓库内可验证的实现事实。

小结：这套规范对现代仓库的三点启发

回顾 Gumroad 的这份 CLAUDE.md，其可迁移价值集中在三点：第一，面向 Agent 的指令文件应当极简，把高频硬约束与低频细节分层存放，避免指令文件自身变成噪音；第二，技能采用"单一事实来源 + 工具链符号链接"的组织方式，配合 frontmatter 元数据协议与allowed-tools白名单，让技能既可发现又可约束；第三，注释规范的本质是注意力管理——明确"给谁写、写什么、删什么"，并用三行测试与噪音测试两个可操作指标守住注释的信息密度。对于正在为自己的仓库设计 AI 协作规范的团队，这份 18 行的文件加上 6 个实际技能目录，就是一套可以直接对照落地的参考范本。

【免费下载链接】gumroadSee what sticks项目地址: https://gitcode.com/GitHub_Trending/gumr/gumroad