Most CLAUDE.md best practices are written as advice for a file the author has not had to live with. We have lived with ours. It is 107 lines, every session reads it, and almost every line is there because something went wrong once.

The short version
  • CLAUDE.md is a markdown file Claude Code loads at the start of every session. It is guidance. It is not enforcement.
  • There are four locations. Organisation policy, your user file, the project file and a local file kept out of git. They are concatenated, not overridden.
  • Global holds how you work. Project holds how this repository works. Say so in words when a project rule replaces a global one.
  • Write the rule and the reason. A rule with its reason gets applied to cases you did not foresee.
  • A config string that reaches the model is behaviour. Update the prompt copy when you update the enforced value.
  • Keep it short. Anthropic's target is under 200 lines. Cut whatever Claude can read from the code.

This post uses our own files as the worked example. Vendor facts come from Anthropic's documentation as fetched on 18 November 2026. It belongs to our guide to how AI agents work, and it pairs with our post on Claude Code memory, which covers the notes Claude writes for itself.

What a CLAUDE.md file is, and what it is not

Every Claude Code session starts with an empty context window. A CLAUDE.md file is how instructions survive that. Anthropic's memory documentation defines it as a markdown file that gives Claude "persistent instructions for a project, your personal workflow, or your entire organization", read at the start of every session.

Two facts from that page set the limits of everything below.

It is context, not configuration. The docs: "Claude treats them as context, not enforced configuration." They also explain the mechanism: CLAUDE.md content "is delivered as a user message after the system prompt, not as part of the system prompt itself". Claude reads it and tries to follow it, with no guarantee of strict compliance.

Every line costs attention. The best-practices page puts it this way: the file loads into every session, so "every line in it takes a little of Claude's attention on every task, whether it's relevant or not".

So a CLAUDE.md is a briefing for a capable colleague who starts each day with no memory of yesterday. It is not a rulebook that enforces itself, and it is not documentation of your architecture.

CLAUDE.md location: where files live and how they load

The documented locations, as of November 2026, in the order they load:

Scope Location Shared with
Managed policy macOS: /Library/Application Support/ClaudeCode/CLAUDE.md; Linux and WSL: /etc/claude-code/CLAUDE.md; Windows: C:\Program Files\ClaudeCode\CLAUDE.md Everyone in the organisation
User ~/.claude/CLAUDE.md Only you, across all projects
Project ./CLAUDE.md or ./.claude/CLAUDE.md Your team, through version control
Local ./CLAUDE.local.md, added to .gitignore Only you, in this project

Three loading rules catch people out.

Files stack. They do not override. The docs: "All discovered files are concatenated into context rather than overriding each other." Content is ordered from the filesystem root down to your working directory, so instructions closer to where you launched Claude are read last. Within a directory, CLAUDE.local.md is appended after CLAUDE.md.

Parents load at launch, children load on demand. Start Claude Code in foo/bar/ and it loads foo/bar/CLAUDE.md and foo/CLAUDE.md. A CLAUDE.md in a subdirectory below you loads only once Claude reads or edits a file in that subdirectory.

Conflicts are resolved by chance. If two files disagree, the docs say Claude "may pick one arbitrarily". There is no precedence engine.

loaded at launchstart Claude Code in foo/bar/managed policy + ~/.claude/CLAUDE.mdyour organisation's file and your ownfoo/CLAUDE.md, then foo/bar/CLAUDE.mdordered from the root down to where you startedCLAUDE.local.mdappended after CLAUDE.md in the same directoryloaded on demandonly when Claude reads therefoo/bar/sub/CLAUDE.mdloads once Claude reads or edits a file in sub/All discovered files are concatenated; none overrides another. If two disagree, Claude "may pick onearbitrarily". Check what loaded with /context all.
How CLAUDE.md files stack. From Claude Code's memory documentation.

To see what loaded in the session you are in:

/context all

and look under Memory files. To open any of the files in your editor, run /memory. To generate a first project file from your codebase, run /init; if a CLAUDE.md already exists, the docs say it suggests improvements instead of overwriting it.

If your repository uses AGENTS.md for other coding tools, Claude Code v2.1.277 or later can read that instead when no CLAUDE.md is present. The details are in our comparison of CLAUDE.md vs AGENTS.md.

Global vs project: what goes in each

The split we use is simple. The global file describes how we work. The project file describes how one repository works.

