Writing a CLAUDE.md That Actually Gets Read
Two lookalike config files, opposite reading order, and one very fixable mistake — burying the instruction that mattered on line 300
Two files that look the same and aren't
Drop a markdown file called CLAUDE.md at the root of a repo, and it looks exactly like a file called AGENTS.md — plain prose, some headings, a few bullet lists of rules. They read the same to a human. They do not behave the same to the tools that consume them.
CLAUDE.md is read by Claude Code. AGENTS.md is a convention started by OpenAI Codex and since adopted by several other tools as a cross-agent standard. Different files, different discovery rules, different failure modes when you get the structure wrong. This module is about the one you actually use every day: CLAUDE.md — where it lives, what belongs at each level, and the specific mistakes that make an agent quietly ignore instructions you were sure you'd given it.
Claude Code discovers CLAUDE.md by walking up the directory tree from wherever you launched it — your current folder, then its parent, all the way to your home directory. Every level it passes adds instructions on top of the last. Get the level wrong, and either everyone on the team inherits your personal habits, or your personal habits never load at all.
Three files, three scopes
"CLAUDE.md" isn't one file — it's a pattern that can appear at three different levels, each with a different audience and a different set of rules for what belongs there.
~/.claude/CLAUDE.md — global, personal
Loads into every project you touch, on this machine, under your account. This is where identity, standing communication style, notification routing, and cross-project habits belong — anything true no matter what codebase you're in.
./CLAUDE.md — project, shared
Lives at the repo root (or a subfolder for a nested project), gets committed to git, and every teammate's agent reads it. Build commands, test commands, architecture decisions, naming conventions, the one thing about this specific codebase a fresh agent would otherwise get wrong.
./CLAUDE.local.md — project, personal
Same folder as the project file, but gitignored by default. Your own paths, your own environment quirks, your own preferences for this one repo — things that would be noise to a teammate reading the shared file.
Ask: "would this be true and useful in a completely different project?" Yes → global. "Would a teammate cloning this repo need to know it too?" Yes → project, committed. Neither → your local, gitignored file.
Good content vs. content that doesn't belong
The most common failure isn't putting a rule in the wrong file — it's putting too much in any file. A CLAUDE.md is context that gets loaded on every single turn. Every line in it costs tokens whether or not that turn ever needed it.
"Run tests with npm test, lint with npm run lint." Precise, short, unambiguous — the kind of thing an agent would otherwise have to guess or discover by trial and error.
"Auth is handled by a shared module, never inline" — a real architectural constraint a fresh agent has no way to infer from the code alone. One line, high value.
"Deployment tokens: see docs/deployment-tokens.md." Load the detail on demand instead of inlining a whole reference doc that's rarely needed.
Dumping architecture docs "just in case" bloats every single turn's context with material that's usually irrelevant to the task at hand.
"I like tabs, not spaces" belongs in your gitignored local file — not the committed one every teammate's agent also has to load.
No API keys, tokens, or credentials in any of these files — global, project, or local. All three can end up committed, synced, or read by a process you didn't expect. Store a pointer to where the secret lives, never the value.
Why "keep it short" isn't just tidiness advice
Anthropic's own guidance for Claude Code is to keep a project CLAUDE.md under roughly 200 lines. That number isn't arbitrary style preference — it's a direct consequence of how a
context window
works.
50 lines → read in full, every time
200 lines → soft cap, still reliable
400+ lines→ buried instructions get skippedA short file gets read carefully because there isn't much to skim.
Past a few hundred lines, an instruction sitting at line 300 competes with everything above it for the model's attention.
The failure mode isn't a crash — it's silent. The agent just doesn't apply the rule you were sure you'd written down.
The fix isn't "explain it more" — it's cut the file down to what's actually load-bearing, and point elsewhere for the rest.
Keep a short "Documentation" section at the bottom of CLAUDE.md that's just a list of pointers to detail docs (docs/code-standards.md, docs/deployment-tokens.md, etc.) instead of inlining that content. The agent reads the pointer, and only opens the linked file when the task actually needs it. Same information available, none of it costing tokens on turns that don't need it.
What a buried instruction actually looks like
This isn't hypothetical. Here's the same rule, written into two files of different lengths, producing two different outcomes on the same task.
Nothing above is the agent being careless. A 300-line file that mixes standing architecture rules with one-off migration notes from a project that finished last year is genuinely hard to weight correctly. Prune the stale material, and the rule that matters today stops competing with noise that doesn't.
If your team also runs a Codex-style tool
AGENTS.md
is a separate convention, read by different tools, with its own discovery rule — it walks down from the repo root toward wherever you're standing, the opposite direction from CLAUDE.md. If your team runs both kinds of tools, don't maintain two diverging rulebooks. Pick one canonical file and make the other a thin adapter: a short @AGENTS.md import at the top of CLAUDE.md, followed only by whatever is Claude-specific.
Just use CLAUDE.md at the three levels above. Nothing else needed.
Make one file canonical, import it into the other (@AGENTS.md syntax), and keep Claude-specific additions clearly separated below the import.
This lesson is distilled from a company blog post (blink.new) that ends with a pitch for its own hosting product — that promotional half is skipped entirely here since it has nothing to do with how CLAUDE.md works. The Claude Code specifics above (three file locations, walk-up discovery, the 200-line guidance, the @import syntax, "never put secrets in these files") match Anthropic's own documented behavior. The Codex-side details the source cited — its exact global path, a 32 KiB size limit, an override filename — are reported by that one blog post and were not independently cross-checked against OpenAI's own docs, so treat those specific numbers as "as reported," not confirmed.
Check yourself
Three questions on scope and structure.
You want Claude Code to always use a local test database path that only exists on your machine, just for this one project.
Where should that instruction go?
A 400-line project CLAUDE.md has a real rule at line 320. The agent doesn't follow it and instead copies a pattern from nearby code.
What's actually going on?
A teammate insists CLAUDE.md and AGENTS.md are basically the same thing with different names.
What's the one structural fact that proves they aren't?
Open your own project's CLAUDE.md right now and count the lines. If it's past 200, find the section that's turned into a dumping ground — old migration notes, a doc that duplicates something else, a rule nobody's touched in months — and cut it down to a one-line pointer. The goal isn't a shorter file for its own sake; it's making sure the rule that actually matters today isn't buried under one that stopped mattering last quarter.