Concepts

What Is CLAUDE.md? Where It Goes and How Claude Reads It

Karan KalraGrowth, Trail

CLAUDE.md is a markdown file that gives Claude Code persistent instructions for a project, a personal workflow or a whole organization. Claude Code reads CLAUDE.md at the start of every session. Published tests show that Claude follows CLAUDE.md rules reliably.

TL;DR

  • Claude rarely ignores a written CLAUDE.md rule. In 48 trials, 0 of 25 runs attempted a command banned in CLAUDE.md, against 23 of 23 runs with no written ban (source).
  • The shape of the file does not change compliance, but the length of the session does. Across 1650 sessions, file size, rule position, split files and contradicting files made no measurable difference. But every function Claude writes after reading a rule cuts the odds of following it subsequently by about 6% (source).
  • The Claude Code team keeps its own file under about 1000 tokens and deletes lines from it with every model release (source).
  • CLAUDE.md files written today quickly become redundant. A 1350-line CLAUDE.md passed 399 of 400 rule checks, but 17 of its 20 rules also passed with no file at all (source).
  • A long CLAUDE.md is a token bill. Claude injects this entire file into every single message you send. A 2000-word rule set burns over 3300 tokens per turn. To save context space, use path-scoped rules. They cost zero tokens until the model actually opens the matching file.
  • Use hooks only for what you cannot undo. Users can unintentionally talk a model into ignoring a CLAUDE.md rule (for example, user claims authorization), but the model can never bypass a hook(source).

What is a CLAUDE.md file?

A CLAUDE.md file is a plain markdown file that gives Claude Code persistent instructions for a project, a personal workflow or an organization. Claude Code loads CLAUDE.md into context at the start of every session. Claude treats CLAUDE.md as context, not enforced configuration, so it guides behavior but cannot block an action.

Anthropic's Claude Code documentation says CLAUDE.md should hold facts Claude needs in every session: build commands, conventions, project layout and "always do X" rules.

An illustrative CLAUDE.md for a small API project looks like this:

# billing-api

## Commands
- Build: `pnpm build`
- Test one file: `pnpm vitest run <path>`

## Conventions
- API handlers live in `src/api/handlers/`
- Use the `logger` module, never `console.log`

## Do not
- Do not edit files under `migrations/` by hand

Note that each line is specific enough to verify. The documentation makes the same point with its own examples: "Use 2-space indentation" works better than "Format code properly".

Does a CLAUDE.md file improve Claude's results?

A CLAUDE.md-style context file does not reliably make a coding agent more successful, but it can make the agent faster. An ETH Zurich benchmark found context files did not generally improve task success and raised inference cost by over 20%. At the same time, a separate paired study measured 29% lower median runtime with a CLAUDE.md present.

StudyWhat it measuredResult
Gloaguen et al., ETH Zurich (2026)Task success and cost across several coding agents and LLMsNo general improvement in success; inference cost up over 20% on average
Lulla et al. (2026)Runtime and token use on 124 pull requests in 10 repositoriesMedian runtime down 28.64%; output tokens down 16.58%

The ETH Zurich authors also report that agents followed the instructions in context files well, while repository overviews did not help. Both studies tested AGENTS.md-style files across agents, not CLAUDE.md alone. They are the closest controlled evidence available for CLAUDE.md, and the practical reading is the same, i.e., to write instructions and skip the overview.

Does Claude ignore CLAUDE.md?

In published tests, Claude Code rarely ignores a clearly written CLAUDE.md rule.

One experimenter ran 48 trials on Claude Code. With no written ban, 23 of 23 runs attempted the banned command. With the ban in CLAUDE.md, 0 of 25 did. File length and rule position made no difference.

A second test agrees. Mayank Kaul put 20 checkable rules in a 1,350-line CLAUDE.md and ran 30 sessions. With the file present, 399 of 400 rule checks passed, and how deep a rule sat in the file predicted nothing.

