Why a bigger CLAUDE.md makes a worse agent for your studio

Did you ever write CLAUDE.md consciously? Knowing what you want to achieve and how you want your agents to work? If so, you write a long, careful CLAUDE.md for your studio.

Storage layout, naming rules, the way you like dailies binned, a paragraph on how Resolve projects are organised, god forbids passwords, some notes on the client, a reminder about the delivery spec. Everything you’d tell a new assistant in their first week or two. Then you point the agent at a day of footage and it renames the cards in a format you explicitly told it not to use, three lines above where it was reading. Consider yourself very lucky if it was only a forbidden rename, not something much worse.

The instinct, this week especially, is to assume the file wasn’t big enough. Claude Sonnet 5 just shipped as the default in Claude Code with a million-token context window. A million tokens is a lot of room. So the reflex is to pour more in, the whole studio wiki, every convention, every past decision, on the theory that a bigger context is a smarter agent. As you may feel, it’s not a good idea, it’s like seeing a strong mule and packing him even more and more, he will handle but at the same time he will lose other stuff on the way.

It’s bad idea because it just makes your agent working bad. Let me tell you why, and then how to write a CLAUDE.md that actually holds.

The file is not documentation. It’s the standing order.

A million-token window is how much the model can read, in real numbers that’s 750 000 words or the equivalent of 2500 – 3000 pages packed of dense technical, legal or scientific material. CLAUDE.md is different: it’s the set of instructions the model is meant to follow, on every turn, without being reminded. CLAUDE.md works alongside auto memory: you write CLAUDE.md for guidance and rules, while Claude writes auto memory for insights and patterns it discovers. 

Auto memory and CLAUDE.md are two different loops: auto memory writes learnings to its own MEMORY.md on its own, while “update your CLAUDE.md” is you telling the agent to edit the standing order – same idea, different files.

Reading is cheap. Following is not. As a rule of thumb, a frontier model reliably follows something on the order of 150–200 instructions, the docs put it at under 200 lines and the system prompt already spends a chunk of that before you’ve written a word. So you have a real budget – a couple hundred rules the agent will actually obey and every line you add to CLAUDE.md spends from it. Fill the file with a wiki and your naming convention is now competing for attention with a paragraph about your client’s brand history. The important rule doesn’t get louder in a bigger file. It gets quieter and the agent it will miss it more often.

That’s why the bloated CLAUDE.md fails in the exact way it does: not a refusal, a dilution. The rule was there. It was in there next to forty things that didn’t need to be.

The file works when it holds only what the model would otherwise miss.

The test for every line

Before a line goes in CLAUDE.md, ask one thing: would the agent already know this, or figure it out from the project? If yes, cut it.

• How Resolve organises a project – it knows. Cut.
• What a bin is, what an AAF is, how relinking works – general knowledge. Cut.
• Where your working media lives versus where the camera masters live – it cannot guess. Keep.
• That your date format is YYYYMMDD everywhere and nothing else – it will guess wrong half the time. Keep.
• The one-off instruction for today’s task – that goes in the prompt, not the file. Cut.

What survives that test, for a post studio, is a short list: storage paths, naming conventions, folder structure, the primary tools you actually use, and the hard do’s and don’ts, especially the safety ones. Almost everything else is either something the model already knows, something it can read from the project, or something that belongs in the moment you ask, not in the standing order.

What a real one looks like

This is closer to the right size than most people expect. It’s a studio brain, not a manual.

# My postproduction studio brain

## Storage

- Working media: /Volumes/POST/{project}/media – do work here.

- Camera masters: /Volumes/ARCHIVE/{project}/BU1 – read-only. Never write to ARCHIVE.

## Primary tools

- Grade and finish in DaVinci Resolve. Assume a Resolve project unless told otherwise.

## Naming

- Camera cards: {DATE}_{CAM}_{CARD}. DATE = YYYYMMDD. CAM = A1/B1/DJI/ARRI

- When relinking, match on the camera-reel substring in the clip ID, not on the file path.

- Date format everywhere is YYYYMMDD. No other format.

## Folder structure (per project)

- 01_dailies / 02_timelines / 03_exports / 04_delivery

- New dailies go to 01_dailies/{DATE}, one bin per shooting day.

## Hard rules

- Destructive file ops (move/rename/delete): dry-run first, show the plan, wait for my yes.

- Renames and relinks run on the working copy, never on ARCHIVE. Make sure I have a backup copy.

- When you get something wrong and I correct you, update this file so it can't happen twice.

And when a rule absolutely has to hold – the forbidden rename, anything that deletes media – don’t leave it to the file. CLAUDE.md is context, not enforcement; the docs are blunt about it, there are no guarantee of strict compliance. The hard stop is a PreToolUse hook, which blocks the action regardless of what the agent decides. I lost one day of footage, but more on that later.

That’s the whole thing. Not because there’s nothing else true about the studio, because everything else is either inferable or belongs somewhere other than the standing order. If you can’t say why a line has to be there, it doesn’t. Remember that you can always ask Claude if you miss anything, this is a powerful prompt: “Am I missing anything?” it will point you well.

The file should be grown, not written

The best CLAUDE.md isn’t drafted in one sitting. It’s grown from corrections.

The last rule in the example is the mechanism: when the agent gets something wrong and you correct it, tell it to update its own CLAUDE.md so it never makes that mistake again. Do that consistently and the file becomes a record of every place the agent has actually tripped, which is exactly the set of things it would otherwise miss. That’s the test passing automatically. Lines earn their place by being mistakes you’ve already had to fix once.

A file built this way stays small on purpose. A file written up front, from imagination, grows in every direction because you can’t tell in advance which rules the model needs and which it already has.

Where this sits between the ditches

Two ways to get this wrong.

The right-hand ditch is the one the million-token window invites: dump everything in, trust the big context to sort it out. It won’t. It’ll obey your real rules less reliably, and you’ll spend the time you saved on writing the file re-fixing the same renames.

The left-hand ditch is having no CLAUDE.md at all – re-explaining your storage layout and your date format at the top of every session, forever, and eating the same mistakes because nothing persists between conversations.

The middle is a tight file that holds only what the model would otherwise miss, grown from real corrections, kept short on purpose. Boring, and it works.

It’s also worth knowing which file actually reaches the floor. The project-root CLAUDE.md is the shared one, checked into git, or living on the NAS in a post house, so it’s the file that reaches every operator. The ones under ~/.claude and .local are personal to your machine, and the enterprise file is whatever IT pushes down. When you want a rule the whole team obeys, it goes in the checked-in project file.

And the foundation underneath it has to be real. This is the 90/10 point: the CLAUDE.md only encodes conventions you actually keep. If your naming is inconsistent on the drive, no file fixes that, you’ve just written down a rule your own media breaks. Get the manual foundation right first: folders, naming, where things live, then encode it. The file is the last 10%, not the first.

The honest limit

It will still ignore the file sometimes. A rule can be short, correct, and sitting right there, and the agent will occasionally do it its own way anyway, most often when you describe a task instead of naming the exact procedure you want. CLAUDE.md raises the odds; it doesn’t guarantee them. For the work where being wrong is expensive – anything that moves or deletes real media – you still dry-run, still work on the copy, still read the plan before it runs. Standing order is a good habit. It is not a substitute for looking. Remember, you are working with intelligence that as every intelligence makes mistakes, chooses poorly, goes for shortcut or fixate around something irrelevant.

A million tokens buys you room to read. CLAUDE.md stays in the doorway, guarding who comes through it but sometimes it behaves as if it forgot its glasses or didn’t sleep well the night before.