Claude Code for Engineering Teams: Building a Shared CLAUDE.md That Actually Stays Current

Running Claude Code solo is easy. You write a CLAUDE.md, you iterate on it, you know what’s in it because you wrote it. Running it across a 5-10 person team is a different problem - and the problems aren’t technical.

Anthropic’s own team maintains a CLAUDE.md in git to document mistakes and best practices. That’s the right instinct. The problem most teams hit is that one person writes it during initial setup, everyone else ignores it, and six months later it describes a project that no longer exists.

A JetBrains 2025 survey found that 61% of teams using Claude Code alongside other tools report duplicate configuration work averaging 5.3 hours per month. That’s not a tool problem. That’s an ownership problem.

Here’s the org design that actually works.

The CLAUDE.md Ownership Problem

Most teams treat CLAUDE.md like a config file. You write it once, commit it, and move on. But a config file describes a static system. Your codebase isn’t static.

The better mental model is a living document - closer to a team wiki page than a .eslintrc. It needs an owner, a review cadence, and a clear contribution process. Without those three things, it decays into irrelevance and developers stop trusting it.

Assign ownership explicitly. This doesn’t mean one person writes everything - it means one person is accountable for the quality of the document. On small teams this is usually the tech lead. On larger teams it can rotate quarterly. The key is that someone notices when the CLAUDE.md diverges from reality and does something about it.

Review it in sprint retros. Not as a major agenda item - five minutes at the end: “Did Claude struggle with anything this sprint that should be documented? Did we introduce a new pattern that isn’t captured?” This keeps the feedback loop tight without creating ceremony.

The silent failure mode is developers developing personal workarounds instead of improving shared context. Someone discovers that Claude keeps generating the wrong service layer pattern, writes a note in their personal scratch pad, and never surfaces it. That knowledge evaporates when they leave. The CLAUDE.md review in retro is specifically designed to surface those workarounds and institutionalize them.

What Belongs Where: Team vs. Personal

Your setup has two layers: the project-level CLAUDE.md committed to the repo, and your personal ~/.claude/CLAUDE.md that applies across all your sessions.

The team CLAUDE.md is for anything that should be consistent across every developer using Claude on this project. The personal file is for your individual workflow preferences.

Team CLAUDE.md (committed to repo):

• What the project does and who it’s for
• Tech stack and key architectural decisions
• Forbidden patterns with reasons
• Reference implementations (“use X as the model for Y”)
• Testing conventions and what counts as adequate coverage
• Environment setup that’s non-obvious

Personal ~/.claude/CLAUDE.md:

• Your preferred explanation style (“when I ask for options, give me exactly three”)
• Shortcuts you’ve trained yourself on
• Personal preferences that would annoy teammates (“always use British spelling”)
• Workflow patterns specific to how you work, not how the project works

The distinction matters because polluting the team file with personal preferences creates noise for everyone else, and putting project conventions in your personal file means new developers start without them.

The Four Sections Every Team CLAUDE.md Needs

I’ve reviewed a lot of team CLAUDE.md files. The ones that work share a structure. The ones that don’t usually have too much ceremony and not enough substance.

1. What this project does (two sentences max)

Not the marketing copy. The developer-facing reality. “This is a B2B SaaS application for construction project management. The core domain is bid tracking and subcontractor coordination.” Claude uses this for every session. Make it accurate.

2. Tech stack and key architectural decisions

List the stack, but also document the why behind non-obvious choices. “We use Inertia.js rather than a separate API because we intentionally avoided the SPA complexity overhead - don’t suggest decoupling the frontend.” That reason is load-bearing. Without it, Claude will suggest refactoring away from it constantly.

3. Explicit forbidden patterns with reasons

This is the highest-value section most teams skip. Example:

## Forbidden Patterns

- Do NOT use repository pattern. We use Active Record directly. Adding abstraction layers here creates complexity we don't want.
- Do NOT add new npm packages without checking package.json first. We have most utilities already.
- Do NOT generate migration rollbacks automatically. We review every rollback manually.

The reason matters. Without it, developers (and Claude) don’t understand when to apply the rule and when the situation is genuinely different.

4. Reference implementations

Claude learns patterns from examples better than from descriptions. When you’ve solved something well, point at it:

## Reference Implementations

