团队规模化使用Claude Code的6个CLAUDE.md实战模式

Anthropic 发布了一个让我开始关注的数据：过去一年，每位 Anthropic 工程师的代码产出增长了 200%，而在他们上线 Code Review 之前，只有 16% 的 PR 获得了实质性的评审意见。产出在涨，评审能力却没有跟上。

这个差距是发布帖子里没人会写的部分。只要打开 Claude Code 并降低"我应该开 PR 吗？"的门槛，就能轻松拉高 PR 数量。真正困难的是不崩溃的评审流程、共享代码库的心智模型，以及团队花了多年建立起来的隐性约定。大多数报告 PR 数量大幅增长的团队，六周后也会悄悄报告他们的主干出现了问题。

我们没有崩溃，原因是 CLAUDE.md——被当作团队的契约而不是 AI 提示词。半年后，我能说出六个扛住了压力的模式，还有一个听起来对但实际上没用的模式。

关于个人 CLAUDE.md 模式的内容在其他地方已经有详细讨论。本文专门讨论的是：当三个、五个、十个工程师都把 Claude Code 指向同一个仓库时会发生什么——以及他们的 agent 开始产生分歧时怎么办。

为什么个人 CLAUDE.md 模式在团队规模下会失效

我在每个团队看到的失败模式都是一样的。每个工程师都在 ~/.claude/CLAUDE.md 保留一份个人 CLAUDE.md，经过精心打磨以适应个人偏好——变量如何命名、什么算"过度工程化"、什么时候想先写测试。当他们是唯一提交代码的人时，效果很好。

然后第二个工程师开始使用 Claude Code。他的 agent 有不同的直觉。他的 PR 在第一个工程师用 snake_case 的地方用了 camelCase。他的测试是集成优先的，而第一个工程师的是单元优先的。评审者——也在使用 Claude Code——又有另一套直觉，所以评审意见与两份 PR 都不一致。

乘以五个工程师，代码库的"声音"就分裂了。不是因为 Claude Code 不好——而是因为五个不同的个人上下文都在争夺同一个共享表面。

每个人第一个想到的解决方案是"我们把约定写下来吧"。这是正确的，但还不够。约定文件必须在仓库里（这样每个 Claude 实例都能读到）、必须被执行（这样漂移会被机制性地捕获）、必须是分层的（这样团队约定在冲突时优先于个人约定）。下面六个模式加起来就是这三个属性的体现。

扛住压力的六个模式

模式 1 — 双层 CLAUDE.md：团队契约，个人偏好

最核心的改变。将 CLAUDE.md 拆分为两个文件，并明确优先级：

./CLAUDE.md 在仓库根目录——团队契约，提交后经过 PR 评审。编码约定、PR 规则、评审清单、"永远不要做 X"。这约束了每个人针对该仓库运行的每个 Claude Code 会话。

~/.claude/CLAUDE.md 在每个工程师的机器上——个人偏好。编辑器怪癖、"因为我是 Go 新手所以解释得更详细"、"使用我的终端别名"。不共享。

Claude Code 会读取这两个文件，当有冲突时，仓库里的那个优先级更高。我在每个团队 CLAUDE.md 顶部写的规则是："如果本文件与个人 CLAUDE.md 存在分歧，以本文件为准。个人偏好只在本文件沉默的地方才适用。"

在这个模式之前，每个合并的 PR 都是五种不同个人风格之间的微小协商。之后：个人偏好继续适用于每个工程师的工作方式，但停止渗透到交付的内容中。

模式 2 — 通过嵌套 CLAUDE.md 实现 per-module 覆盖

并非所有约定都是仓库全局的。大多数团队的 frontend 和 backend 实际上有不同的测试哲学，强制单一全局规则会导致"后端规则强加给前端文件"或"完全没有规则"。