But CLAUDE.md does fail in four documented ways:

  • The user overrides it. When a prompt claimed authorization, a CLAUDE.md rule gave way in 2 of 2 runs while a hook held in 2 of 2 (Rulestack).
  • The session runs long. Both experiments used short sessions. But many users report that rules lapse in very long sessions.
  • The rule sits in a nested file. The documentation says a project-root CLAUDE.md is re-read after /compact, but nested files reload only when Claude reads files in that directory.
  • The rule is vague or contradicted. The documentation says Claude may pick arbitrarily between two conflicting instructions.

Why does Claude ignore CLAUDE.md?

Claude ignores CLAUDE.md mostly because of how the file reaches the model. Claude Code pastes CLAUDE.md into the conversation wrapped in a reminder that the content "may or may not be relevant" to the task. The model is not trained to look for the file, and the wrapper tells it the contents are optional.

HumanLayer found the wrapper by logging Claude Code's API traffic through a proxy. The reminder ends: "You should not respond to this context unless it is highly relevant to your task." Their reading is that rules which do not apply to every session get treated as not relevant and dropped. A GitHub issue asking for the wrapper to go was closed as not planned.

The practical fix follows from the wrapper. HumanLayer's CEO recommends "if X then Y" phrasing, because naming when a rule applies is what gets it past "probably ignore this". Three other writers arrived at the same pattern on their own. See how to write a rule Claude follows.

Boris Cherny, who leads Claude Code, put it this way on HN: CLAUDE.md "is not about fighting the model, rather it's giving the model a shortcut to get the context it needs to do its work."

Does the structure of a CLAUDE.md matter?

In the largest controlled test so far, nothing about the structure of a CLAUDE.md changed how often Claude followed it. What changed compliance was how much work the session had already done.

Damon McMillan ran 1650 Claude Code sessions across two TypeScript codebases and five tasks, mostly on Sonnet 4.6 with an Opus 4.6 cross-check. Then, he varied factors and measured compliance.

What variedRangeEffect on compliance
File size25 to 500 linesNone detectable
Position of the ruleTop to bottomNone detectable
One file or split across filesTwo layoutsNone detectable
A contradicting file next to itPresent or absentNone detectable

The effect he did find sits inside the session. Each function Claude generated after reading the rule cut the odds of following it by about 6%. The decline is not a straight line, and he found it during analysis rather than planning for it, but it reproduced on the second codebase and on Opus 4.6.

This agrees with the two smaller tests above and with the field reports. One HN user describes adherence as good "at the beginning and end of the conversation" and poor "during the middle where the real work is being done." Another says rules "stop influencing" after a few tens of thousands of tokens.

Our view: write the file however you like. Then keep sessions short, or re-inject the rules with a hook. The work you have already done in a session is a bigger threat to a rule than anything about the file.

How long should a CLAUDE.md be?

Boris Cherny, the Claude Code lead, gives a figure: "Try to keep it under 1k tokens or so. Ours is maybe half that size." Note that in published tests, the measurable penalty of a long CLAUDE.md was cost, not disobedience.

Practitioners' own caps run upto 2000 tokens max:

WhoCapReason given
Boris Cherny, Head of Claude CodeUnder 1,000 tokens; theirs about 500Team practice
Augment Code (vendor benchmark)100 to 150 lines plus reference filesGains "started reversing" past that
HumanLayerUnder 300 lines; their root file under 60Instruction budget, below

The spread is the point. The cost of a long file is tokens, not disobedience.

Those tokens are charged on every request, which is why a loaded CLAUDE.md is one reason a greeting can burn a chunk of your session. Rulestack measured the same rule set in four places on a fresh Claude Code session:

Where the 2,004-word rule set livesInput tokens over baseline, first request
Inline in CLAUDE.md+3,330
Imported with @path+3,442
.claude/rules/ file without paths+3,438
.claude/rules/ file with paths+0, then 2,987 on the turn that reads a matching file

