Claude Code Version Control: Which CLAUDE.md Files Your Team Actually Shares

Why Claude Code version control decides team consistency

Claude Code version control is the lens that turns the configuration hierarchy from a list of file locations into a story about teams. The previous knowledge point established three scopes; this one asks a single sharper question about each: does it travel through git? The answer is what determines whether your colleagues experience the same assistant you do, or a quietly different one. Understanding this is the difference between configuring Claude for yourself and configuring it for a team.

The rule is clean. Project-level and directory-level CLAUDE.md files live inside the repository, so they are committed and distributed to everyone who clones it. The user-level file at ~/.claude/CLAUDE.md lives in your home folder, outside any repository, so git has no idea it exists. A fourth file, CLAUDE.local.md, is the deliberate escape hatch: it sits in the project but is meant to be gitignored, so you can keep personal project notes without pushing them. Two scopes are shared, two are private, and almost every team-consistency problem traces back to confusing the two groups.

What git tracks, and what it cannot

It helps to think in terms of the repository boundary. Anything inside the repository folder is a candidate for version control; anything outside it is invisible to git no matter how relevant it is to your work. The project CLAUDE.md and any nested directory files are inside the boundary, get staged and committed like source code, and therefore reach every future contributor automatically. There is no separate distribution step. Cloning the repo is the distribution.

The user file is the mirror image. Because ~/.claude/CLAUDE.md lives in your home directory, it is outside every repository simultaneously, which is exactly what makes it useful for cross-project personal preferences and exactly what makes it useless for sharing. It cannot be committed from inside a project because it is not part of that project. When you write an instruction there, you are writing it for one machine.

CLAUDE.local.md sits in an interesting middle position: it is physically inside the project, so git would track it if you let it, but the intended pattern is to add it to .gitignore so it stays personal. This gives you a place for project-specific but private details, a local sandbox URL, your preferred test fixtures, without leaking them to the team or polluting the shared file.

The consequence: consistency is a placement decision

Here is the understanding the exam wants you to demonstrate. The quality of a rule has nothing to do with whether your team benefits from it. A beautifully written standard placed in your user file improves your sessions and no one else's. A mediocre rule committed to the project file at least reaches everybody. Consistency across a team is therefore a placement decision long before it is a content decision.

This reframes a whole category of confusing symptoms. When two developers on the same repository get noticeably different output, the instinct is to suspect the model, or to assume one of them is prompting badly. Far more often, one of them has a relevant instruction in their personal config that the other simply never received. The behaviour looks like inconsistency in Claude; it is actually consistency in git faithfully shipping only what was committed.

A new joiner exposes the gap

The cleanest way to feel this rule is to watch what happens when someone joins. A new teammate clones the repository and instantly has the project and directory files, because those are part of what they cloned. They have none of the existing team's personal configuration, because that was never theirs to receive. If the team had been quietly relying on a standard that one senior developer kept in their user file, the new joiner is the first person to notice it missing, and their output diverges from day one.

Common misreadings to avoid

Both errors below come from forgetting which side of the repository boundary a file sits on.

Sharing instructions without git: the managed claudeMd setting

Version control is the usual way to distribute shared instructions, but it is not the only one, and the exception is worth knowing because it behaves unlike every scope above. Organisations that manage developer machines centrally can inject CLAUDE.md content through the claudeMd key in managed-settings.json, the managed-policy settings file. Content placed there applies to every Claude Code session on that machine, in every repository, without ever being committed to any of them. It is distribution by device policy rather than by clone, which makes it the right tool for organisation-wide guidance and the wrong tool for project-specific standards.

Two precise facts make this exam-relevant. First, claudeMd only takes effect as a managed-policy setting; placing it in an ordinary user, project, or local settings file has no effect at all, a detail that quietly defeats teams who try to set it in a regular settings.json. Second, because it is machine-wide and lives outside any repository, it sits above the version-control story entirely rather than replacing it. Per-project standards still belong in the committed project file so each repo carries its own; managed claudeMd is reserved for blanket guidance that should hold on a fleet of machines regardless of which project is open.

