Merging and Sharing a Team CLAUDE.md Through Git (Claude Code)

The problem: a different Claude on every machine

• Restrictions differ by person. One CLAUDE.md says “don’t commit,” another doesn’t, so Claude commits on its own.
• Rules are all over the place. Naming, comment language, and whether to run tests differ from file to file, so output from the same project doesn’t match in style.
• Outdated content lingers. Written once early in the project and never touched, they still describe folder structures and conventions that are long gone.
• What someone figures out doesn’t spread. A workaround someone found after a struggle lives only in their local file, so the person next to them repeats the same struggle from scratch.

The last one hurt the most. The original article has a similar story: a junior spent two hours rediscovering a workaround three seniors already knew. Knowledge was stuck in personal files, exactly our situation.

The turning point: shorter wins

At first I thought merging everyone’s CLAUDE.md would produce the perfect file. It quickly grew to thousands of lines, and the article hit exactly that point.

Both are short and work better. CLAUDE.md is loaded in full at the start of every conversation. A big file spends tokens before you even ask anything, and the longer the context, the worse the model gets at holding on to earlier instructions (context rot). In the NoLiMa benchmark the article cites, 11 of 12 models dropped below 50% recall accuracy at 32k tokens.

So I switched from a union to an intersection plus a diet.

When implementing authentication, always ensure you follow security best practices including input validation, proper error handling, secure token storage...

Auth: validate inputs, handle errors securely, follow auth/ patterns

Same content, far fewer tokens. With this principle I cleared out overlapping sentences, defensive “just in case” instructions, and rules nobody used anymore.

The 7 anti-patterns, against my experience

Rather than list all seven as they are, I regrouped them around what actually tripped us up while merging.

Three of these are closest to the heart of merging, so here they are in more detail.

Solo configuration: sharing through git is the whole job

The article quotes Boris: “At Anthropic, each team keeps its CLAUDE.md in git.” That one sentence sums up what I did. Here’s the structure.

project-root/
├── CLAUDE.md         # shared, committed to git (team rules)
├── CLAUDE.local.md   # personal taste, .gitignore
└── .claude/
    └── commands/     # team slash commands

The key is splitting team rules and personal taste into separate files. Team rules go in CLAUDE.md so everyone uses the same thing, and personal taste like “I prefer this log format” stays in CLAUDE.local.md, which is in .gitignore. A new teammate gets the full team context with a single clone. We pass on far fewer rules by word of mouth during onboarding.

Static memory: a document that keeps growing

Merge it and leave it, and the same problem comes back. So we made it a rule.

• Lessons from PR reviews go into CLAUDE.md on the spot. If the same comment comes up across several PRs, it’s a rule that should have been in the md.
• To add something mid-session, use the # shortcut. Type something like # utils use named exports only and it goes straight into memory.
• Review it once a month. Delete what’s stale and fill in what’s missing.

Verification loop: make it team-wide

What Boris called most important in the article is giving Claude a way to verify its own work. Verification alone reportedly lifts final quality two to three times. If it varies by person it means nothing, so we put it in the shared md.

## Verification
- Run `npm test` after code changes
- Run `npm run typecheck` before marking done
- Check API changes with curl/Postman
- Check UI changes in the browser before committing

Because it’s in the project context, Claude runs these on its own without being told in every prompt. With it applied across the team, nobody skips past with “it’s probably been checked.”

Results

It hasn’t been running long, so this isn’t a big success story, but the difference is clear.

The best part is the compounding. Every PR makes CLAUDE.md a little better. What we learned the hard way used to vanish inside personal files. Now it builds up as a team asset.

It’s not a silver bullet. Getting everyone on the team to contribute is a culture problem and still hard (only a few contribute actively), and complex verification like distributed systems still needs human judgment. Even so, getting rid of the root problem, a different Claude on every machine, was well worth it.

Wrapping up

The value of CLAUDE.md isn’t its length. It comes from the team looking at the same thing and that thing continuing to grow. There was no hard technology involved. We just changed “everyone on their own” to “the team together,” and the difference was bigger than I expected.