Splitting a CLAUDE.md into imports does not save tokens. The documentation says the same: imported files load at launch.

In Mayank Kaul's deletion test, the same 20 rules were delivered two ways:

Full CLAUDE.mdShort CLAUDE.md plus Skill files
Length1,350 lines19 lines
Rule checks passed99 of 100100 of 100
Cost per run$1.094$0.696

The short version was about 36% cheaper per run with no loss in compliance.

Also, cut the file on every model release. Cherny's team (Head of Claude Code) does: "We remove from it with every model release since smarter models need less hand-holding." One user removed all his instructions on Opus 4.5 and found it "basically never violates those points." The reverse risk exists too. Anthropic dropped its own cyber reminders from the system prompt for Opus 4.7 because the model "tended to over-fixate on them" (source). A rule written for an older model can push a newer one too hard.

Delete from your existing CLAUDE.md files

Delete any CLAUDE.md rule that a careful reader of the repository would follow anyway. In one deletion test, 17 of 20 rules passed every check even with no CLAUDE.md, because the code already demonstrated them. The only rules that mattered were the two that contradicted what the repository showed.

That finding comes from Mayank Kaul's 30-run test of a 1,350-line CLAUDE.md. Without the file, Claude followed the conventions the repository's own changelog and history demonstrated.

Delete from CLAUDE.mdKeep in CLAUDE.mdAdd to CLAUDE.md
Directory layouts and architecture overviewsConventions that differ from what the code showsSecurity requirements
Dependency listsBuild, test and lint commandsPerformance requirements
Style rules every existing file already followsPitfalls and the reasons behind themA short list of code that looks wrong on purpose
File paths and symbol names, which rotOne-sentence constraints tied to a failure you sawALWAYS / ASK FIRST / NEVER boundaries by path
Any "don't" without a paired "do"
Rules written in anticipation of a failure

Three sources support the delete column. The ETH Zurich study found repository overviews did not help agents. An alphaXiv summary of its ablation reports generated files helped by about 2.7% only once existing documentation was removed. Claude Code's own /doctor checkup proposes trimming content Claude can derive from the codebase.

The add column comes from a study of 2,303 context files: only 14.8% specified security requirements and 14.5% specified performance.

One warning from Kaul's test: the rules worth keeping are the ones your codebase contradicts, and those are also the ones most likely to be wrong. Reconcile each one with the code before keeping it.

What each kind of content did in one vendor benchmark. Augment Code measured AGENTS.md content types on real pull requests with its own agent. Augment sells that agent, so read the figures as vendor-measured, and the post gives no sample sizes beyond "dozens" and "hundreds".

ContentMeasured effect
A six-step deployment workflowPRs missing wiring files fell from 40% to 10%; correctness up 25%; completeness up 20%
A decision table (React Query vs Zustand)best_practices up 25%
3 to 10 line snippets of real production codecode_reuse up 20%
30 or more "don't" rules on a CRUD taskThe PR "took twice as long and was 20% less complete"
A full service topology, on a two-line config changeClaude read 12 docs, loaded about 80K tokens, completeness down 25%
The same file, bug fix vs feature in one modulebest_practices up 25% on the fix; completeness down 30% on the feature

The last row is the one to remember. One file helped and hurt in the same module, depending on the task. Augment's rule from it: pair every don't with a do.

A file can look better and be worse. Stet had Codex rewrite its own AGENTS.md eight times against five training tasks. The best candidate cut input tokens from 33.9M to 23.5M on those tasks. On ten held-out tasks, correctness fell 0.20, scope discipline fell 0.49, and input tokens rose by 17.8M. Ten tasks is a small sample, and the author calls the result directional. The pattern still deserves a name: a rule that fixes the task in front of you and breaks the ones you did not test.

