Why does our team's CLAUDE.md keep growing while agents still miss what we decided?
By Soumen Sarkar · October 2026
Short answer: Because CLAUDE.md is being used for two jobs: stable instructions, and the team's running decisions. Every session reads the whole file whatever it's working on, and new decisions reach it only when someone edits it. Keep CLAUDE.md short and stable, and give decisions a live, per-area home that sessions are briefed from.
How does a CLAUDE.md get this way?
It starts small: how to run the tests, which folders not to touch, the house style. Then an agent does something the team didn't want, and someone adds a line so it won't happen again. A decision is made in a meeting, and someone adds a line. Months later the file is long, half of it is about one corner of the code, and some lines contradict newer decisions nobody went back to remove.
Two things then go wrong:
- Every session reads every line, whatever it's working on. A session fixing a typo in the docs carries the billing rules; a session in billing has to find its three relevant lines among dozens.
- New decisions arrive late. A call made in a session at 10am isn't in the file until someone edits it, so the session that starts at 11am doesn't know.
Anthropic's own docs describe CLAUDE.md as context, not enforced configuration. A long file of mixed instructions and history is the hardest kind of context to follow.
What belongs in the file, and what doesn't?
Keep in CLAUDE.md what's true for every session and rarely changes: build and test commands, conventions, boundaries, and one line saying where the team's live decisions are.
Move out what belongs to one part of the code, or changes week to week: decisions with their reasons, what's being changed right now, what was tried and dropped, and assumptions waiting for an answer.
Where do the decisions go instead?
Somewhere they're recorded as they're made and given to the session that needs them, in the area it's working in:
- Record a decision when it's made, in the session or the meeting, with its reason. See decision.
- Brief by area. The first time a session reads or edits a part of the code, it gets the decisions for that part. See area brief.
- Let the newest call win. A decision that replaces an older one marks it as superseded, so nobody follows both.
Campfyrr does all three for Claude Code teams, as a plugin. Your CLAUDE.md goes back to being short. See shared team memory for Claude Code, or where should a team's decisions live so every agent finds them?
Words used here
- Decision: A decision is a call made in the work, recorded with its reason at the moment it is made, so it travels to everyone who touches the same ground.
- Area brief: An area brief is what a person or agent is told the first time they touch a part of the code: what's changing there now, what was decided, and what was tried.
- Superseded: Superseded describes a decision or rule that a later one has replaced: it no longer stands, but it is kept with what replaced it and why.
The principle behind this: Decide by doing: Our decisions live in what we do, not in what we say.
Move as one at agent speed. Nobody waits. Add Campfyrr to Claude: it briefs every agent before it touches the code, keeps assumptions and handoffs where the team can see them, and never takes your code (what it keeps).