Why can a long CLAUDE.md make things worse?
The model reads it at the start of every task, whether it matters or not. Old instructions written for a weaker model compete with what the code actually says, and sometimes the model follows the old ones
Blog
Do you still need a CLAUDE.md file?
Today's models read your code better than the long CLAUDE.md you wrote three versions ago. What to cut, what to keep, and the context that belongs somewhere else
Free, no call
Get the 13, in order, and the prompt that holds them
One or two lines per step, and a prompt that makes Claude or Cursor wait until step eight
The short answer
Do you still need a CLAUDE.md file?
For code, mostly no. Current models read your codebase well, so the code is the context. Stop growing a CLAUDE.md or AGENTS.md you wrote for older models, and keep it to the few things the code cannot tell the model, like how to run it, the rules that must not break, and why big decisions were made.
What should stay in the file?
What the code cannot show: how to install, run and test the project, the rules you never want broken, and why a few big decisions were made
Where does context about my business go?
In its own folder. Your code does not know your clients, your voice or what the AI is allowed to touch, and that context is worth writing down once. That is what Brain OS sets up
Watch the video
Watch the 20-second version
The same idea in a short video, on TikTok
The code is your CLAUDE.md
An agent file written three model versions ago was written for a model that needed more help. Today's models read the repository, follow the imports and pick up the conventions on their own. Updating that old file and piling more context into it does not help them. It gives them more to read, and more old advice to follow.
What to cut
- Descriptions of the folder structure. The model can see it.
- Coding style the code already follows. The model copies what is there.
- Instructions written to work around an older model's mistakes.
- Anything that has gone out of date. Out-of-date instructions are worse than none.
What to keep
- How to install, run, test and deploy the project.
- Rules that must never be broken, like never touching production data or never committing secrets.
- Decisions the code cannot explain on its own, with one line on why they were made.
If the file still runs to pages after that, read it the way the model does: top to bottom, at the start of every task. Anything you would skip, it should skip too.
Where business context goes
Your code does not know who your clients are, how you write, what you have already decided or what the AI is allowed to touch. That is the context worth writing down once, in a folder your AI reads before it starts on anything. That is what Brain OS is: one folder that teaches your AI how your business runs, and sets itself up.
Free, no call
Get the 13, in order, and the prompt that holds them
One or two lines per step, and a prompt that makes Claude or Cursor wait until step eight
Keep readingEvery post
The launch film prompt: a 34-second film made almost entirely in code
A 34-second launch film where every screen, word and beat is code, and only the mascot came from an AI video model. How it was made, and the prompt behind it
The Opus motion design prompt: turn your website into a product video in code
A prompt for Claude Code on Opus that reads your real site and turns it into a short product video built in code, one shape that never cuts. Free, the whole prompt
2 min readFour things to learn if AI writes your code
If AI writes most of your code, four skills still decide whether it runs: bash, containers, real CSS, and hydration and state
Bring what you have. We’ll tell you where it stands
You’ll leave the call knowing what’s risky and what to do next
- 30 minutes
- Free
- No slides, no sales team