Why "don't" rules cost so much. One HN user explains the mechanism: "'Don't do X' leads to 'Wait, I need to make sure I didn't X'", and each pass raises the odds of X. Write "Never X. Use Y instead." A bare prohibition strands Claude when it believes it needs X.

Facts, constraints, and wishes. One user who maintained a file for six months in production sorts rules into three bins. Facts, like directories and commands, "always work". Constraints work "if each individual item doesn't exceed one sentence and describes a failure I've already observed". Behaviour rules written in anticipation of a failure "are usually not followed". Another user's summary: "zero instructions are better than wrong instructions."

Two things worth adding come from Tian Pan's post on project context. First, a list of intentional oddities: the deliberate denormalization, the excluded type-check, the hand-rolled retry. Without a line saying it is on purpose, agents "fix" it. Second, boundaries in three tiers: ALWAYS safe to modify, ASK FIRST, and NEVER modify. His filter for everything else is the competent engineer test: would a competent engineer work this out by reading the code? Then cut it.

File paths rot faster than you expect. One vendor's audit of TypeScript repositories found 10 to 84% of symbol references in AI config files were stale (source). A line like "auth logic lives in src/auth/handlers.ts" outlives the refactor, and Claude then searches the wrong place with confidence. Describe what a module does, not where it is.

How do you write a rule Claude follows?

A rule Claude follows

  • names when it applies
  • says why it exists
  • can be checked.

Few examples -

Bad exampleGood exampleWhy
Format code properlyUse 2-space indentationA script can check it
Be careful with migrationsRun pnpm db:migrate --dry-run first. Do not push until drift is reconciled.Names a command and a check
Do not use the staging database for testsDo not use the staging database for tests. It is shared with demo, and test writes broke two live demos.The reason lets Claude generalize
Never use console.logNever use console.log. Use the logger module.A "don't" without a "do" strands Claude
You work on the payments serviceDo not touch auth/, catalog/ or admin/. If a task needs them, stop and say so.Negative scope with an exit
See docs/foo.mdIf you hit FooBarError, read docs/foo.mdA trigger beats a bare pointer

Few more pointers -

  1. Name the trigger. This is the "if X then Y" pattern from the wrapper section above. Hwee-Boon Yar found that a skill without a trigger hint was ignored about half the time, and fired once the rule said when to use it. Shrivu Shankar's version for pointers: a bare @path/to/docs.md either bloats context, if imported, or gets ignored, if only named. What worked for him was "For complex Foo usage or if you encounter a FooBarError, see path/to/docs.md."

  2. Give the reason. One developer's staging-database rule, above, is from yureki_lab's six months of notes. With the reason attached, Claude worked out that reads were fine and writes were the hazard. The bare rule never said so. His line: "Reasons are compression." Another user reports that a short paragraph on why the team does TDD changed behaviour more than any rule, to the point that Claude started mutating code to watch tests go red, unprompted.

  3. Scope by what to avoid, and leave an exit. yureki_lab found that positive scope ("you work on payments") failed. Naming the sibling services to stay out of worked, but only with an exit: "If a task genuinely requires another service, stop and say so instead." Without it, "absolute boundaries get rationalized away the first time they're inconvenient."

  4. Make it checkable. Iwo Szapar's test for every line: does it change a decision or name a check? Yar measured what vague rules cost him. Without an explicit braces rule, braceless one-liners about half the time. Without "pnpm (not npm, not yarn)", npm about half the time. Those are the lines that earn their place.

  5. Settle conflicts in writing. One HN user observed that with two conflicting lines "it tends to ignore both." The documentation says the same. The single most useful line in yureki_lab's file was a tiebreaker: "If STATE.md contradicts CLAUDE.md, STATE.md wins (it's newer)."

  6. Emphasize one line, or none. The official best-practices page now says to add "IMPORTANT" to one skipped line only, because "If you emphasize many lines, none of them stands out." HN splits on whether it works at all, and the escalation loop has a documented end. Manpreet Singh tracked a timestamp rule violated 4 times in 24 days across about 150 commits. Sharpening the wording bought 11 days. A GitHub issue shows the same rule restated more forcefully after each violation and broken again each time. His count: 124 issues with "CLAUDE.md" and "ignore" in the title, 68 closed as not planned.

  7. Fix the right rule. Singh's second finding is the one we would have missed. About 900 words of "keep it simple" guidance in his file targeted how Claude talked. 17 of his 25 real corrections were about writing style. The rule was long, emphatic and aimed at the wrong thing.

