A CLAUDE.md file is the standing brief Claude Code reads before it does anything in your repository. Used well it removes the need to re-explain your conventions in every session. Used badly it becomes a dumping ground that makes every response slower and none of them better. The difference is almost entirely about what you leave out.
What belongs in it
The test is simple: would a capable contractor need to be told this, and would they be unable to work it out from the code in front of them? If both are true, it belongs. If either is false, it does not.
Commands that are not obvious: how to run the tests, how to build, how to start the dev server
Conventions the code does not enforce: naming patterns, where new modules go, what gets committed
Hard constraints: systems not to touch, migrations not to run, environments that are production
Known traps: the flaky test, the service that needs a specific auth flow, the directory that looks unused and is not
Those last two categories carry the most weight per line. A single sentence warning that a directory is generated and should never be edited by hand saves an entire wasted session, and no amount of reading the code reveals it.
What does not belong
The most common failure is treating it as documentation. It is not documentation, it is a briefing note, and every line that restates something visible in the code is costing you attention on every single request.
Descriptions of the folder structure, which Claude can see directly
Explanations of what well-named functions do
Changelogs and records of past fixes, which belong in version control history
Generic engineering advice, which the model already has and did not need repeating
Anything secret: keys, tokens and credentials never belong in a file like this
A CLAUDE.md that has grown past a page or two is usually carrying a lot of this. Deleting half of it typically improves results, which is a counterintuitive enough outcome that most teams have to try it before they believe it.
Write instructions, not prose
The file works best as directives rather than description. "Always run the linter before committing" is actionable. "This project values code quality" is not, and will be politely ignored because there is nothing to act on.
Be specific about the negative cases too. If there is something that looks like a reasonable idea and is actually forbidden, say so explicitly, because the model will otherwise reach the reasonable conclusion. Prohibitions are cheaper to write than the cleanup after they are discovered the hard way.
Keeping it honest over time
The failure mode of any standing instruction file is staleness. A file describing a build command you changed in March is worse than an empty one, because it produces confident wrong behaviour rather than a question.
Treat it as code: it lives in the repository, changes go through review, and when someone changes the build process the same pull request updates the file. A quarterly read-through catches the rest. If nobody has touched it in a year on an active project, assume most of it is wrong.
What it is worth getting right
This sounds like housekeeping and it is, but the cost of skipping it is measurable. A developer on a fully loaded $160,000 a year who loses two hours a week to re-explaining context or unpicking work that ignored a convention is costing roughly $8,000 a year, and that is per person.
Across a team of five that is real money spent on a problem a one-page file mostly solves. The reason it goes unwritten is not cost, it is that nobody is assigned to write it.
Scope: one file or several
On a large codebase a single file gets unwieldy and generic. Directory-level files that carry conventions specific to that part of the system usually work better, with the top-level file kept short and covering only what applies everywhere.
The rule of thumb is that instructions should live as close to the code they govern as possible. A rule about the payments module is more likely to be followed, and far more likely to be updated, if it sits with the payments module.
What not to conclude
A good CLAUDE.md does not make Claude Code understand your architecture, and it does not remove the need to review the changes it makes. It reduces the number of avoidable mistakes and the amount of context you retype, which is worth a great deal on a codebase you work in daily and almost nothing on one you touch twice a year.
Australian teams working under any kind of audit obligation should also treat it as a record: what it says about production constraints is effectively a control, and worth being able to point at when someone asks how the guardrails were communicated.
If your team is rolling out Claude Code and wants the conventions written down properly, book a short call and we will look at what is worth documenting first.
