6 CLAUDE.md Patterns That Kept Shared Context From Breaking When PR Volume Outran Review

Anthropic published the number that made me pay attention: code output per Anthropic engineer has grown 200% in the last year, and before they shipped Code Review, only 16% of their PRs got substantive review comments. Output went up. Review capacity did not follow it.

That gap is the part nobody puts in the launch post. A big jump in PR count is trivial to produce if you turn on Claude Code and lower the "should I open a PR?" bar. The hard part is not collapsing the review process, the shared codebase mental model, or the tacit conventions the team spent years building. Most teams that report a big jump in PR volume also, quietly, report six weeks later that their trunk got weird.

Ours did not get weird, and the reason was CLAUDE.md -- treated as a team constitution instead of an AI prompt. Six months in, I can name the six patterns that carried the weight. Also one pattern that sounded right and turned out to be dead weight.

Individual CLAUDE.md patterns are well-covered elsewhere. This piece is specifically about what changes when three, five, ten engineers are all pointing Claude Code at the same repo -- and their agents start disagreeing.

Why individual CLAUDE.md patterns fail at team scale

The failure mode I see in every team is the same. Each engineer keeps a personal CLAUDE.md in ~/.claude/CLAUDE.md that is honed to their taste -- how they name variables, what they consider "over-engineered," when they want tests written first. It works great when they are the only one committing.

Then a second engineer adopts Claude Code. Their agent has different instincts. Their PRs use camelCase where the first engineer's used snake_case. Their tests are integration-first, the first engineer's were unit-first. The reviewer -- also using Claude Code -- has yet another set of instincts, so the review comments are inconsistent with both PRs.

Multiply by five engineers and the codebase's "voice" fractures. Not because Claude Code is bad -- because five different personal contexts are all bidding for the same shared surface.

The fix everyone reaches for first is "let's write down our conventions." That is correct but insufficient. The convention file has to be in the repo (so every Claude instance reads it), enforced (so drift is caught mechanically), and layered (so team convention beats personal convention when they conflict). Those three properties are what the six patterns below add up to.

The 6 patterns that carried the weight

Pattern 1 -- Two-layer CLAUDE.md: team constitution, personal preferences

The single most load-bearing change. Split CLAUDE.md into two files with clear precedence:

• ./CLAUDE.md in the repo root -- the team constitution, committed and PR-reviewed. Coding conventions, PR rules, review checklists, "never do X." This binds every Claude Code session anyone runs against the repo.
• ~/.claude/CLAUDE.md on each engineer's machine -- personal preferences. Editor quirks, "explain longer to me because I am new to Go," "use my terminal aliases." Not shared.

Claude Code reads both, and the repo one takes precedence for anything that conflicts. The rule I write at the top of every team CLAUDE.md is: "If this file and a personal CLAUDE.md disagree, this file wins. Personal preferences apply only where this file is silent."

Before this pattern, every merged PR was a small negotiation between five different personal styles. After: personal preferences continued to apply to how each engineer worked, but stopped leaking into what got shipped.

Pattern 2 -- Per-module overrides via nested CLAUDE.md

Not every convention is repo-global. The frontend and backend of most teams have honestly different testing philosophies, and forcing a single global rule turns into either "backend rules on frontend files" or "no rules at all."

Claude Code will read a CLAUDE.md at any level of the directory tree it is working in. Put a packages/backend/CLAUDE.md that specifies "unit tests with Vitest, mock the DB with an in-memory adapter" and a packages/frontend/CLAUDE.md that says "integration tests with Playwright, no mocks." The root CLAUDE.md carries only what is truly universal.

The trap: do not duplicate rules across nested files. Leaf files should be short -- five to fifteen lines each -- and only carry the delta from the parent. If you find yourself repeating the parent's rules, you are undoing the pattern.

Pattern 3 -- Hook-based enforcement, not just prose

CLAUDE.md prose is a soft constraint. Claude Code will usually follow it. Under time pressure, on the eighty-third turn of a long session, on an edit near the token limit, it will sometimes forget. "Usually" is not good enough once PR volume outruns review capacity.

The fix is hooks. Anthropic's hooks feature lets you register scripts that fire at fixed points in the agent lifecycle. The two that carry the most weight are:

• PreToolUse on Bash -- validate the command before it runs. Block rm -rf, block git push --force to main, block committing without tests passing.
• PostToolUse on Edit / Write -- run the linter and type checker automatically. If they fail, feed the errors back to Claude so it fixes them without a human turn.

The difference between "please run the tests" in CLAUDE.md and a PostToolUse hook that actually runs them is the difference between "ninety percent of the time" and "one hundred percent of the time." At team scale, the ten percent gap is exactly what erodes trust in the review process.

Pattern 4 -- Explicit review-role separation