Should you use /init to create CLAUDE.md?

Use /init to draft a CLAUDE.md, then cut the draft hard. Anthropic's documentation recommends /init as a starting point to refine with instructions what Claude would not discover on its own.

LLM-generated context files don't generally improve task success, so an unedited /init file only adds cost.

  1. Run /init in a Claude Code session. Claude analyzes the codebase and writes a CLAUDE.md with the build commands, test instructions and conventions it finds.
  2. Delete what Claude can derive. Remove directory layouts, architecture overviews and dependency lists. They are unhelpful.
  3. Add what Claude cannot discover. Write down conventions that differ from tool defaults, known pitfalls, and security and performance requirements.
  4. Confirm CLAUDE.md loaded. Run /context and check the list under Memory files.
  5. Ask for trims. Run /doctor, which proposes cuts to a checked-in CLAUDE.md.

Treat /init output as a list of candidates for deletion, not as a finished file. The commands and behavior above come from the Claude Code documentation.

Should a rule go in CLAUDE.md, a path-scoped rule, a skill or a hook?

Put a rule in CLAUDE.md only if it applies to every session and a mistake is reversible.

Rules the repository already demonstrates should get deleted. Rules whose failure is irreversible should go in a hook or a permission rule. Rules for certain paths or tasks should go in a path-scoped rule or a skill.

The four-question placement test for a CLAUDE.md rule:

  1. Would a careful reader of the repository already do this? Delete the rule.
  2. Is a failure irreversible? Move the rule to a hook or a permission rule. Think production data, credentials and force-pushes.
  3. Does the rule apply only to some paths or tasks? Move it to a path-scoped rule in .claude/rules/ or to a skill.
  4. Can a linter or a wrapper script express it? Then use it. It costs no context and holds every time.
  5. None of the above? The rule earns a line in CLAUDE.md.

For what a skill is and which pre-written ones might be worth installing, see our post on 49 Useful Claude Code Skills.

MechanismWhen it loadsEnforced?What was measured
CLAUDE.mdEvery sessionNo, it is context0 of 25 runs attempted a banned command; about 3,330 tokens per 2,004 words
Path-scoped ruleWhen Claude reads a matching fileNo0 tokens until a matching file is read
SkillWhen invoked or judged relevantNo19 lines plus a Skill scored 100 of 100 in one test; skills scored 53% by default in another
HookAt fixed lifecycle eventsYesBlocked every attempt in the 48-trial test

Interestingly, Jesse Vincent's Superpowers plugin shipped a SessionStart hook that ran async. It "never injects its context", and the whole system was inert with no errors (post-mortem). Asking Claude what it would do gave the right answer every time. What it did differed. His conclusion was that "Advisory language tests comprehension, while hard gates and checklists test compliance."

Another user's CLAUDE.md banned commit attribution. But a default in settings.json added it anyway (source). For anything that must hold, permissions.deny in settings outranks prose.

Should CLAUDE.md point to docs or include them?

Point to docs when the pointer says when to read them. A bare list of files gets ignored. Anything Claude needs in every session goes inline.

The pattern should be a short CLAUDE.md, an agent_docs/ folder with files like running_tests.md, and one line per file saying what it covers. "Prefer pointers to copies", with file:line references, because pasted snippets rot. Write lines like "When adding CSS, refer to: docs/ADDING_CSS.md", deliberately without @, so nothing loads until needed.

