CLAUDE.md: Global vs Project — What Goes Where

Claude Code reads CLAUDE.md at two levels. The user-global file at ~/CLAUDE.md (or ~/.claude/CLAUDE.md) loads in every session, on every project. The project-local CLAUDE.md at the repo root loads only when you are working in that repo. Both files are read; their contents stack. The decision of which content goes where is one of the most consequential choices in the harness, and one of the easiest to get wrong.

Why the split exists

The split is not cosmetic. It exists because some rules belong to you and some belong to the project, and conflating the two produces predictable failures.

Rules that belong to you are about how you work — your communication style, your tools, your operational quirks, the conventions you have across all your projects. These do not change when you switch projects. They are not negotiable with collaborators. They live in ~/CLAUDE.md, and every project you touch inherits them.

Rules that belong to the project are about what the project is and how the team has decided to operate. These do not change when you leave or someone else joins. They are decided by the team, encoded in the repo, and apply equally to every contributor and every agent that touches the code. They live in the project's CLAUDE.md, alongside the rest of the project state.

When you put project rules in ~/CLAUDE.md, the rules follow you instead of the project — which means a collaborator who clones the same repo gets a different agent experience. When you put personal preferences in the project file, they get shipped to everyone, including collaborators who do not share them. Both cases produce friction.

What goes in the global file

Eight categories tend to belong in ~/CLAUDE.md for most users.

Communication style. What language to talk to you in, how terse, what tone, what nicknames if any. The agent's communication preferences are personal — they should not change per project.

Universal hard rules you apply everywhere. "Never edit lockfiles by hand," "never push directly to main," "all changes through PR." If you apply these to every project, they belong global so you don't repeat them in fifteen project files.

Operational notes about your machine. Where your tools live, what shell you use, what virtualization platform, what code editor. The agent benefits from knowing your local environment; the project does not need to know.

Default tools and aliases. "Prefer rg over grep," "I have a shortcut kw that means kalami + worktree." These are personal ergonomic preferences.

Your knowledge bases. The paths to your Armory, your AIMD experience library, your wiki, your scratchpad. These are yours, not the project's.

Default behaviors when context is missing. "When unsure, ask one specific question, not three." "Don't create new files in the home directory." Personal defaults that should kick in regardless of project.

Your workflow conventions. "I review code before pushing," "I want a plan before any 3+ step task," "I expect commit messages in imperative mood." How you work, not how the project works.

Your meta-rules. "Tell me what you're about to do before each tool call." These shape the agent's interaction style with you specifically.

What goes in the project file

Six categories tend to belong in the project's CLAUDE.md, regardless of who is contributing.

Project description. What this project does. What it is for. What stack it runs. The first paragraph in every well-written project CLAUDE.md.

Team-decided process rules. Branching strategy, commit conventions, PR requirements, test requirements, release process. These are team contracts; every contributor must follow them.

Project-specific tooling. Build commands, test commands, dev environment setup, package manager. Different projects use different tools; the project file is where this gets pinned.

Architecture decisions. "Monolith, not microservices." "State via Jotai, not Zustand." "Use TanStack Query for server state." Decisions the project has made that the agent should not relitigate.

Operational facts about the codebase. "This path is a symlink." "The Playwright suite is flaky on Tuesdays." "The migration in 0042 is intentionally non-reversible." Project-specific knowledge that survives across contributors.

Project principles. Three to seven, with rationale. The principles that the team has agreed apply to this codebase. Different projects can have different principles — this is where they go.

The override mechanic

When a rule appears in both files, the project rule wins. This is the documented and expected behavior in Claude Code. It also produces a recurring source of confusion: a global rule "use bun" gets overridden by a project rule "use npm" without any warning. The agent obediently switches, but the global rule remains in your ~/CLAUDE.md looking like it should still apply.

The discipline is to make overrides explicit. When a project file overrides a global rule, the line should say so: Use npm — overrides ~/CLAUDE.md § Tools (project CI requires npm). This makes the override traceable and tells the agent that the contradiction was deliberate.

The opposite case — a project rule that contradicts a global rule unintentionally — is harder to catch. AgentLint v0.4 (planned) will check for global-vs-project contradictions and flag undeclared overrides. Until then, the manual sweep is to grep both files for the same nouns and check for contradictions.

Migration patterns

Two migration patterns come up often.

Promoting a project rule to global. You have written the same rule in three project CLAUDE.md files in a row. That is the signal it should be global. Move it once to ~/CLAUDE.md, delete from the three project files, run AgentLint to confirm none of them re-introduce it as an override.

Demoting a global rule to project. You have a global rule that does not actually apply to a new project. The temptation is to add an exception in the project file. Better path: check whether the global rule is correct as-stated for most of your projects. If yes, add an explicit override in the new project. If no, the global rule was wrong — move it down to the projects where it actually applies.

The principle is that ~/CLAUDE.md should encode rules that apply almost universally to your work. If you find yourself overriding a global rule in 30% of projects, the global rule is wrong.

A worked example

Here is the same rule cluster, allocated correctly:

~/CLAUDE.md (excerpt):

## Communication
- Talk to me in spoken Chinese during chat. Code, comments,
  commits, docs in English.
- Be terse. No "Let me know if..." trailers.
- Default discussion mode unless I use action verbs.

## Universal rules
- All changes go through PR. No direct pushes to main.
- Don't edit lockfiles by hand. Use the package manager.
- No secrets in commits. .env* is gitignored globally.

## Operational
- I work on a Mac Studio M4 Max. Tools live at /opt/homebrew/bin.
- I prefer rg over grep, fd over find, bat over cat.
- My scratch dir is /tmp; my project dir is ~/Projects.

Project CLAUDE.md (excerpt, same conceptual cluster):

## Project
A real-time collaboration tool. TypeScript, React, Yjs,
Postgres, Redis, deployed on Fly.io.

## Process
- Branch from main, PR, squash-merge.
- Tests required: Vitest unit + Playwright E2E.
- Use bun, not npm — overrides ~/CLAUDE.md § Tools.

## Architecture
- Monolith. We tried microservices in Q3 2024 — do not propose.
- State: TanStack Query for server, Zustand for client. No Redux.
- CRDT via Yjs. Do not propose Automerge or Y.js wrappers.

## Operational
- Postgres 16 + Redis 7 via docker-compose; `bun dev:up`.
- Playwright requires `bun exec playwright install` after clone.
- CI runs Linux only — Mac/Windows local issues do not fail CI.

Notice: the global file talks about how you work; the project file talks about how the project works. They share the abstraction "rules" but partition cleanly. The project file's bun, not npm line explicitly cites the global override, so the contradiction is deliberate and traceable.

What to do this week

Two practical exercises. First, read your ~/CLAUDE.md and the CLAUDE.md of the project you are most active in. Identify any rule in ~/CLAUDE.md that is actually project-specific (mentions a tool only one project uses, references a path only one project has). Move those to the project file. Identify any rule in the project file that is actually personal preference (your communication style, your shortcuts). Move those to global. The reallocation usually shrinks both files.

Second, make sure every undeclared override is either declared or removed. Grep for common nouns (build command, package manager, test runner, branching strategy) in both files. Where they contradict, add the explicit "overrides ~/CLAUDE.md § X" tag in the project file. The agent will appreciate the disambiguation, and so will future contributors who read both files cold.