Gumroad 的 CLAUDE.md 实践面向 AI Agent 的仓库规范与技能体系【免费下载链接】gumroadSee what sticks项目地址: https://gitcode.com/GitHub_Trending/gumr/gumroadCLAUDE.md 是 Gumroad 仓库面向 AI 编码助手Claude Code的元指令文件它只解决两件事Agent Skills 的存放与维护约定以及代码注释的写作规范。本文以该文件为主体结合仓库中 6 个真实技能文件、.claude/settings.json权限配置与 CONTRIBUTING.md 的协作流程完整拆解这套AI 时代工程协作的落地方式读完后你可以直接复用到自己的仓库如何组织 Agent 技能目录、如何写出让同事包括 AI 同事真正想读的注释以及如何让规范在每次代码评审中被持续修正。CLAUDE.md 的定位一份极简的 AI 指令文件Gumroad 仓库根目录下的 CLAUDE.md 全文只有 18 行没有大段的架构介绍、没有命令清单、没有环境配置说明它刻意只保留两条硬约束Agent Skills 的组织约定技能本体存放在.agents/skills/name/SKILL.md.claude/skills/name是供 Claude Code 兼容使用的符号链接新增或更新技能时编辑.agents/skills并保持符号链接同步。代码注释规范为已经了解代码库的读者写注释只说出代码无法表达的那一件事然后停止。同时文件第一行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-confidenceAI 驱动的测试执行——由模型分析 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。注释不需要解释代码库的背景、不需要交代入门知识读者能自行点击进入命名常量、能看懂当前文件上下文。这个假设直接决定了注释的取舍标准。保留三样代码说不出的东西规范明确列出了值得保留的三类内容非显而易见的原因the non-obviouswhy某个设计决策背后的动机。例如一个看似多余的空检查为什么必须存在。顺序约束ordering constraints这段代码必须在另一段之后/之前执行的原因这类约束写在代码里会被执行顺序隐藏。会坑到下一个人的陷阱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 youre 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Gumroad 的 CLAUDE.md 实践：面向 AI Agent 的仓库规范与技能体系
Gumroad 的 CLAUDE.md 实践面向 AI Agent 的仓库规范与技能体系【免费下载链接】gumroadSee what sticks项目地址: https://gitcode.com/GitHub_Trending/gumr/gumroadCLAUDE.md 是 Gumroad 仓库面向 AI 编码助手Claude Code的元指令文件它只解决两件事Agent Skills 的存放与维护约定以及代码注释的写作规范。本文以该文件为主体结合仓库中 6 个真实技能文件、.claude/settings.json权限配置与 CONTRIBUTING.md 的协作流程完整拆解这套AI 时代工程协作的落地方式读完后你可以直接复用到自己的仓库如何组织 Agent 技能目录、如何写出让同事包括 AI 同事真正想读的注释以及如何让规范在每次代码评审中被持续修正。CLAUDE.md 的定位一份极简的 AI 指令文件Gumroad 仓库根目录下的 CLAUDE.md 全文只有 18 行没有大段的架构介绍、没有命令清单、没有环境配置说明它刻意只保留两条硬约束Agent Skills 的组织约定技能本体存放在.agents/skills/name/SKILL.md.claude/skills/name是供 Claude Code 兼容使用的符号链接新增或更新技能时编辑.agents/skills并保持符号链接同步。代码注释规范为已经了解代码库的读者写注释只说出代码无法表达的那一件事然后停止。同时文件第一行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-confidenceAI 驱动的测试执行——由模型分析 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。注释不需要解释代码库的背景、不需要交代入门知识读者能自行点击进入命名常量、能看懂当前文件上下文。这个假设直接决定了注释的取舍标准。保留三样代码说不出的东西规范明确列出了值得保留的三类内容非显而易见的原因the non-obviouswhy某个设计决策背后的动机。例如一个看似多余的空检查为什么必须存在。顺序约束ordering constraints这段代码必须在另一段之后/之前执行的原因这类约束写在代码里会被执行顺序隐藏。会坑到下一个人的陷阱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 youre 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
