Writing

How to Write a CLAUDE.md File for a Side Project

By Scott Wilder · October 30, 2026 · 6 min read · All writing

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:

  1. Put @AGENTS.md on the first line of CLAUDE.md, then add Claude-only rules below it.
  2. 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.

  1. Open Claude Code in the project folder and type /memory. It shows which CLAUDE.md files are loaded and lets you edit them.
  2. If your file is not listed, it is in the wrong place. Move it to the repo root or to .claude/CLAUDE.md and open a new session.
  3. 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.
  4. 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.

  1. Is the file listed in /memory? If not, nothing else matters.
  2. Is the rule checkable? If you could not pass or fail it on a diff, rewrite it.
  3. 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.
  4. 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

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.

Questions

Where does the CLAUDE.md file go?

Put it in the repo root or in .claude/CLAUDE.md. Claude Code loads it automatically at the start of every session. Run /memory to confirm it is listed.

How long should a CLAUDE.md be?

Aim for under about 200 lines. That is a guideline, not a hard cap, but a longer file costs tokens on every turn and spreads the agent's attention across more rules. Check yours with wc -l CLAUDE.md.

Does Claude Code read AGENTS.md?

No, it reads CLAUDE.md only. Put @AGENTS.md on the first line of your CLAUDE.md, or symlink it with ln -s AGENTS.md CLAUDE.md, so one set of rules serves both agents.

Should I use /init to create the file?

Yes as a starting point, then edit it hard. The draft infers conventions from your file tree, so it can record guesses as rules. Delete every line that fails the three month test or the checkable test.

Where do my personal preferences go?

Rules for every project go in ~/.claude/CLAUDE.md. Rules that are only yours for one repo go in CLAUDE.local.md, which is meant to stay uncommitted. Keep them out of the shared repo file.

How do I know Claude actually read my CLAUDE.md?

Type /memory and check that your file is listed. Then ask a question your file answers, such as which command runs the tests. If the answer matches, the file is loaded.