6 CLAUDE.md Patterns That Keep Shared Context From Breaking When PR Volume

Key Takeaways

• Use the two-layer CLAUDE.md split, hooks, and CI review action to prevent agent drift.
• The repo-root file wins over personal preferences, and enforcement matters more than prose.

The Problem: More PRs, Less Review Capacity

Anthropic reported that code output per engineer grew 200% in the last year, but before Code Review shipped, only 16% of PRs got substantive review comments. That gap is the real story. When you turn on Claude Code and lower the "should I open a PR?" bar, PR volume jumps—but review capacity doesn't. Six weeks later, the trunk gets weird.

Your team's shared codebase mental model and tacit conventions fracture when five different personal CLAUDE.md files all bid for the same surface. Each engineer's agent has different instincts: camelCase vs snake_case, integration-first vs unit-first tests. The reviewer—also using Claude Code—has yet another set. Multiply by five and the codebase's "voice" breaks.

The Fix: Treat CLAUDE.md as a Team Constitution

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 preference). Here are the six patterns that carried the weight.

Pattern 1: Two-Layer CLAUDE.md

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 session.
• ~/.claude/CLAUDE.md on each engineer's machine—personal preferences. Editor quirks, "explain longer, I'm new to Go." Not shared.

Claude Code reads both, but the repo one wins on conflict. Write at the top of the team file: "If this file and a personal CLAUDE.md disagree, this file wins. Personal preferences apply only where this file is silent."

Pattern 2: Per-Module Overrides

Not every convention is repo-global. Frontend and backend have different testing philosophies. Put packages/backend/CLAUDE.md with "unit tests with Vitest, mock DB with in-memory adapter" and packages/frontend/CLAUDE.md with "integration tests with Playwright, no mocks." The root carries only what's universal. Keep leaf files short—five to fifteen lines—and only the delta from the parent. Don't duplicate rules.

Pattern 3: Hook-Based Enforcement

CLAUDE.md prose is a soft constraint. Under time pressure, on the eighty-third turn, Claude will sometimes forget. Use hooks:

• PreToolUse on Bash—validate commands. Block rm -rf, git push --force to main, committing without tests.
• PostToolUse on Edit/Write—run linter and type checker. If they fail, feed errors back to Claude.

This is the difference between "ninety percent" and "one hundred percent" compliance. At team scale, the ten percent gap erodes trust.

Pattern 4: Explicit Review-Role Separation

Use two Claude Code sessions—one implements, one reviews. Give the reviewer session its own addendum:

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

Load with claude --append-system-prompt "$(cat ./.claude/CLAUDE-reviewer.md)". This makes the reviewer adversarial by default, not sycophantic. It produced the biggest lift in review quality.

Pattern 5: CI-Side Re-Application

Hooks fire locally. That's not enough when another engineer's Claude session opens a PR with a slightly older CLAUDE.md checkout. Run review server-side with the official 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'

This ensures every PR gets a fresh, consistent review from the current constitution.

Pattern 6: Constitution Drift Gate

Changes to the team CLAUDE.md itself need review. Treat it like code: PR-review any change, require a "why" in the description, and log the change in a changelog. This prevents silent drift that breaks agent behavior.

The One Pattern That Was Dead Weight

A single "global rules" file that tried to cover everything. It became bloated, contradicted itself, and agents ignored it. The layered approach replaced it.

What Changed for My Team

Six months in, PR volume tripled, but the trunk stayed clean. Hooks caught 100% of lint errors. Review comments were consistent and actionable. The key was treating CLAUDE.md as a living constitution, not a static prompt.

Source: dev.to