Augment's benchmark measures whether Claude actually follows the pointer -

Where the instruction livesHow often the agent found it
The AGENTS.md hierarchy100%
A file referenced from itOver 90%
A README in the working directory80% or more
A nested READMEAbout 40%
An orphan _docs/ folderUnder 10%

Augment's 90% is for references with a reason to read them. The failures are bare pointers. A pointer read at turn three is also as perishable as a rule read at turn zero, which is the within-session decay from the 1650-session study. And every pointer costs a turn, because no harness can batch the read of CLAUDE.md with the reads it asks for.

Augment also warns against more than 10 to 15 references in one file. One module had 37 related docs; removing its AGENTS.md "barely changed agent behavior" because the sprawl dominated.

Where does CLAUDE.md go and how does it load?

A project CLAUDE.md goes at ./CLAUDE.md or ./.claude/CLAUDE.md and is shared through version control. Personal instructions go in ~/.claude/CLAUDE.md, private per-project notes in ./CLAUDE.local.md, and organization policy in a managed system path. Claude Code concatenates every CLAUDE.md it finds rather than letting one override another.

ScopeLocationShared with
Managed policymacOS: /Library/Application Support/ClaudeCode/CLAUDE.md; Linux and WSL: /etc/claude-code/CLAUDE.md; Windows: C:\Program Files\ClaudeCode\CLAUDE.mdEveryone in the organization
User~/.claude/CLAUDE.mdOnly you, in all projects
Project./CLAUDE.md or ./.claude/CLAUDE.mdYour team, through source control
Local./CLAUDE.local.md, added to .gitignoreOnly you, in this project

How CLAUDE.md files load, per the Claude Code documentation:

  • Upward at launch. Claude Code loads CLAUDE.md and CLAUDE.local.md from the working directory and every directory above it.
  • Downward on demand. A CLAUDE.md in a subdirectory loads only when Claude reads files in that subdirectory.
  • Closest last. Files nearer the working directory appear later in context, and CLAUDE.local.md is appended after CLAUDE.md at each level.
  • Imports expand at launch. @path/to/file imports load with the CLAUDE.md that references them, to a maximum depth of four hops.
  • Comments are free. Block-level HTML comments are stripped before CLAUDE.md enters context.

To verify which CLAUDE.md files loaded, run /context and read the list under Memory files.

In a monorepo, nest by what loads together. Thorsten Ball's advice from his Laracon talk: "litter them around your codebase, you can leave like trails for the agent." His Storybook folder's file holds the URL, the port and the verification steps. Nothing else.

Blake Crosley's rule for when to split: extract a block when it passes 20 to 30 lines and some sessions do not need it. iOS rules should not load in a web session. His monolithic file cost about 4000 tokens a session. The root is now about 800.

Shankar's monorepo uses a budget. A tool gets a section only if 30% or more of engineers use it, and each team gets a token allowance, "almost like selling ad space to teams". His observation from it: "Keeping your CLAUDE.md as short as possible is a fantastic forcing function for simplifying your codebase."

How do you maintain CLAUDE.md over time?

Add a line after a failure you saw, check that the line changes behaviour, and delete on a schedule. The Claude Code team adds to its file "multiple times a week" and cuts it on every model release.

Add after a failure, then verify. Cherny's rule for what goes in: "If there is anything Claude tends to repeatedly get wrong, not understand, or spend lots of tokens on, put it in your CLAUDE.md." Pamela Fox adds the check. After writing the line, revert the change, rerun the task, and see if the output improved (source). Chris Jones's version: "A good rule is a scar." Every rule in his global file traces to something that went wrong at least twice. He started empty.

Two strikes before a line. Remy's workflow: the first time something goes wrong, log it to a memory file as "observed X". The second time, promote it to CLAUDE.md. "Twice = pattern. Once = noise."

