Most teams that adopt Claude Code hit the same wall around week three. Two or three engineers are getting strong results, everyone else is getting code that compiles but ignores house conventions, and the gap keeps widening. The difference is rarely prompting skill. It is almost always the standing context file: CLAUDE.md.
CLAUDE.md is the file Claude Code reads at the start of every session. Build commands, architecture notes, naming rules, boundaries. A good one is the difference between an assistant that guesses and one that knows your stack. This post covers the CLAUDE.md practices we apply in structured Claude Code rollouts with Australian engineering teams.
Why CLAUDE.md decides rollout quality
Claude Code is agentic. It plans multi-step changes, runs tests, fixes failures, and edits across a whole codebase. Every one of those decisions draws on context, and CLAUDE.md is the only context guaranteed to be present in every session, for every engineer, on every task. Individual prompts vary wildly from person to person. The standing file does not, which makes it the cheapest consistency lever a team has.
Teams that treat the file as an afterthought get inconsistent output and blame the tool. Teams that treat it as a maintained engineering document get output that reads like it came from someone who has worked in the codebase for six months.
What belongs in a team CLAUDE.md
Five categories cover almost everything worth writing down:
Commands. Build, test, lint and run, with the exact flags your team uses. If the test suite needs a database container running first, say so. Claude will otherwise discover this the slow way, on your token bill.
An architecture map. Route groups, key modules, where requests enter and where the bodies are buried. Three or four sentences per area beats a diagram nobody updates.
Conventions. Naming, error handling, comment policy, commit style. Only the rules a linter cannot enforce.
Boundaries. Files and directories Claude must not touch: generated code, migrations that have shipped, secrets, vendored dependencies. This is the section that prevents the incidents people tweet about.
Gotchas. The non-obvious things that burn an afternoon. The flaky test that fails on Mondays, the env var that must be set locally but never in CI. Written down once, they stop being tribal knowledge.
What to leave out
A CLAUDE.md fails in two directions, and the bloated failure is more common than the empty one. Leave out:
Anything that changes weekly. Sprint priorities, current ticket numbers, who owns what this quarter. Stale context is worse than no context because the model trusts it.
Long style guides better enforced by tooling. If ESLint or RuboCop can catch it, configure the linter and delete the paragraph.
Duplicates of what the model can read from the code itself. Claude can see your folder structure and your package.json. Describe intent, not inventory.
Patterns that hold up in production
After running Claude Code across our own work and client codebases, four habits separate the files that keep earning their place from the ones that rot:
Keep it under a few hundred lines. Attention is finite; a 2,000-line file dilutes every instruction in it. If you are over budget, cut the weakest section, not the font size.
Write why, not just what. The reasoning behind a rule transfers to situations the rule never anticipated. A bare rule does not.
Review CLAUDE.md changes in pull requests, like code. It effectively is code: it shapes every change the tool makes after it merges.
In monorepos, prefer per-package files over one giant root file. Claude Code reads the nearest file for the area it is working in, so scoped context stays relevant and short.
The cost of not writing it down
The economics are blunt. Take a Sydney team of 12 engineers at typical Australian rates. If each engineer spends even 30 minutes a day re-explaining context to AI tooling, restating the build commands, re-describing the architecture, correcting convention misses in review, that is roughly $40,000 a year in payroll time spent saying the same things over and over. A maintained CLAUDE.md removes most of that, and it costs an afternoon to write and minutes a week to keep current.
The same logic scales down. A four-person startup in Brisbane loses proportionally more, because there is no slack to absorb the waste.
Start with one honest afternoon
You do not need a working group. Put one senior engineer in a room for an afternoon with the five categories above and a hard 300-line budget. Ship the first version, then let pull requests improve it the way they improve everything else. Within a fortnight the file reflects how the team actually works rather than how anyone wishes it did.
If you want a second pair of eyes, this is exactly the kind of artefact our Claude consultancy in Sydney produces during a rollout: every engagement ships with written conventions your team owns outright. Our AI readiness assessment includes a review of your existing context files if you already have them.
Wondering what a good CLAUDE.md would look like for your codebase? Book a brainstorming call and bring your messiest repo.