Auditing what your team actually shares

Because the danger is invisible by design, a small habit prevents most version-control surprises: periodically audit what the repository genuinely carries versus what individuals have quietly come to rely on. The quickest version of this audit is to open the committed configuration, the project CLAUDE.md, any directory files, and any .claude/rules/ files, and read them as if you were a brand-new hire. Whatever is not written there is not something a new teammate will receive, no matter how universally the current team behaves as though it is.

A useful forcing function is onboarding itself. When someone joins and their output diverges, treat it as free diagnostic information rather than a nuisance: the new joiner is effectively running the repository's configuration with none of the accumulated personal layers, so any behaviour that disappears for them was being supplied by an unshared scope. Rather than patching the new person's machine, move the responsible instruction into the committed file so the gap closes for everyone, permanently.

Running /init on a fresh checkout is another way to surface the baseline. It generates or improves a project CLAUDE.md from what is actually in the codebase, which gives you a concrete, shareable starting point and makes it obvious how much of your team's 'shared' behaviour was never really shared at all. The goal of the audit is not perfection; it is to keep the committed configuration the single honest record of how the team works.

Why placement is the highest-leverage fix for team drift

It is worth dwelling on why this knowledge point matters out of proportion to how simple it sounds. Teams reach for elaborate remedies when their assistant behaves inconsistently, longer prompts, stricter wording, even discussions about changing models, when the actual lever is almost always a one-line change of file. Moving a standard from an unshared scope into a committed one is cheap to do, immediate in effect, and durable, because version control keeps distributing it to every future clone without anyone remembering to.

Framed that way, version control is not a deployment detail bolted onto configuration; it is the mechanism that makes a team's standards real. An instruction that is not committed is, for the team, merely an intention. An instruction that is committed is a guarantee that every clone carries it. Internalising that distinction turns a whole category of frustrating, hard-to-reproduce inconsistencies into a quick, confident fix, which is exactly the judgement the certification is checking you can exercise.

Make the shared file the source of truth

The throughline of everything above is a single working principle: the committed project configuration should be the one honest record of how the team works, and nothing the team genuinely relies on should live anywhere git cannot reach. When that principle holds, the awkward surprises this knowledge point describes, the year-old habit that vanishes for a new hire, the convention only one person seems to follow, simply stop occurring, because there is no hidden personal layer for the team's behaviour to hide in.

Getting there is rarely a big project. It is usually a handful of small relocations, lifting a rule out of a personal file and committing it into the project, repeated whenever an audit or an onboarding exposes a gap. Each move is cheap, and each one makes the team's behaviour a little more reproducible. Over time the shared file becomes exactly what it should be: the single place a newcomer can read to understand, in full, how this team expects its assistant to behave.

How this shows up on the exam

This is an understand-level knowledge point inside Domain 3, which is worth 20 percent of the exam, and it powers a recurring scenario shape: a description of two developers, or an established team plus a new hire, behaving differently on the same codebase. The examiners want you to reach past 'the model is inconsistent' and recognise a scoping-and-sharing problem. The diagnostic instinct to build is simple, ask where the relevant instruction lives, and whether that scope is version-controlled. Once you can reliably separate the shared scopes from the machine-local ones, you are ready to actually trace these inconsistencies to their root cause and design a configuration that prevents them.

Watch and learn

Official Anthropic Academy lessons first, then hand-picked walkthroughs. Videos load only when you press play.

Official · Anthropic AcademyOpen full lesson in Academy

Sharing skills

Why watch: Whether a skill is version-controlled determines if teammates receive it, the team-consistency implication this KP stresses.

More videos for this concept

Sharing skills

Introduction to Agent Skills

Claude Code just changed Memory Forever (Tutorial)

Jack Roberts

Claude Code's Memory System: The Full Guide (Most Developers Miss 90% of This)

DIY Smart Code

Master ALL 7 Levels of Claude Code Memory

Mark Kashef