六个 CLAUDE.md 模式防止团队代码风格漂移

dev.to · AI#Claude Code#团队协作#工程管理

Editor brief · 编辑速览

通过双层 CLAUDE.md 分层、Git hooks 和 CI 自动化审查，防止多人使用 AI 编程工具时代码规范不一致的问题。

文章思维导图

Knowledge map

拖拽缩放

Full translation

完整中文译文

问题：PR 增多，审核能力不足

Anthropic 报告称过去一年每位工程师的代码产出增长了 200%，但在 Code Review 功能上线前，只有 16% 的 PR 获得了实质性的审核评论。这个差距才是真正的问题所在。当你开启 Claude Code 并降低「是否应该开一个 PR？」的门槛时，PR 数量会激增——但审核能力不会。六周后，主干代码就开始变得奇怪了。

当五份不同的个人 CLAUDE.md 文件同时争夺同一个代码表面时，你团队共享的代码库心智模型和隐性约定就会崩塌。每位工程师的 agent 都有不同的本能：camelCase 对比 snake_case，先集成后单元 vs 先单元后集成测试。审核者——同样使用 Claude Code——又有另一套规则。乘以五，代码库的「声音」就破碎了。

修复方案：把 CLAUDE.md 当作团队宪法

约定文件必须在仓库中（这样每个 Claude 实例都能读取它）、被强制执行（这样 drift 会被机械地捕获），并且是分层的（这样团队约定优于个人偏好）。以下是承载这些重量的六种模式。

模式 1：双层 CLAUDE.md

将 CLAUDE.md 拆分为两个文件，并明确优先级：

./CLAUDE.md 在仓库根目录——团队宪法，提交并经过 PR 审核。编码约定、PR 规则、审核清单、「永远不要做 X」。这约束每个会话。

~/.claude/CLAUDE.md 在每位工程师的机器上——个人偏好。编辑器怪癖、「解释得更详细一些，我是 Go 新手」。不共享。

Claude Code 会读取两者，但仓库的文件在冲突时获胜。在团队文件顶部写上：「如果此文件与个人 CLAUDE.md 存在分歧，此文件获胜。个人偏好仅在此文件沉默处适用。」

模式 2：按模块覆盖

并非每个约定都是仓库全局的。前端和后端有不同的测试理念。在 packages/backend/CLAUDE.md 放置「使用 Vitest 进行单元测试，用内存适配器 mock DB」，在 packages/frontend/CLAUDE.md 放置「使用 Playwright 进行集成测试，不使用 mock」。根目录只保留通用内容。保持叶子文件简短——五到十五行——并且只是与父文件的差异。不要复制规则。

模式 3：基于 Hook 的强制执行

CLAUDE.md 的文本是软约束。在时间压力下，在第 83 轮时，Claude 有时会忘记。使用 hooks：

PreToolUse on Bash——验证命令。阻止 rm -rf、git push --force to main、不运行测试就提交。

PostToolUse on Edit/Write——运行 linter 和类型检查器。如果它们失败，将错误反馈给 Claude。

这就是「百分之九十」和「百分之百」合规之间的区别。在团队规模上，百分之十的差距会侵蚀信任。

模式 4：明确的审核角色分离

使用两个 Claude Code 会话——一个实现，一个审核。给审核者会话配备自己的附录：

# ./.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 tests don't cover, API surface changes, 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：CI 端重新应用

Hooks 在本地触发。当另一位工程师的 Claude 会话用稍微旧一点的 CLAUDE.md checkout 打开一个 PR 时，这还不够。使用官方 action 在服务端运行审核：

# .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
      - uses: anthropics/claude-code-action@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          claude-code-command: 'review'

这确保每个 PR 都从当前宪法中获得新鲜的、一致的审核。

模式 6：宪法漂移门控

对团队 CLAUDE.md 本身的更改需要审核。像代码一样对待它：对任何更改进行 PR 审核，在描述中要求「为什么」，并在变更日志中记录。这防止了会破坏 agent 行为的静默漂移。

一个曾是累赘的模式

一个试图覆盖一切单一的「全局规则」文件。它变得臃肿、自相矛盾，agent 们忽略了它。分层方法取代了它。

我的团队发生了什么变化

六个月后，PR 数量增加了两倍，但主干代码保持干净。Hooks 捕获了 100% 的 lint 错误。审核评论一致且可操作。关键是像对待活的宪法一样对待 CLAUDE.md，而不是静态的 prompt。

Originally published on gentic.news