CLAUDE.md Best Practices from getting it wrong.

Ryan “RyMac” McKinney · USMC · 22 August 2026 · 3 minute read

Every rule below cost me something before it became a rule. My CLAUDE.md has lived between 77 and 137 lines across every version I have ever saved, and the versions that hurt were always the long ones.

1. Short beats complete

This file is read at the start of every session. Length is not a one time cost, it is a tax you pay every time you sit down, and the same maths applies to everything else competing for room on the desk.

When mine crept past 140 lines the agent got noticeably slower to the point. Not wrong. Slower, and vaguer. Every line has to earn its seat.

2. The map points, it does not instruct

The single most valuable line in mine says: before you touch anything, go read the desk file.

The moment you also put standing orders in the map, you have 2 files giving orders. When they disagree, your agent picks one and you will not know which. If the difference between the 2 files is not sharp yet, what a CLAUDE.md file actually is draws it properly.

3. A rule has to be testable

Bad: write in a friendly tone.

Good: never use an em dash. Numbers are always digits, never spelled out.

The second kind can be checked by looking. The first kind gets ignored quietly and you find out on camera. Mine also says I cannot write code, so explain it like I am in 9th grade, and that one line has saved more time than the rest of the file put together. That is the same thinking as writing the system for somebody who is not a developer.

4. Personal in the home file, project in the project file

How you like to be talked to belongs in the personal one in your home folder, because it is true everywhere.

What this business is, where its files live, what has been decided, belongs in the project. Mixing them means copying your own preferences into 6 places and updating 2 of them, which is exactly the drift the multi brand audit was built to catch.

5. Write the reason, not just the rule

A rule with no reason gets deleted by the next person, or by you in 3 months, because it looks arbitrary.

Mine carry a line each about what the rule cost. Not sentiment. It stops me undoing my own hard won decision on a Tuesday when I am in a hurry.

6. Delete on a schedule

Once a month, read it and cut anything that has not changed a decision. Rules pile up. A file made only of additions becomes an archive nobody reads properly, including the machine.

The 6 mistakes, plainly

Putting today's work in it. That is the desk file's job.

Explaining your business philosophy. Nobody acts on it. It costs on every read.

Copying somebody else's file wholesale. Including mine. Their rules solved their arguments.

Secrets in it. Passwords and keys do not belong in a file that travels with the folder.

Never updating it. A map describing a building that was remodelled is worse than no map.

Making it the only file. Without a desk file, everything you learn today is gone tomorrow, which is the actual cause of the forgetting.

How to check yours in 2 minutes

Open it and read it as if you had never seen the project. Then ask 3 questions.

Does it tell me where to go next? If not, that is the only thing worth fixing today.

Could I follow every rule without asking a question? Any rule that fails is not a rule yet.

Would cutting this line change any decision? If not, cut it.

The shape it should end up in is the ICM folder structure, and if you want a written starting point rather than a blank file, the template is free.