Claude Code in a Team, how to keep CLAUDE.md alive without turning it into a trash bin

Solo with Claude Code, everything runs smooth. You have your CLAUDE.md, you know every hook, you know exactly why the /deploy slash command is wired the way it is. Then the first colleague joins the repo, clones it, opens Claude Code, and suddenly the output is different. Answers read differently, code style conventions get ignored, the /deploy slash command produces a branch nobody expected.

That is not Claude Code being broken. That is missing team hygiene. CLAUDE.md, hooks and slash commands are exactly the places where solo workflows tip over the moment more than one person hangs off them. This playbook brings 10 steps to share that cleanly, without anyone committing their private notes by accident and without one person quietly bending the shared config.

I assume you use Git and you have a GitHub or GitLab workflow. If you are not familiar with Git for AI yet, take a look at mini-module L1-08 to L1-10 first.

Step 1, separate two CLAUDE.md files, shared and private

First rule. There are two homes for CLAUDE.md and they have different jobs. The shared CLAUDE.md sits in the repo root and gets committed. The private CLAUDE.md sits in ~/.claude/CLAUDE.md on your machine and never gets committed.

The shared file contains everything that applies to the team. Tech stack, code style, branch conventions, test commands, deploy paths. The private file contains your personal preferences. That you like more explanations during pair coding, that you use pnpm instead of npm on your machine, that you dislike claude --print mode.

If you mix that, chaos follows. One person reads "always write comments in English" in the repo CLAUDE.md, another would never have written that. Separate, immediately and consistently.

Step 2, keep the repo CLAUDE.md short

The temptation is big for everyone to dump their favourite note in. After three weeks the file has 800 lines, nobody reads it, Claude Code loads it into every context anyway. That is token waste and guaranteed drift.

Keep the repo CLAUDE.md under 200 lines. What does not fit goes into docs/claude/, a dedicated doc structure that Claude reads on demand. The repo CLAUDE.md then references those files by path instead of duplicating content. Saves tokens and makes the source of truth clear.

Rule of thumb. If you have not read the repo CLAUDE.md cover to cover in 5 minutes, it is too long.

Step 3, sections with owners

Structure the repo CLAUDE.md into sections, and put behind each section who maintains it. Example.

## Tech stack (owner: all)
- Next.js 16, Prisma 7, Postgres
- Pnpm for package management
- Vitest for tests

## Deploy workflow (owner: Anna)
- main auto-deploys to Vercel
- staging via `pnpm deploy:staging`

## Database migrations (owner: Tim)
- ALWAYS `prisma migrate dev --name <slug>` locally
- NEVER `db push --force-reset` in CI

If something sits in repo CLAUDE.md without an owner, nobody will update it after three weeks. With an owner, one person goes in, checks, makes a PR. Same principle as any other doc.

Step 4, take the .claude directory into the repo

Claude Code drops project-specific skills, slash commands and hooks under .claude/ in the repo. That belongs in Git. What does not belong are personalised logs and caches, so you need a .gitignore entry.

# .gitignore
.claude/cache/
.claude/sessions/
.claude/local-settings.json

What gets committed is .claude/skills/, .claude/commands/ and .claude/hooks/. Plus a .claude/README.md that briefly explains what lives in the directory and who maintains it.

If your team does not separate this, every person has different logs in Git and pull requests turn into a conflict hell. Better to set up cleanly now than migrate later.

Step 5, one person is skill owner per project

Skills are capability-like add-ons that Claude uses in a project. In a solo project everyone writes their own. In a team project ONE person MUST own them. Otherwise everyone has their own variant of "code review skill" and the output is no longer reproducible.

Find or pick a skill owner. This person merges new skills, checks for conflicts, removes outdated ones. Others can propose, draft new skills, but merging happens through the one person. Sounds bureaucratic, is exactly what you will be thankful for after three weeks of drift.

Step 6, version slash commands like code

Slash commands are small shortcuts like /deploy or /review-pr. If Tim tweaks /deploy this morning because he has an edge case and you deploy in the afternoon, things go wrong. Slash commands are code, treat them like code.

Three rules that hold for us. Every change to a slash command goes through a pull request, not directly to main. The commit message says WHAT changed, not just "update deploy". And the repo CLAUDE.md has a section that briefly explains what each shared slash command does.

If a slash command only makes sense for one person, it belongs in the private ~/.claude/commands/ directory, not in the repo.

Step 7, keep cost-bearing hooks separate

Hooks can make API calls, so they can cost money. If someone builds a hook that calls Claude Haiku on every tool use and it runs uninvited on all 5 team members all day, that is a few hundred euros a month.

Mark in .claude/hooks/README.md which hooks cost money and which do not. Cost-bearing hooks should be opt-in, only people who activate them run them. Defaulting cost-bearing hooks in the repo is a small dictatorship.

Rule of thumb. Per new hook, an estimate "costs about X cents per 100 calls" in the comment. Saves the awkward question later "why is the Anthropic bill 400 euros this month".

Step 8, pull requests to CLAUDE.md need a review

Sounds obvious, is not. Many teams commit straight to main when "only the note for Claude" changes. That causes drift because nobody sees the change.

Set the rule. CLAUDE.md, .claude/skills/, .claude/commands/ and .claude/hooks/ all need a code review like any normal code. In the review comment, briefly explain why the change was needed. If the reviewer does not understand why a skill change is coming, that is a sign the change is probably not team consensus.

Bonus. On CLAUDE.md changes you can additionally check whether the file stays under 200 lines (see step 2). Otherwise the trash effect creeps in.

Step 9, quarterly team cleanup

Every three months you do a one-hour "CLAUDE.md cleanup day". Together on screen, one Zoom call, you scroll through everything that has accumulated in Claude config. What is still used, what is outdated, what can go.

My rhythm is mid-January, mid-April, mid-July, mid-October. Sounds rare, is enough. What happens between cleanup days is caught by pull requests. What slips your mind between May and July is caught by the cleanup day.

Concrete approach. Three columns on a whiteboard. Keep, change, delete. Per skill, per slash command, per hook one card, everyone votes, at the end one person moves the cards into the respective piles. Delete in one single pull request, not in five separate ones.

Step 10, onboarding doc for new team members

If Lisa joins the team on Monday, she should not have to crawl through 200 lines of CLAUDE.md first. Write a 30-minute onboarding doc in docs/claude/onboarding.md. What does Lisa need to install locally, which variant of Claude Code (Pro or API), which hooks should she activate, which cost-bearing ones better not, which skills are mandatory and which optional.

Plus a smoke test. At the end of onboarding, Lisa does a task like "describe what happens in src/lib/auth.ts with Claude Code's help". If the output looks like team standard, she is set up. If not, something is missing in her local config and you can fix it now instead of two weeks later when she is already frustrated.

Whoever does not write the onboarding down forces every new colleague to figure out the same path themselves, and each of those paths has a different solution. That is the birth of drift.

What's next

If you got through this, your team setup is solid. The next sensible step is the playbook "Your own slash commands for Claude Code", where you learn how to build the next shared slash command cleanly. If you have no committed hooks yet, "Hooks against hallucinations" is worth doing next. And if you are thinking about updating to Claude Code 2.x while the team is still on 1.9, look at the playbook "Claude Code update strategy" before someone has a broken workflow on Monday morning.