CLAUDE.md examples that actually change behavior.

One file, three locations.

CLAUDE.md is plain markdown. Claude Code loads it at session start and treats it as standing context — not enforced configuration, context. Where you put it decides who it applies to:

• ./CLAUDE.md — repo root, checked into version control. Team-shared: build commands, conventions, architecture decisions. (./.claude/CLAUDE.md works too.)
• ./CLAUDE.local.md — same repo, gitignored. Personal, per-project: your sandbox URLs, your test data, your communication preferences. Loads right after the project file.
• ~/.claude/CLAUDE.md — global. Applies to every project on your machine. Loads before project files, so project instructions can override it.

Two loading details worth knowing. Claude Code walks up the directory tree from wherever you launch it, so a CLAUDE.md in a parent directory loads too. And CLAUDE.md files in subdirectories don't load at launch — they load on demand, when Claude reads files in that directory. That second behavior is what makes the monorepo pattern below work.

Files can also import other files with @path syntax — @docs/git-instructions.md pulls that file into context at launch. Useful for sharing one instruction set between CLAUDE.md and an AGENTS.md that other agents read.

Example 1: the minimal starter.

Ten lines. Commands Claude would otherwise guess at, and one pointer on style. Most projects need this file first and many never need more:

Note what's absent: no project description, no directory tree, no tech-stack inventory. Claude can discover all of that by reading the code. The file only holds what discovery gets wrong — the single-file test invocation, the lint-before-done rule.

Example 2: test discipline, enforced in prose.

For teams whose main failure mode is an agent that reports "done" with red tests. Every line targets a specific bad behavior:

The all-caps FIRST and the numbered definition of done aren't decoration — specificity is what makes instructions verifiable, and verifiable instructions are the ones that get followed. "Test your changes" does nothing; "never modify a test to make it pass" names the exact behavior you're banning.

Example 3: monorepo root with per-package pointers.

Don't write one giant file for a monorepo. Write a thin root file and put a CLAUDE.md in each package — subdirectory files load on demand when Claude works in that package, so the context cost lands only where it's spent:

The root file holds only what crosses package boundaries. Everything specific to the API — its test database, its migration commands — lives in apps/api/CLAUDE.md and loads only when Claude touches API files.

Example 4: a personality layer under the engineering rules.

CLAUDE.md configures behavior, and how Claude communicates with you is behavior. Append a personality-matched section after your engineering rules — this one is condensed from the ISTJ tuning:

Different type, different rules — the INTJ file bans hedging and permission-asking; the ENFP file is nearly its inverse. All 43 are free in the library, and if you don't know your type, the free MBTI test takes about ten minutes. The full argument for why this layer belongs in an engineering file is in coding agent personality.

The principles: short and imperative beats long and narrative.

• Imperative, not narrative. "Run npm test after every change" outperforms a paragraph about how much your team values quality. Claude follows commands; it skims essays.
• Constraints the code can't express. The best CLAUDE.md lines are things no amount of code-reading reveals: "the staging DB is shared — never run destructive migrations," "packages/config changes need an RFC." Rationale, pitfalls, and politics — not structure.
• Don't duplicate what's greppable. Directory trees, dependency lists, function inventories — Claude can read the repo. Every greppable line in CLAUDE.md is context spent twice, and it goes stale the day someone refactors.
• Stay under ~200 lines. Anthropic's own guidance: longer files consume more context and reduce adherence. If it's growing, split it — per-package files in a monorepo, or path-scoped rules in .claude/rules/.
• Maintain it like code. A stale instruction is worse than none — Claude will follow it. When Claude makes the same mistake twice, add a line; when a rule stops being true, delete it. Review it in the same PRs that change what it describes.

The mistakes that make Claude ignore the file.

• The wiki dump. Pasting your architecture doc into CLAUDE.md. Adherence drops as length grows; the ten rules that matter drown in forty paragraphs of background.
• Contradictions. "Prefer small PRs" in the global file, "batch related changes" in the project file. Claude picks one arbitrarily. Audit across all three locations.
• Vague virtues. "Write clean, maintainable code" changes nothing. If you can't verify compliance, Claude can't either.
• Treating it as enforcement. CLAUDE.md is context, not a gate. If something must always happen — lint before commit, no pushes to main — use a hook or a permission rule. Prose is for guidance; tooling is for guarantees.
• Personal preferences in the team file. Your sandbox URL and your ISTJ communication layer belong in CLAUDE.local.md or ~/.claude/CLAUDE.md — not in the checked-in file your teammates inherit.

Questions people ask.

Keep going.