Our global file at ~/.claude/CLAUDE.md has thirteen sections. None of them names a client or depends on one repository's layout. The headings give the idea: verify before you assert, delegation, evaluate critically, correct the record, money and irreversible actions, find the source of truth before editing, finish the change, shipping, memory hygiene. These are habits that should hold in a WordPress repository, a Shopify theme and a Python agent alike.

It opens by stating its own scope:

# Operating standards

Applies to every project in this tree. Project-level CLAUDE.md files override this where they conflict.

That second sentence is doing real work, and it is worth being precise about why. As the docs say, nothing in Claude Code makes a project file win. Our sentence is an instruction to the model about how to resolve a conflict, not a setting. It helps, and we back it up on the other side. One of our client repositories has no remote, so the global rule to open a pull request cannot apply. Its project file says:

- The repo has no remote, so no PRs (this overrides the global rule to open one).

Name the rule you are replacing and say that you are replacing it. An agent reading both files then has no conflict to guess at.

The global file also tells project files what they should own. Its shipping section ends: "Repo-specific deploy behaviour belongs in that repo's own CLAUDE.md, not here." Which is where the project files come in.

A CLAUDE.md file example: three project files, anonymised

We keep a project-level file in each repository. Here are three, described with client details removed, because they show three different shapes.

Our own site's repository: 25 lines. Three headings: shipping, the scheduled agent that lives in the repo, and working in this repo. The shipping section exists because of one trap:

- **Merging to `main` auto-deploys** via `.github/workflows/deploy-production.yml`. A manual `gh workflow run deploy-production.yml` dispatches against `main`, not your branch — so it redeploys whatever is already live and does nothing for unmerged work.

And the "working in this repo" section saves every session a wasted search:

- Tracking changes touch `_local/head.html` (injected at deploy) and `assets/js/track.js`. The built pages in the repo do **not** contain the tags — editing a page's HTML looking for a pixel is a dead end.

Both lines pass Anthropic's test. Claude could not learn either from reading the code without going down the wrong path first.

A photographer's static site: 35 lines. A short description of how the site deploys, then a list headed "Rules for this site". The first rule is the one that matters most: pages are generated, so edit the build script and never the output file. Most of the others record a decision the operator made, with the date, so a later session does not reopen it. One says the logo is the client's name in one typeface and nothing else, and notes when a set of generated logos was turned down. That is a decision that exists nowhere in the code.

A back-office platform for a client: 101 lines. The largest, with three parts: where things are, what to read first, and a section titled "Rules that have bitten". We like that heading. It tells the reader, human or model, that each entry is there because of a real failure. One of them:

- Any claim about a screen, in a build, a check, a report or an answer [...] needs evidence from the running app [...] Reading the code is not proof.

This file is at the upper edge of what we think works. It stays readable because most lines point at a document instead of repeating it: read the conventions file before touching a module, read the runbook before touching the live server.

One more, as a caution. An older WordPress client file of ours has headings reading "MUST FOLLOW" and "ALWAYS APPLY". Anthropic now lists that style under advice you can stop following: current models follow a plainly worded line, and piling on emphasis "mostly makes Claude over-apply the rule". The fix it gives is the one we would give: if a rule cannot bend, make it a hook, and if a line is getting lost, the file needs to be shorter. That file is due an edit.

For comparison, the compact example from Anthropic's own best-practices page:

# Commands
- Install: pnpm install
- Run one test file: pnpm vitest run path/to/file.test.ts
- Typecheck: pnpm tsc --noEmit

# Conventions
- Use the error helpers in src/lib/errors.ts, never throw raw strings
- src/legacy/ is still live but don't copy its patterns into new code

# Gotchas
- Integration tests need DATABASE_URL set, see .env.example

Write the rule plus the reason

The docs ask for instructions "concrete enough to verify". Their examples: "Use 2-space indentation" instead of "Format code properly", and "Run npm test before committing" instead of "Test your changes".

We would add one thing. Put the reason on the same line. A bare rule covers the case you wrote it for. A rule with its reason gets applied correctly to cases you did not think of, and gets skipped correctly when the reason does not hold.

Three lines from our global file show the pattern:

- Ad accounts, APIs, analytics: read the current state through the API before diagnosing or "fixing" anything. Past sessions have wasted work fixing problems that no longer existed.
- Quote glob arguments in shell commands (`--include='*.ts'`, `find . -name '*.ts'`): the shell expands an unquoted glob that matches before the command sees it [...]
- Run `git add -N <new files>` before `/code-review`: it reviews `git diff`, which leaves untracked files out.