The Boris Cherny pattern -- two Claude Code sessions, one implements, one reviews -- is well known individually. At team scale it needs a small structural addition: the reviewer session gets its own CLAUDE.md addendum that tells it how to be a reviewer, not just "you are Claude reviewing this 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.

Load this file with claude --append-system-prompt "$(cat ./.claude/CLAUDE-reviewer.md)". Now the reviewer session has a genuinely different disposition from the implementer session -- adversarial by default, not sycophantic. This is the single change that produced the biggest lift in real review quality on my team.

Pattern 5 -- CI-side re-application via anthropics/claude-code-action@v1

Hooks fire locally. That is not enough when the "team member" opening the PR is another engineer's Claude session with a slightly older CLAUDE.md checkout. You need the review to run server-side, from a fresh checkout, on every PR.

The official action shipped GA in August 2025 and is what carries this pattern:

# .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

Watch the input names here. v1 of the action removed mode, system_prompt_file and post_inline_comments; everything folded into prompt and claude_args. Plenty of blog posts still show the v0.x shape, and it fails at the action's input validation rather than at runtime, so it looks like a permissions problem when it isn't.

Two properties matter. First, the reviewer system prompt puts Claude in the same disposition Pattern 4 configures locally -- adversarial, not helpful. Second, track_progress: true puts the findings on specific diff lines, not as one long summary. Human reviewers can then Accept / Dismiss individual comments, which is a UX Claude cannot fake by writing prose.

The 2026 AI Engineering Report -- telemetry from roughly 22,000 developers -- found that median time in PR review is up 441% across the industry, and 31% more PRs are now merging with zero human review, not by policy but because reviewers cannot keep pace with the volume. CI-side Claude review is not a substitute for humans -- it is the way you keep humans from being the bottleneck that produces that "31% more."

Pattern 6 -- Drift detection: CLAUDE.md changes are PR-reviewed

The final pattern is the boring one. Nobody wants to write it in a blog post because it sounds obvious. It is the pattern most teams skip and later regret.

CLAUDE.md is a team constitution. Amendments to a constitution should go through review. Add a CODEOWNERS entry on CLAUDE.md requiring two approvers, and add a lint rule that fails CI on CLAUDE.md edits that also change source files (they should be separate PRs).

Without this, engineers "just add a quick line" to CLAUDE.md to unblock a PR at 4pm on a Friday, and by Monday the team has 12 conflicting rules that nobody agreed to. With it, changes are deliberate and the team stays aligned on what the constitution actually says.

The one pattern I ripped out

Full disclosure: I tried a seventh pattern for six weeks. Agent Teams -- Claude spawning parallel sub-agents that message each other via a shared task list -- felt like it should work at team scale. Two engineers, four Claude sessions, coordinated by a lead agent. In theory this handles parallel modules, cross-layer refactors, and long-horizon debugging.

In practice, on our workload, it burned 3-4x the token cost of the equivalent single sessions for a marginal quality lift I could not measure. The scenarios where it did clearly win -- true cross-layer refactors where the DB, API, and UI needed to change in lockstep -- came up maybe once every three weeks. Not often enough to justify the standing cost.

I still turn it on for those specific weeks. I stopped keeping it in the default team playbook. Six patterns, not seven.

What to do Monday

If your team is one to five engineers on Claude Code and you have not felt the pain yet, you probably will inside six weeks. Two things worth doing before that:

1. Move your best CLAUDE.md into the repo. Whichever engineer has the sharpest personal CLAUDE.md, copy it to ./CLAUDE.md, delete the rules that are personal preference, PR it. Now the team has a starting constitution.
2. Turn on anthropics/claude-code-action@v1 in review mode. The YAML block above works out of the box. It will start flagging real issues in PRs within the first day. Some of them will be wrong -- that is fine, humans dismiss them. What matters is the review queue stops being the bottleneck.

The single sentence I keep coming back to when the team asks why we spend so much energy on this file: CLAUDE.md is not the AI's instructions. It is the team's memory of what we already argued about, written down so we do not have to argue about it again every PR.

Book CTA

The full team-scale playbook -- the four-phase rollout (individual → standardization → CI integration → parallel dev), the specific Git worktree pattern for isolating parallel Claude sessions, the token-cost model for deciding when Agent Teams is worth it, and 24 chapters of hard-won context on the whole Claude Code workflow -- is written up in Claude Code Mastery: Context Engineering that Changes How You Ship. Chapter 7 goes deep on team CLAUDE.md; chapter 11 covers multi-tool coordination; chapter 17 covers the policy/risk side of turning Claude loose in a shared repo.

If the CI-side enforcement in Pattern 5 is where you want to start, Harness Engineering Guide covers the broader shape of "how do you keep AI agents inside guardrails you can enforce at build time" -- CLAUDE.md is one instance of that pattern, hooks are another, CI-side review is a third.