大多数 CLAUDE.md 指导是针对单独开发者一次处理一个项目而编写的。代理机构的工作不同：你有一个客户项目组合，每个项目都有自己的规范，同一个工程师可能在一周内接触其中六个。对单独开发者有效的 CLAUDE.md 策略在代理机构规模下失效。这是我们在 Seahawk Media 经过 18 个月的迭代、跨 200+ 个活跃客户代码库后采用的工作方法。
关键要点：在代理机构规模下，CLAUDE.md 需要三层结构——机构范围内的标准、客户覆盖项，以及按具体项目的备注——这样一个工程师可以在六个仓库之间切换，获得适当的上下文。CLAUDE.md at agency scale needs three layers, agency-wide standards, client overrides, and per-engagement notes, so one engineer can move across six repos with the right context.
如果你正在运营一个每天使用 Claude Code 的代理机构，并且发现工程师在不同项目中获得差异巨大的输出，这篇文章就是结构性的解决方案。
为什么单独开发者的 CLAUDE.md 建议在代理机构规模下失效
标准的 CLAUDE.md 建议是：一次性编写，针对你的项目优化，保持在 500 行以下。当你只有一个项目时这样有效。当你有 50 个客户代码库时，会出现三个问题。同一个工程师记不住哪些规范适用于哪个客户。新工程师入职一个项目时会面对 50 个不同的 CLAUDE.md 文件。当工程师更新一个项目而忘记更新其他项目时，CLAUDE.md 内容会漂移。
在代理机构规模下解决这个问题需要分层方法：一个地方放代理机构范围的标准，另一个地方放客户特定的覆盖，第三个地方放每个项目的上下文。这些层堆叠而不是重复。
三层 CLAUDE.md 模型
第一层：机构范围的标准
一个单一的 CLAUDE.md 模板存在于我们机构的私有 GitHub 仓库中。它涵盖：我们发布的语言中的代码风格、我们禁止的模式、我们的测试规范、我们的安全标准、我们的英式拼写编辑规则、我们的部署默认值。这个文件大约 400 行，每年改动几次。
每个新客户项目都通过符号链接或复制这个文件来启动。机构范围文件的更改按季度审查周期被拉入项目。工程师可以依赖这些规范在他们打开的任何项目中完全相同。
第二层：客户特定的 CLAUDE.md
每个客户仓库都有自己的 CLAUDE.md，它导入机构范围的文件并添加客户具体信息：他们的技术栈、他们的托管、他们的插件、他们的团队规范、他们的编辑风格、他们禁止的插件。这个文件通常 100 到 200 行，当客户参与形式发生变化时更改。
我们在顶部使用一个简单的包含指令："## Agency standards" 并链接到机构范围的文件，然后是 "## Client-specific" 和覆盖项。Claude 读取两者，因为它们都在项目树中。
第三层：按参与项目的注释
特定的时间限制的上下文：当前冲刺目标、积极的发现结果、最近的决策日志、未解决的问题列表。存在于 CLAUDE_NOTES.md 或类似的文件中，在参与期间每周更新，在参与结束时存档。
这是大多数机构在 CLAUDE.md 卫生方面失败的地方。前两层保持整洁；第三层漂移并变得陈旧。我们通过周五下午的审查周期来解决这个问题：每个工程师审查他们活跃的 CLAUDE_NOTES.md 并更新或归档它。
复合的禁止模式列表
我们整个代理机构 CLAUDE.md 中单一的最高杠杆要素是禁止模式列表。二十条条目，按季度刷新。来自当前列表的示例：
永远不要在我们交付的任何语言中使用 eval()。
永远不要在 WordPress 中使用 query_posts()（改用 WP_Query）。WordPress (use WP_Query instead).
永远不要在 TypeScript 中使用 any，除非带有明确的"// suppressed: <reason>"注释。
永远不要在任何上下文中使用 document.write()。
永远不要将密钥提交到 git，无论哪个分支。
永远不要在任何客户端副本中使用 em-dashes（运营标准用于 AI 检测规避）。
永远不要禁用 Supabase 表上的 RLS 来修复错误。Supabase tables to fix a bug.
永远不要直接推送到 main（始终使用 PR）。
永远不要在可以编辑现有文件时创建新文件。
这个列表会不断增长，因为每次工程师违反其中一条规则，我们就会添加这条规则。Claude 在每个会话中都会读取禁用模式列表，并拒绝生成违反这些规则的代码。我们曾经发布到测试环境的那类错误已经消失了。
CLAUDE.md 中应该排除什么
我们在代理机构 CLAUDE.md 文件中明确不放置的五件事：
项目状态更新。它们会过时；应该放在 Linear 或 Notion 中。
冗长的架构论证。应该放在设计文档中；CLAUDE.md 应该引用它们，而不是重复它们。
客户端密钥、凭证或任何敏感信息。即使是私有的 CLAUDE.md 文件也太容易泄露了。
个别工程师的个人偏好。标准必须是整个代理机构范围内的；工程师特定的偏好应该放在他们自己的 .claude/settings.json 中。
营销文案或销售语言。CLAUDE.md 是工程背景；它读起来应该像是一名资深工程师为其他工程师写的。
CLAUDE.md 如何改变招聘等式
一位能够在整个客户组合中快速上手、无需在每次访问时重新学习项目的资深工程师，其价值远高于做不到这一点的工程师。三层 CLAUDE.md 系统正是让这成为可能的原因。新工程师的入职时间从大约 2 周的项目特定学习曲线降至 3 天，因为约定被编成代码而非口头传承。
同一位工程师，输出更多，入职成本更低，上下文切换开销更少。一旦我们建立了这个系统，招聘流程就不再倾向于初级工程师，而是更多资深工程师，因为初级工程师不再需要吸收那些曾经是唯一约定传递方式的项目特定背景。
总结
机构规模的 CLAUDE.md 是一个分层系统：机构范围的标准作为基础，客户特定的覆盖作为中间层，每个项目的笔记作为顶层。禁止模式列表是杠杆效应最高的部分。通过周五审查的节奏避免每个项目层内容过时。
实施三层模型，你的工程师就会停止在整个客户组合中输出不一致的内容。跳过这一步，你就是在为 AI 助手付费，而这些助手会根据工程师碰巧打开的上一个项目而产生不同的工作质量。
常见问题
什么是 CLAUDE.md 文件？
CLAUDE.md 是一个项目文件，它告诉 Claude Code 你的标准、技术栈和编码约定，这样它的输出就能符合你的代码库。在代理机构规模下，每个项目一个平面文件是不够的，这就是为什么这里跨多个客户仓库使用三层模型。
你如何在多个客户项目中扩展 CLAUDE.md？
使用三层模型：适用于所有地方的机构范围内的标准、按账户的客户特定覆盖项，以及针对给定项目的按具体项目备注。同一个工程师可以在一周内在六个客户仓库之间切换，在每个仓库中都有适当的上下文，无需重新编写。
什么不应该放在 CLAUDE.md 中？
密钥、任何不断变化的东西，以及稀释重要规则的干扰信息。保持它仅限于持久的标准和约定。充斥的 CLAUDE.md 会被忽视；精炼的、分层的、清楚说明禁止模式的 CLAUDE.md 才能真正改变输出。
CLAUDE.md 是否改变你的招聘方式？
它降低了入职成本。当标准存在于分层的 CLAUDE.md 中时，新工程师通过工具继承机构的约定，而不是需要几个月的隐性知识。它使招聘转向判断力，远离记忆公司风格。