Claude Code 会读取它正在工作的目录树中任何级别的 CLAUDE.md。在 packages/backend/CLAUDE.md 中指定"使用 Vitest 进行单元测试，用内存适配器模拟 DB"，在 packages/frontend/CLAUDE.md 中指定"使用 Playwright 进行集成测试，不使用 mocks"。根 CLAUDE.md 只携带真正通用的约定。

陷阱：不要在嵌套文件中重复规则。叶子文件应该保持简短——每个 5-15 行——只携带与父文件的差异。如果你发现自己开始重复父文件的规则，你就在 undoing 这个模式。

模式 3 — 基于 Hook 的执行，而不仅仅是散文

CLAUDE.md 散文是软约束。Claude Code 通常会遵循它。但在时间压力下、在长对话的第 83 轮、在接近 token 限制的编辑附近，它有时会忘记。一旦 PR 数量超过评审能力，"通常可以"就远远不够了。

修复方案是 hooks。Anthropic 的 hooks 功能允许你注册在 agent 生命周期固定点触发的脚本。承载最重量的两个是：

PreToolUse on Bash——在命令运行前验证。阻止 rm -rf、阻止 git push --force 到 main、阻止在没有测试通过的情况下提交。

PostToolUse on Edit / Write——自动运行 linter 和类型检查器。如果它们失败，将错误反馈给 Claude，这样它就能修复它们，而无需人工介入。

"请在 CLAUDE.md 中运行测试"和 PostToolUse hook 实际运行测试之间的区别，就是"90% 的时间"和"100% 的时间"之间的区别。在团队规模下，这 10% 的差距正是侵蚀评审过程信任的原因。

模式 4 — 显式评审角色分离

Boris Cherny 模式——两个 Claude Code 会话，一个实现，一个评审——各自独立已经很有名了。在团队规模下需要一个小结构补充：评审会话获得自己的 CLAUDE.md 附录，告诉它如何做评审，而不仅仅是"你是 Claude，正在评审这个 PR"。

# ./.claude/CLAUDE-reviewer.md
You are reviewing a PR opened by another Claude session.
- Assume the implementer already believed their code was correct.
- Look for: hidden coupling, edge cases the tests do not cover,
  API surface changes the implementer did not flag, security implications.
- Do not restate the diff. Only comment on issues.
- Classify every comment: Must / Should / Nit.
- Terminate review with a one-sentence verdict.

使用 claude --append-system-prompt "$(cat ./.claude/CLAUDE-reviewer.md)" 加载这个文件。现在评审会话有了与实现会话真正不同的处置方式——默认是对抗性的，而不是谄媚性的。这是我团队中产生最大评审质量提升的单一改变。

模式 5 — 通过 anthropics/claude-code-action@v1 在 CI 端重新应用

Hooks 在本地触发。这还不够，因为开 PR 的"团队成员"是另一个工程师的 Claude 会话，可能 checkout 了略旧版本的 CLAUDE.md。你需要评审在服务器端运行，从全新的 checkout 开始，在每个 PR 上运行。

官方 action 在 2025 年 8 月发布了 GA，是承载这个模式的工具：

# ./.github/workflows/claude-review.yml
name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: read
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            REPO: ${{ github.repository }}
            PR NUMBER: ${{ github.event.pull_request.number }}
            Review this PR against the reviewer constitution.
          claude_args: |
            --system-prompt-file ./.claude/CLAUDE-reviewer.md
          track_progress: true

注意这里的 input 名称。v1 版本的 action 移除了 mode、system_prompt_file 和 post_inline_comments；一切都折叠到 prompt 和 claude_args 中。大量博客文章仍然显示 v0.x 形状，它在 action 的 input 验证时失败而不是运行时，所以看起来像权限问题时实际上不是。

两个属性很重要。首先，reviewer system prompt 将 Claude 置于与模式 4 在本地配置的相同处置方式——对抗性的，而不是有用的。其次，track_progress: true 将发现的问题放在特定的 diff 行上，而不是作为一个冗长的总结。人类评审者然后可以 Accept / Dismiss 各个评论，这是 Claude 无法通过写散文来伪造的 UX。