- Service layer: see app/Services/BidService.php
- API resource: see app/Http/Resources/ProjectResource.php
- Feature test: see tests/Feature/BidSubmissionTest.php

Now when Claude generates new code, it anchors to your actual patterns rather than inventing its own.

Keeping It Current: The PR Checklist Rule

The best mechanism I’ve found for keeping the CLAUDE.md fresh is a PR checklist item: “If this PR introduces a new pattern that Claude struggled with or got wrong, update CLAUDE.md.”

This works because it attaches the update to the moment of highest relevance. The developer just spent 30 minutes correcting Claude’s approach to a problem - they know exactly what should be documented. Waiting until retro means that knowledge fades.

Put it in your PR template:

## Checklist
- [ ] Tests pass
- [ ] If a new pattern was introduced that Claude struggled with, CLAUDE.md is updated

It’s not a heavy lift. It’s one or two lines added to the relevant section. But compounded over a year of PRs, it produces a CLAUDE.md that actually reflects how the codebase works.

Onboarding New Developers to AI-Assisted Workflow

This part is almost completely undocumented in most teams, which means every new developer has to rediscover the workflow from scratch.

The pattern I use: a new developer’s first task is to read the CLAUDE.md, pick a small ticket (something estimated at 1-2 hours), work through it with Claude, and then add one thing to the CLAUDE.md they wished they’d known before starting.

This accomplishes three things. First, it forces real engagement with the document rather than a skim. Second, it produces a concrete contribution - the developer leaves their first mark on the codebase through documentation. Third, it surfaces gaps from a fresh perspective. Developers with six months in the codebase have stopped noticing things that are confusing to newcomers.

The quality bar for the addition is low on purpose. One sentence about something they had to figure out the hard way is enough. Over time, these accumulate into surprisingly useful context.

The Shared Hooks Pattern

Claude Code hooks let you run scripts automatically at specific points in a session - before a tool runs, after Claude responds, when the session ends. For teams, hooks are how you enforce conventions deterministically rather than hoping Claude remembers them.

Commit a .claude/settings.json to the repo with team-wide hooks:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint --silent"
          }
        ]
      }
    ]
  }
}

This runs your linter automatically after every file write. Every developer on the team gets this behavior without configuring anything. Formatters, test runners, type checkers - all of these can run automatically.

Personal overrides go in ~/.claude/settings.json. The local file merges with the project file, with local settings taking precedence. A developer who wants to disable the auto-lint during a specific session can do so without touching the shared config.

The key rule: the committed .claude/settings.json contains only team-wide conventions. Anything personal stays in the home directory file. This keeps the shared config lean and avoids the situation where one developer’s preferences get accidentally committed as team defaults.

The Session Handoff Problem

Claude has no memory between sessions. Every time you open a new session, you’re starting from a blank slate - Claude knows the codebase because it can read files, but it doesn’t remember what you built together yesterday, what decisions you made, or what you were planning to do next.

This is manageable if you build the habit. At the end of any significant session - one where you made real architectural decisions, worked through a complex problem, or set up something you’ll continue next time - ask Claude to document it:

“Write a summary of what we built in this session and what the next steps are. Save it as SESSION_NOTES.md.”

Or use Claude’s memory tool if you’ve set it up:

“Write a summary of what we built and what’s next to memory.”

The next session starts with: “Read SESSION_NOTES.md and continue from where we left off.” Claude picks up context immediately.

For team-shared context, the same pattern works - a WORKING_NOTES.md committed to the repo (and gitignored or not, depending on your preference) that captures in-progress decisions. It’s not a permanent document. It’s a handoff note.

The broader principle: Claude is a powerful tool with a hard constraint. Work with the constraint by externalizing memory explicitly. Teams that don’t build this habit spend the first 10 minutes of every session re-explaining context they already explained three days ago.

What Good Looks Like

A team CLAUDE.md that’s working has a few observable properties: it’s been updated in the last two weeks, it has commits from more than one person, and developers actually reference it when they’re unsure how to approach something.

A CLAUDE.md that’s failing has a single author, a last-modified date from the initial project setup, and developers who say “I don’t really look at it” when you ask.

The document is as useful as the discipline behind it. Build the discipline first - the ownership assignment, the retro review, the PR checklist item - and the document quality follows.

The tools are good. The gap is always the org design.