Delete on a schedule, not on a failure. yureki_lab runs a 15-minute pass each month and asks three questions of every line: still true? violated recently? added in anger? His file shrank four months running, from over 400 lines to about 80, and "behavior improved each time." Anthropic's own guidance for large codebases expects "a meaningful configuration review every three to six months." Alex Dunlop caps his file and makes every addition evict a line.

Prune by experiment. Yar's method: remove one rule, rerun a few representative tasks from the same repository state, and restore the rule if behaviour regresses. He never prunes safety, auth or payment rules this way. This is the testing procedure above, pointed at deletion.

Let Claude propose edits at the end of a session. One HN user's closing prompt: "Update AGENTS.md only if you learned a durable, generalizable lesson. If nothing durable was learned, no changes are needed." Another's standing rule: "When I tell you to do something more than once, add a rule to Claude.md." And when Claude ignores a rule, ask it why. One user reports the answer "often provides very useful feedback to adjust the rules."

Keep "always true" apart from "true right now". A status line like "We are currently migrating the auth module" outlived the migration in yureki_lab's file, and Claude kept acting on it. Volatile state goes in a separate file updated every session, with the tiebreaker line from the rule-writing section.

Keep personal preferences out of the team file. At one HN user's company, personal habits like gitignored scratch directories ended up "encoded in a whole-team doc" (source). The fix is one shared line: "Never edit CLAUDE.md. Write user preferences to CLAUDE.local.md." Another user's warning on scale: a bad shared file in a repo with 100 engineers makes "every agent for every engineer worse, without anyone really noticing."

Review it like code. The official page now says to treat CLAUDE.md like code: review it when things go wrong, prune it regularly, and test changes by watching whether behaviour shifts. The failure mode is the opposite, a file "treated like a lock file where everyone is scared to touch it."

Treat it as an attack surface. Rohit Ghumare recommends linting the file for invisible Unicode, after Pillar Security's hidden-directive demo, and notes NVIDIA's proof of concept of a dependency dropping a malicious AGENTS.md into a repo. "Treat AGENTS.md with the same suspicion you give a shell script that a package wants to run."

What is the difference between CLAUDE.md and AGENTS.md?

CLAUDE.md is Claude Code's own instruction file; AGENTS.md is the cross-tool equivalent. Claude Code reads both, but by default it reads AGENTS.md only when no CLAUDE.md or CLAUDE.local.md exists in the working directory or above it. Reading AGENTS.md directly requires Claude Code v2.1.277 or later.

Your repository hasClaude Code reads
AGENTS.md and no CLAUDE.md or CLAUDE.local.mdAGENTS.md
AGENTS.md and a CLAUDE.md or CLAUDE.local.mdThe CLAUDE.md files only
A CLAUDE.md that imports AGENTS.mdCLAUDE.md, with AGENTS.md included through the import

Three details from the Claude Code documentation catch teams out:

  • CLAUDE.local.md switches AGENTS.md off. Adding a personal CLAUDE.local.md to a project that relies on AGENTS.md stops Claude reading AGENTS.md, unless Project instructions is set to claude-md-and-agents-md in /config.
  • One shared file needs one line. A CLAUDE.md containing @AGENTS.md keeps AGENTS.md as the single source for every tool, with Claude-specific instructions below the import.
  • Symlinks break on Windows. ln -s AGENTS.md CLAUDE.md works on macOS and Linux, but the documentation recommends the import when anyone on the team uses Windows.

Claude Code took a year to read AGENTS.md at all. Thariq from the Claude Code team explained why: "we don't think that model families are interchangeable and the system prompt can have a big impact on performance." One HN user's practical version: an AGENTS.md tuned for Codex is not the same file as a CLAUDE.md tuned for Claude. When the fallback shipped, it only worked with telemetry on for a few days. A rollout flag caused it, fixed in v2.1.281 (source).