2026 年 AI 工程报告——来自大约 22,000 名开发者的遥测数据——发现整个行业 PR 评审的中位时间增加了 441%，31% 更多的 PR 现在在零人工评审的情况下合并，不是通过策略，而是因为评审者无法跟上数量。CI 端的 Claude 评审不是人类的替代品——它是防止人类成为产生那"31% 更多"的瓶颈的方式。

模式 6 — 漂移检测：CLAUDE.md 变更需要 PR 评审

最后一个模式是最无聊的。没有人想在博客文章中写它，因为它听起来显而易见。这是大多数团队跳过的、后来后悔的模式。

CLAUDE.md 是团队契约。对契约的修订应该经过评审。在 CLAUDE.md 上添加 CODEOWNERS 条目，要求两个 approvers，并添加一条 lint 规则，对同时更改源文件的 CLAUDE.md 编辑让 CI 失败（它们应该是单独的 PR）。

没有这个，工程师们会在周五下午 4 点"快速添加一行"CLAUDE.md 来解除 PR 阻塞，到了周一团队就有了 12 条没有人同意的冲突规则。有了这个，更改是审慎的，团队保持对齐在契约实际说的内容上。

我移除的一个模式

完全公开：我尝试了第七个模式 six 周。Agent Teams——Claude 生成通过共享任务列表相互通信的并行子 agent——感觉应该在团队规模下工作。两个工程师，四个 Claude 会话，由一个 lead agent 协调。理论上这处理并行模块、跨层重构和长期调试。

在实践中，在我们工作负载上，它燃烧了等效单个会话 3-4 倍的 token 成本，而质量提升我无法衡量。它明显胜出的场景——真正的跨层重构，DB、API 和 UI 需要同步变更——大约每三周出现一次。不够频繁，不足以证明持续成本是合理的。

我仍然在那些特定的几周打开它。我停止将它保持在默认团队手册中。六个模式，不是七个。

如果你还没感受到痛

如果你的团队有 1-5 个工程师使用 Claude Code，而且你还没有感受到痛，你可能在六周内就会感受到。有两件事值得在那之前做：

把你最好的 CLAUDE.md 移入仓库。无论哪个工程师有最精炼的个人 CLAUDE.md，将其复制到 ./CLAUDE.md，删除其中的个人偏好规则，提交 PR。现在团队有了一个起点契约。

在评审模式下打开 anthropics/claude-code-action@v1。上面的 YAML 块开箱即用。它会在第一天内开始在 PR 中标记真正的问题。有些会是错误的——没关系，人类会 dismiss 它们。重要的是评审队列不再成为瓶颈。

每当团队问为什么我们在这个文件上投入这么多精力时，我不断回头想的那句话是：CLAUDE.md 不是 AI 的指令。它是团队对我们已经争论过的事情的记忆，写下来这样我们就不必在每个 PR 中都重新争论。

完整的团队规模 playbook——四阶段推广（个人 → 标准化 → CI 集成 → 并行开发）、用于隔离并行 Claude 会话的特定 Git worktree 模式、用于决定 Agent Teams 是否值得的 token 成本模型，以及关于整个 Claude Code 工作流程的 24 章经验总结——都在《Claude Code Mastery: Context Engineering that Changes How You Ship》中。第七章深入讨论团队 CLAUDE.md；第十一章涵盖多工具协调；第十七章涵盖在共享仓库中放开 Claude 的策略/风险方面。

如果模式 5 中的 CI 端执行是你想开始的地方，Harness Engineering Guide 涵盖了"如何在构建时强制执行 AI agent 边界"这一更广泛的外形——CLAUDE.md 是这种模式的一个实例，hooks 是另一种，CI 端评审是第三种。