Claude Code can work brilliantly in one session and go in circles in the next. The model may be the same; the briefing is not. A well-curated CLAUDE.md often explains the difference.
What CLAUDE.md Is
CLAUDE.md is a markdown file that contains instructions and context relevant to your project. Claude Code reads it at the start of every session. Think of it as the briefing document you’d give a new team member on their first day, except this team member has amnesia and needs the briefing every single morning.
You can generate a starting file by running /init on a new project. Claude will read your README, scan source files, and produce an initial CLAUDE.md.
Treat the generated file as a draft. Read it immediately, and delete anything the agent can discover cheaply from the repository.
The Case Against Auto-Generated Context Files
Addy Osmani (a name most web developers will recognise) published in February 2026 an analysis on some papers that I think Claude Code users should read. The core thesis: auto-generated AGENTS.md files from /init hurt agent performance and inflate costs by roughly 20%.
The research backing this is solid. An ETH Zurich study tested four agents across SWE-bench and custom benchmarks. LLM-generated context files reduced task success by 2–3% while increasing cost by over 20%. Developer-written files improved success by about 4%, but also increased cost by up to 19%. A separate study by Lulla et al. found that human-authored AGENTS.md files reduced median wall-clock runtime by nearly 29% and output token consumption by about 17%. Though that study measured efficiency, not correctness.
The critical finding from ETH Zurich was when they stripped all documentation from repos and then tested with LLM-generated context files. Those files improved performance by 2.7%. The auto-generated content isn’t useless; it’s redundant. The agent could discover all of it by reading the repo. Handing it the same information twice adds noise.
Human-written files perform better because they contain things the agent genuinely cannot discover on its own.
The Minimalism Principle
Every line in your CLAUDE.md must pass one test: can the agent discover this on its own by reading the code?
If yes, delete it.
Here are some examples of things that should be in your CLAUDE.md:
- “
uvfor package management instead ofpip” to fight the default tendency of the models to usepip. Operationally significant to avoid the model wasting tokens rediscovering you useuv, notpip. - “Always run tests with
--no-cacheor you’ll get false positives from fixture setup” to ensure the model doesn’t try to fix non-existent failures. - “The auth module uses a custom middleware pattern; do not refactor to standard Express middleware” to avoid Claude assuming you use a common library and rewriting things.
- “The
legacy/directory is deprecated but imported by three production modules; don’t delete anything in it” to avoid dead-code cleanup removing this important package.
Here are examples of things you may see in many CLAUDE.md files that should usually stay out:
- “This project uses a monorepo structure with packages in /packages.” The agent finds this in the first directory listing.
- “The following commands are used to run tests, linting, etc” Claude can read your
package.json(or equivalent) and knows how to run tests in most programming languages.
Long context files can become compliance checklists instead of useful guidance. I made this mistake myself, growing elaborate CLAUDE.md files every time the agent disappointed me. The ETH Zurich study found that generated context files could reduce task success while developer-written files produced a modest improvement at additional cost. It does not establish a universal line limit. Osmani’s analysis offers the more useful filter: keep information the agent cannot discover from the repository, and remove the rest.
The Hierarchy
CLAUDE.md isn’t a single file. It’s a hierarchy of files with the same name:
Global (~/.claude/CLAUDE.md): Loaded in every session, regardless of project. Keep this extremely short: personal preferences, working style, and an index of reference files. In her description of a three-layer context system, which I’ll discuss in the next chapter, Teresa Torres keeps her global file to just a few lines. Her reasoning is worth internalising: “If I’m using Claude to brainstorm Christmas gifts for my husband, Claude does not need to know about Product Talk.”
Project (CLAUDE.md in your repo root): Project-specific details. Architecture decisions the agent can’t discover, known gotchas, bash commands that should be run after a task.
Subdirectory (CLAUDE.md in subdirectories): Loaded lazily when Claude accesses that directory. Useful for folder-specific rules like an integration testing folder with its own conventions, for example. Just beware, these are the files that tend to duplicate most of the details that the agent can discover by itself.
Claude Code recurses up from the current working directory to root, loading CLAUDE.md files found along the way. Subtree files are loaded only when Claude enters those directories. This also means that the context receives all this content, another reason to keep it short and restricted to things the model can’t find. Three big files can start cluttering your context window with details that are redundant for the agent.
What to Actually Put in CLAUDE.md
Based on months of iteration and the collective experience of the community, here’s what consistently helps:
Non-standard commands. The exact commands to run — cargo clippy, pnpm lint, ruff check — if they are not discoverable, because they are not the standard. The ETH Zurich data backs this up: when a developer-written file mentioned uv, agents used it 1.6 times per task on average; when not mentioned, fewer than 0.01 times as it defaulted to pip.
Steps on task completion. What Claude should do when it thinks it’s done: run tests, run the linter, check types. Having a single executable (like runAll.sh) that executes all these steps in sequence (returning any errors found) helps, as it is a single entry for the CLAUDE.md that ensures no step is missed.
Files Claude should NOT read. Large doc folders, generated files, vendor directories. Saves context.
How to read logs. If you have a combined logging setup, tell Claude how to access the last 20 lines. Better yet: set up a tail-logs command.
Non-obvious conventions. Anything that would trip up a new team member who’s good but doesn’t know your codebase.
Workflows with Graphviz/dot. dot is a graph notation that Claude is particularly good at following. Less ambiguous than prose for describing workflows.
Team Practices
Boris Cherny, creator of Claude Code and Staff Engineer at Anthropic, shared how his team uses CLAUDE.md in a series of posts about his workflow (aggregated at howborisusesclaudecode.com). One example:
Our team shares a single CLAUDE.md for the Claude Code repo. We check it into git, and the whole team contributes multiple times a week. Anytime we see Claude do something incorrectly we add it to the CLAUDE.md, so Claude knows not to do it next time.
This is compounding engineering: each useful correction improves future sessions for every team member. The CLAUDE.md becomes part of the team’s accumulated operational memory.
Let’s say that during review, someone spots an anti-pattern and adds it to CLAUDE.md as part of the PR. The example he gives is never use enums, always prefer literal unions. Recording the correction may reduce recurrence across the team. If the rule must be enforced, put it in a linter or another executable check rather than relying on future sessions to remember it.
CLAUDE.md as Forcing Function
Your CLAUDE.md can also be an indicator of the health of your codebase and processes.
If your CLAUDE.md instructions are getting complex, with too many steps, that’s a signal to simplify the tools, not expand the documentation. Provide scripts that run those steps at once, in a single execution.
If models are struggling to find something in the codebase, it may be in the wrong place. The codebase structure itself is the primary documentation: fix the structure rather than adding more CLAUDE.md instructions.
If agents can’t use a tool, the tool may be the wrong fit. Find an alternative. Giving agents the tools to unblock themselves is more useful than adding workarounds to CLAUDE.md.
Think of CLAUDE.md as a diagnostic tool. Every line signals something in the codebase confusing enough to trip an AI agent, which means it probably trips human contributors too. The right response is to fix the actual problem, not grow the context file.
Martin Fowler made this point directly in a February 2026 blog fragment, titling one section “The Venn Diagram of Developer Experience and Agent Experience is a circle.” The practices that make a codebase easier for humans to read — clear modularity, descriptive naming, well-organised directories — are the same practices that make it easier for agents. Every time you fix a CLAUDE.md instruction by improving the codebase instead, you’re simultaneously improving both the human and agent experience.
The code might work while both humans and agents struggle to understand it. In that case the durable fix is often a clearer codebase, not another instruction.
The ideal CLAUDE.md is nearly empty, not because you haven’t invested in it, but because you’ve fixed the underlying issues it was compensating for.
Getting Started
If you’re starting from scratch, my recommendation: begin with a nearly empty CLAUDE.md containing one instruction: “If you encounter something surprising or confusing in this project, flag it as a comment.” Run a few sessions. See what Claude flags. Fix what you can in the codebase. Add the rest to CLAUDE.md.
Invest in curating this file as you would any other piece of developer tooling. Keep the instructions that prevent real mistakes, and remove the ones the repository has made redundant.