Keep your CLAUDE.md under about 200 lines, write every line as something Claude Code should do or never do, and check once that the file loads. By the end of this post you will have a five-section template to paste, a two-question test, and a fixed order for finding out why a rule gets ignored.
A CLAUDE.md is a markdown file in your repo root or in .claude/CLAUDE.md. Claude Code loads it automatically at the start of every session. It is not documentation. It is a short instruction sheet for an agent that forgets everything between sessions.
If you build on nights and weekends, that sheet saves you the most. You do not have time to re-explain your test command every Tuesday.
A five-section CLAUDE.md you can paste today
Create CLAUDE.md in the repo root and paste this. Replace every bracket with a real command or a real rule. Delete any section you cannot fill honestly.
# Project
[Two sentences: what this app does and the stack. Example: Habit tracker web app. Next.js, Postgres.]
# Commands
- Run locally: [your command]
- Run tests: [your command]
- Lint: [your command]
# Rules
- Use named exports except for route files.
- [Two or three rules about imports, error handling or async that you have actually been annoyed by.]
# Do not touch
- [Files or folders the agent must never edit, such as migrations already run or the .env file.]
# Done means
- Tests pass and lint is clean before you say a task is finished.
That is about 20 lines. Most side projects never need more than 60.
Why these five sections and nothing else
Each section answers a question the agent would otherwise guess at. What is this thing, how do I run it, how should the code look, what is off limits, and when am I finished. The best-known guides frame the file as a short set of enforceable constraints, and this layout follows that idea.
The "Done means" section is the one most people skip. It pairs well with the checks in How to Tell If an AI Agent Actually Finished the Task.
Cut any line that fails one of two tests
Run every line through these two tests.
The three month test. Ask: will this still be true in three months without an edit? If not, remove it. Roadmaps, sprint goals and OKRs do not belong in the file. They go stale in weeks, and a stale line is an instruction that is wrong.
The checkable test. Ask: could I pass or fail this on a diff? "Write clean code" cannot be checked, so it changes nothing. "Use named exports except for route files" can be checked, so the agent can actually follow it.
If a line describes something (history, background, a long explanation), cut it or move it to its own doc. If a line tells the agent what to do or not do, keep it.
| If the line says | Do this |
|---|---|
| "We use Postgres because..." | Cut the because. Keep "Stack: Postgres." |
| "Write clean, readable code" | Rewrite as a checkable rule or delete |
| "This quarter we are building billing" | Delete. It fails the three month test |
| "Never edit /migrations" | Keep. Move it under Do not touch |
| "Run npm test before finishing" | Keep. Move it under Done means |
Stay under 200 lines and count them
Run wc -l CLAUDE.md in the project folder. Under 200 passes.
The 200 line figure is a guideline. The reported technical ceiling is far higher, at 4 MiB, so a long file will still load. The reason to stay short is cost and focus. The file is read into the input on every turn, so every extra line is paid for on every message. And more rules can mean fewer get followed because the important ones get buried.
Example: say your file is 260 lines and you send 40 messages in an evening. Those 60 extra lines ride along 40 times. If they are not used in most sessions, they are a bad deal.
The rule: if a line is not used in most sessions, move it to its own file or delete it. If you are watching token spend, AI Agent Spending Limits covers the cap side of the same problem.
Split a long file with @imports instead of deleting good rules
When the main file nears 200 lines, move detail into another file and point to it. The @path syntax takes relative and absolute paths and follows imports up to 4 hops. For example, put @docs/testing.md in your CLAUDE.md and keep your test conventions in that file.
Start with /init, then edit it hard
The fastest start is to run /init inside Claude Code. It analyzes the repo and drafts a CLAUDE.md with build commands, test commands and conventions it infers. If a file already exists, it suggests improvements instead.
Do not keep the draft as is. It infers conventions from your file tree, so it can write a guess down as a rule. Read every line, then run the two tests above. Delete what fails.
If you are brand new to the tool, Claude Code for Non-Developers: A Practical Setup That Stays Safe walks through day one, and /init fits right after it.
Claude Code reads CLAUDE.md, not AGENTS.md
If you also use another coding agent that reads an AGENTS.md file, this one bites. Claude Code reads CLAUDE.md and ignores AGENTS.md, so your rules silently do not load.
Two fixes, both from the same source:
- Put
@AGENTS.mdon the first line of CLAUDE.md, then add Claude-only rules below it. - If you need nothing Claude-specific, make a symlink:
ln -s AGENTS.md CLAUDE.md.
Pick one. Two copies drift apart within a month.
Put each rule in the file that matches who it is for
| The rule applies to | Put it in |
|---|---|
| Every project you build | ~/.claude/CLAUDE.md |
| This repo and anyone who opens it | The repo CLAUDE.md |
| Only you, not collaborators | CLAUDE.local.md, which is meant to stay uncommitted |
Do not keep your personal habits in the shared file. They apply to everyone who opens the repo. Also keep secrets, API keys and private prompts out of every one of these files. Treat the file as something that could be shared. Prompt Injection: What Every Builder Running AI Agents Should Know explains why a loose file is a risk.
Prove the file loads in two minutes
A misplaced file means every rule is ignored, and nothing tells you. Check it once.
- Open Claude Code in the project folder and type
/memory. It shows which CLAUDE.md files are loaded and lets you edit them. - If your file is not listed, it is in the wrong place. Move it to the repo root or to
.claude/CLAUDE.mdand open a new session. - Ask a plain question: "What commands do you run to test this project?" If the answer matches your Commands section, the file is loaded. Asking the agent directly what it retained from its memory files is a known way to check.
- Test one Do not touch rule. In a throwaway branch, ask for a small change that would break it. The agent should refuse or ask first.
Step 3 is the pass or fail. It takes under a minute.
When a rule gets ignored, check these four things in order
Stop at the first one that fails.
- Is the file listed in
/memory? If not, nothing else matters. - Is the rule checkable? If you could not pass or fail it on a diff, rewrite it.
- Does another line contradict it? Claude can scan CLAUDE.md, CLAUDE.local.md and .claude/rules/ for contradictory statements and recommend trims. Ask it to, then delete one side of every conflict. Do not keep both and hope.
- Is the file over 200 lines? Split it with
@imports or cut it.
Most ignored rules die at step 2 or step 3.
Three mistakes that cost you the most
- Writing it like documentation. Long explanations bloat the file and bury the rules that matter.
- Trusting the /init draft. A guessed convention becomes a rule you never chose.
- Never checking it loads. One wrong folder and every rule is dead.
The upkeep habit: one line per repeat correction
Each time you correct the agent for the same thing twice, add one line. Once a month, run wc -l CLAUDE.md and delete lines that no longer hold. That is the whole routine. If you work in short blocks, it fits inside the sessions in One-Hour AI Coding Agent Sessions After Work.
Do this in the next ten minutes
Create CLAUDE.md in your repo root. Paste the five-section template, fill in your real test and lint commands, then open Claude Code, run /memory, and ask it what command runs your tests. If the answer is right, you are done for today.
Got a manual task you keep meaning to hand to an agent?
I'm a former law enforcement officer who now runs Riot Digital, an AI automation agency, and ships small products like Outposts, Columns and DrawDog. If there is a task you think should already be automated, email me with what it is and I'll tell you what I'd try first.
