When Claude gets something wrong, most people react the same way. They add another instruction. Then another. A few weeks later the project's instruction file is several hundred lines long, and the output is no better. Often the output is worse.
I spend a large part of my training on this habit, because the instinct to add more is so strong. The model works with whatever it has been given. If what it has been given is noisy, stale or crowded, you get noisy, stale or crowded work back. The skill worth building is deciding what the model knows when it answers. That practice has a name, context engineering, and it matters more for teams than for individuals, because a team's instruction file shapes everybody's work at once.
A warm-up about pink elephants
I open the first kick-off session with a small demonstration in an ordinary browser chat. I have a long back-and-forth about pink elephants. Then, in the same chat, I ask: "Create a logo for a furniture business."
Before I press enter, I ask the group to predict what comes back and why. The conversation is carrying residue from everything that came before it, and the model uses that residue.
The lesson is simple. A fresh task often needs fresh context. Later in the same session, once everyone is inside Claude Code, I show the fix: /clear starts a clean conversation, and /compact trims the old one down and keeps going.
An index card shows how limited the context window is
The second exercise uses paper. Each person takes an index card, which stands in for the model's context window, the limited space holding everything it can see while it answers.
Before writing any task on it, they colour in strips for what is already on the card:
- The system prompt.
- Memories and anything carried over from earlier sessions.
- Skills, agents and other capabilities Claude has loaded.
Only then do they write their actual request in whatever space is left. People see the point quickly: the model never starts from an empty card. The useful questions are what is already on the card, what still fits, and what should be removed or made clearer.
Claude Code lets you look at the real context window. Type /context and it shows how the space is being used: system prompt, tools, skills, memory, messages and free space. The percentage in the status line shows how full the context window is.
The goal is the right context for the task: relevant, current and useful.
What CLAUDE.md is for
CLAUDE.md is a plain text file in your project that Claude Code reads at the start of every session. Whatever you put in it, Claude sees on every task, whether that task needs it or not.
Because Claude sees every line on every task, I treat CLAUDE.md as the project's ground rules. The file should hold the small set of things almost every task needs:
- what the project is for;
- the critical architecture or domain context;
- build, test and run commands that someone has actually checked;
- the essential conventions;
- what "done" means;
- permission to challenge instructions that are unclear;
- links to deeper reference material, so Claude can find detail when it needs it.
The failure I watch for most is a file that has quietly become a store for everything anyone ever learned about the project. Feature notes, folder-specific quirks, one person's preferences, last month's temporary workaround. Each line was true when somebody wrote it. Together those lines bury the rules that matter.
Why more rules can mean less compliance
In the masterclass session on context engineering, I ask one question at the start: what harm can a true but irrelevant instruction cause?
There are two answers. First, the instruction competes for attention. The model has to weigh that instruction against what matters for today's task, so being correct is no defence. Second, the instruction goes stale. Permanent context creates a maintenance job, and future tasks inherit today's temporary truth.
Anthropic says the same in its own Claude Code documentation on memory. It recommends a target of under 200 lines per CLAUDE.md file and states plainly: "Longer files consume more context and reduce adherence." The same page notes that Claude treats these files as context, and that "The more specific and concise your instructions, the more consistently Claude follows them."
The augmented coding patterns catalogue has a name for the habit of adding rules until the important ones get ignored: Obsess Over Rules. Having a name for the habit helps. A team that can say "we're obsessing over rules again" can catch itself.
Five tests for a line of permanent context
Before something earns a place in a file Claude reads every time, I ask whether the line is CRESS:
- Current. Is it still true today?
- Refutable. Could something show it to be wrong? A brief that says "this passes" is weak. A brief that names a failing test and the command to run it can be checked.
- Empirical. Is it based on what the project actually does, or on what someone assumes?
- Small. Is it as short as it can be?
- Specific. Does it apply to this project, or is it generic advice the model already knows?
"Use encryption for passwords" fails the last test. The advice is true, and Claude already knows it. In a ground rules file the line only takes up room.
Where should each piece of knowledge live?
The bigger shift comes when people stop asking "should this go in CLAUDE.md?" and start asking where the knowledge belongs. In the masterclass I give teams four questions to ask about each piece of knowledge, in a fixed order:
- Is it worth keeping?
- Must it be guaranteed?
- Who needs it?
- When must it be in context?
The first question sends some facts nowhere. The second sends anything that must never happen to a deterministic control, such as a permission rule or a hook, because an instruction influences behaviour and a control enforces it. The last two questions place whatever survives: the root CLAUDE.md, a smaller CLAUDE.md inside one folder, a skill, a reference document, the current prompt, or someone's personal memory.
Teams then sort a set of placement cards. Half of the cards describe newsletter and marketing work, so non-technical participants have cards they can own outright. A few examples:
- This month's newsletter brief belongs in the current prompt. The brief expires the moment the newsletter goes out.
- The steps you follow every month to get a newsletter checked, approved and sent belong in a skill. The steps are a repeatable procedure with a result you can check. I've written about turning repeated work like this into a skill.
- Yesterday's open rates for the last newsletter belong nowhere permanent. Those figures were true yesterday and will mislead next month.
- "Never send to the whole mailing list without a test send first" belongs in the sending tool as a block. A reminder in a text file is no guarantee.
The one-line test I repeat most: a skill tells Claude what to do, and a reference helps it know what to consider while doing it.
Prove the file is being read
A small trick lets you check whether a context file reaches Claude. At the end of each context file, ask Claude to start every response with a specific emoji. Give each file a different one.
If the emoji appears, the file reached the model. If it doesn't, the file was never read, and rewriting its wording will not help. A nested file's emoji should show up only when you work in that folder. A skill's emoji should show up only when the skill runs. The emoji check takes a minute to set up and it ends a lot of guessing.
What participants take away
One developer, Heinrich, summed up what stayed with him after the programme in a single line:
"Setting up the Claude.md files correctly to provide certain context when needed."
The phrase I'd underline is "when needed". Good context arrives when the task needs it and stays out of the way the rest of the time.
Making context engineering a team habit
In the session, everyone runs /init in a real project of their own, which has Claude draft a CLAUDE.md by inspecting the code. Then they audit it line by line. Every item gets one decision: keep it, move it to a folder-level file, extract it into a skill or reference, or delete it on purpose. They run the commands the file claims, and they correct or remove any that Claude invented.
The homework turns context engineering into a team practice. Each team sits down before the next session and agrees what Claude should do automatically while they build a feature together, then builds the context that makes it happen: ground rules in the root file, a knowledge base written as linked references, and the repeatable steps captured as skills.
If your team has a CLAUDE.md that keeps growing while the output stays the same, I'd like to talk to you about that file. See how the programme for engineering and product teams works, and get in touch if the programme fits.