Each one is an instruction, a colon or a full stop, and then the mechanism. The third is the cleanest. A session that knows why the step exists will also know to do it before any other tool that reads git diff.

The reason also earns the rule its place. Our delegation section opens with its justification before any rule: "Subagents multiply cost and latency — each one re-establishes context, re-explores, reports back, and then you re-read the report." The rules that follow read as consequences, not as arbitrary limits.

A few more habits that have held up:

  • State the boundary of a rule. Our verification section ends by saying what it does not mean: it is about checking live systems, not about re-reading your own answer or spawning a subagent to double-check. Without that paragraph, a strong "verify everything" rule turns into expensive self-review.
  • Give the agent an honest way out. When something cannot be verified, our file tells it to label the claim "Verified" or "Confirm in account" instead of smoothing it into a confident sentence.

Config strings that reach the model are behaviour

This is the least obvious rule in our file, and it applies to anyone building agents, not only to people using Claude Code.

We ran an automated ad-buying agent for our own account. Its money limit lived in a JSON file. One field was the number the code enforced. Another field, a sentence describing the agent's objective, was fed word for word into the model's context, and that sentence also mentioned a limit. Raise the enforced number and forget the sentence, and nothing errors. The validator permits the new ceiling. The agent, reading the old sentence, limits itself to the old one.

The project file for that repository still records it:

- **`strategy/guardrails.json` is the money rail.** `budget.autonomous_ceiling_usd` is what the code enforces (`ad_push/ads_optimize.py`). Anything else in that file that states a dollar figure is prose — but `optimizer.objective` is fed verbatim into the model's context, so a stale number there silently changes what the agent does even when the rail is correct. Update every copy together.

And the general form went into the global file, under "Find the source of truth before editing":

- **A config string fed into an LLM prompt is behavior, not documentation.** A ceiling raised in the enforced field but left stale in the prompt string means the agent self-limits to the old value while the rail permits the new one. Check what reaches the model, not just what the validator enforces.

The same thinking applies to CLAUDE.md itself. It is a config string that reaches the model. A stale line in it is not harmless documentation drift. It is an instruction your agent is still following. When a deploy process changes, the file changes in the same pull request.

Keep it short

Anthropic's number is explicit: "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence." Its diagnosis of an ignored line is useful too: either the file has grown long enough that the line gets lost, or the line is a rule that cannot have exceptions and belongs in a hook.

Our global file is 107 lines. The project files run from 25 to 101. Ways to stay there:

Move path-specific rules out. A rule that only matters in one part of the codebase goes in .claude/rules/ with a paths: filter, so it loads only when Claude works on matching files. The example from the docs:

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format

Move procedures into skills. A long release procedure in CLAUDE.md weighs on every unrelated bug fix. In a skill, Claude sees only the name and description until the task calls for it. We cover that in our guide to Claude skills.

Do not count on imports. A CLAUDE.md can pull in other files with @path/to/file syntax, up to four hops deep. The docs are clear that this helps organisation and not size: imported files "load together with the CLAUDE.md that imports them".

Let the tool propose cuts. /doctor suggests trims for content Claude can derive from the codebase, and /doctor prompt-audit, on v2.1.283 or later, looks for instructions written for older models, references to files that no longer exist, and files that contradict each other. Nothing changes until you ask it to apply the edits. On paid plans, /usage will also flag an oversized instruction file as a share of your usage.

What does not belong in CLAUDE.md

Cutting is most of the work. These are the things we keep out.

  • What Claude can read. Directory layouts, dependency lists and architecture overviews. The docs list "describe your architecture and file layout in CLAUDE.md" among advice that is no longer needed, because Claude reads the repository itself.
  • Rules that must never be broken. "Never read .env" in a CLAUDE.md is followed almost every time. For the cases where almost is not enough, the docs' answer is a hook, a deny rule or a managed setting. In one client repository we backed a written git rule with a hook that refuses the commit. See Claude Code hooks.
  • Secrets and identifiers. No tokens, passwords or keys. A project file is committed and read by every session and every teammate.
  • Incident history. The file should hold the rule, not the story of the outage. Our own wording: "Write the rule, not the incident."
  • Personal preferences in a shared file. Those go in CLAUDE.local.md, added to .gitignore, or in your user file.
  • Facts about current state. "The migration is half done" is true for a week. That belongs in memory with a date, or in a ticket.