One more difference for teams on both tools. Claude Code concatenates every file it finds, closest last. The agents.md spec says the nearest file takes precedence. The same tree can give different effective instructions in each tool.

How do you test your own CLAUDE.md?

To test a CLAUDE.md, run the same task several times with and without one rule, and count the outcomes with a script. Published experimenters used three to five runs per condition, a deterministic checker, and a repository where CLAUDE.md never existed in git history.

  1. Pick checkable rules. Choose rules whose outcome a script can verify from the file tree or the command log, such as "never use sed".
  2. Build a clean baseline. Use a repository where CLAUDE.md was never committed. In Kaul's test, 10 of 10 runs recovered a deleted CLAUDE.md from git history.
  3. Close the other channels. Remove memory plugins and turn off auto memory with CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. Both leaked rules into Kaul's first attempt.
  4. Observe every condition. Run the same logging hook in all arms. Without it, zero violations and nothing watching look identical.
  5. Repeat each condition. Run at least three to five sessions per arm. One experimenter nearly published a wrong result from a single run.
  6. Change one thing at a time. The cleanest comparison in the 48-trial test differed by exactly four lines of CLAUDE.md.

Record the Claude Code version with every result. The author of the 48-trial test warns that a new model generation could move every number.

Frequently asked questions about CLAUDE.md

Does CLAUDE.md survive /compact? A project-root CLAUDE.md survives compaction. After /compact, Claude Code re-reads the project-root CLAUDE.md from disk and re-injects it. Nested CLAUDE.md files reload only when Claude next reads a file in their directory.

Should CLAUDE.md be committed to git? Commit the project CLAUDE.md so the whole team shares it. Keep personal notes in CLAUDE.local.md and add that file to .gitignore.

Is there a size limit for CLAUDE.md? Claude Code loads a CLAUDE.md of up to 4 MiB in full and skips a larger file. The recommended target is under 200 lines per file.

Is CLAUDE.md part of the system prompt? No. Claude Code delivers CLAUDE.md as a user message after the system prompt. For system-prompt-level instructions, use the --append-system-prompt flag.

Can Claude audit a CLAUDE.md automatically? Yes. /doctor prompt-audit reports outdated, missing-reference and conflicting instructions, and changes nothing until asked. It requires Claude Code v2.1.283 or later.

How do you check that CLAUDE.md loaded? Run /context in a session and look for the file under Memory files. If CLAUDE.md is missing from that list, Claude cannot see it.

Is CLAUDE.md cached? Yes. It sits in the prompt prefix Claude Code caches, so after the first request its tokens bill as cache reads. Boris Cherny describes the main agent using a one-hour cache and subagents a five-minute one. Editing CLAUDE.md mid-session changes the prefix and invalidates the cache for the whole conversation. If Claude updates the file for you, let it do so at the end of a session.

How do you know Claude is still following CLAUDE.md late in a session? You mostly cannot tell from the output. Some users add a canary, like a rule to address them by a nonsense name, and treat its absence as a warning. The canary only shows the file loaded. One user notes Claude "can send the emoji while still ignoring more important rules." The 1,650-session study found compliance falls with every function written, so the fix is a shorter session or a hook that re-injects the rules.

Which wins, CLAUDE.md or settings.json? settings.json. A permission deny or a default in settings overrides a prose rule. Put anything irreversible there.

Should auto memory stay on alongside CLAUDE.md? Watch it. One user turned auto memory off because it stored "severely wrong statements that then would confuse it later." Another found Claude "seems to lean on memory more than updating CLAUDE.md." The testing section above turns it off for that reason.

Should you regenerate CLAUDE.md for a new model? Delete from it. Do not regenerate it. Newer models need fewer rules, and a rule written for an older model can make a newer one over-fixate.

Share

See the mechanism
on your own documents.

Point Trail at the policy, SOP, agreement that decides your work, and watch it build an agent using rules traced back to the text they came from.