Maintaining it

A CLAUDE.md is finished the way a garden is finished. Anthropic's list of when to add a line is the right trigger set: Claude makes the same mistake a second time, a review catches something it should have known, you type the same correction you typed last session, or a new teammate would need the same context.

Our routine is small:

  1. When a session repeats a mistake, add the rule and its reason. One line, in the section it belongs to.
  2. When a process changes, change the file in the same pull request. A stale instruction is live behaviour.
  3. When two files disagree, fix the wrong one. Do not add a third line that explains the disagreement.
  4. Every so often, read the whole file as if you were new. Delete anything you would not miss. Run /doctor prompt-audit and read its findings.
  5. Check it loaded. /context all, then the Memory files list.

One last detail worth knowing: the docs say subagents load the same CLAUDE.md hierarchy as the main conversation, except the built-in Explore and Plan agents, which skip it to stay fast. If a rule must reach those, restate it when you delegate.

The takeaway. The best CLAUDE.md is the shortest one that stops your agent repeating a mistake. Write what it cannot see, put the reason beside the rule, say out loud when one file replaces another, and move anything non-negotiable into enforcement. Then keep editing, because the file is behaviour, and behaviour drifts.

We wrote more about the working habits these files support in how to use Claude Code effectively, and about the wider practice in how we use Claude Code for web development. If you want agents set up around how your business actually runs, that is our AI integration service, and you can tell us what you're working on.

Common questions

What are the CLAUDE.md best practices that matter most?

Keep it short, keep it specific, and only write what Claude cannot work out from the code. Anthropic's guidance as of November 2026 is to target under 200 lines per file and to write instructions concrete enough to verify, such as the exact test command. From our own files we would add: put the reason next to the rule, state plainly when a project rule replaces a global one, and move anything that must never be skipped into a hook, because CLAUDE.md is guidance and not enforcement.

Can you show a CLAUDE.md file example?

Anthropic's best-practices page gives a compact one with three headings: Commands, listing install, single-test and typecheck commands; Conventions, naming the error helper to use and a legacy folder not to copy; and Gotchas, noting an environment variable the integration tests need. Our own project files follow the same shape under different names: how shipping works in this repository, the rules that have caused real mistakes, and where a search for something will lead you to a dead end.

Where can I find more CLAUDE.md examples?

Start with the files you can generate yourself: run /init in a repository and Claude Code writes a starting CLAUDE.md from your codebase, which you then cut down. Anthropic's memory documentation includes examples for imports, path-scoped rules and a shared AGENTS.md. This post quotes sections of our real global file and describes three project-level files with client details removed. Treat every example as a pattern for structure, since the useful content is whatever is specific to your project.

What is the CLAUDE.md location for global and project files?

As of November 2026 the documented locations are: ~/.claude/CLAUDE.md for personal instructions across all projects; ./CLAUDE.md or ./.claude/CLAUDE.md for project instructions shared through version control; ./CLAUDE.local.md for personal, project-specific notes kept out of git; and a managed policy path set by an organisation, such as /etc/claude-code/CLAUDE.md on Linux. Files in directories above your working directory load at launch. Files in subdirectories load when Claude works with files there.

What is a CLAUDE.md file?

It is a plain markdown file that Claude Code reads at the start of every session. Because each session begins with an empty context window, the file is how standing instructions survive from one session to the next: build and test commands, conventions, and rules about how work ships. Anthropic's documentation describes it as context, not enforced configuration. Claude reads it and tries to follow it, and the more specific and concise the instructions, the more consistently it does.

What should I put in CLAUDE.md?

Anthropic's test is whether you would otherwise re-explain it. Add an entry when Claude makes the same mistake a second time, when a review catches something it should have known, or when a new teammate would need the same context. Good entries are the commands that verify work, places where the code is misleading, and decisions that were never written in the repository. Leave out the file layout, the architecture and anything else Claude can read for itself.

Does a project CLAUDE.md override the global one?

Not automatically. Anthropic's documentation says discovered files are concatenated into context instead of overriding each other, ordered so instructions closer to where you launched Claude are read last. If two files give conflicting guidance, Claude may pick one arbitrarily. So write the override in words. One of our project files says its repository has no remote, so no pull requests, and adds that this overrides the global rule to open one. That sentence removes the conflict.