CLAUDE.md is not documentation — it is the operating law of your agent

TL;DR

CLAUDE.md is not a place to explain your project structure so the agent can understand it. It is the set of rules that defines what the agent can and cannot do on your system — a forcing function that lives in context, not a document that collects dust. Write it wrong and you are still repeating yourself every session. Write it right and it runs on its own.

You have probably added something like this to a prompt: "Do not modify any file I have not explicitly mentioned."

The next session, the agent modified another file.

You added it again. The next session, same thing. You started putting it at the top of every prompt. Then you started wondering: why am I repeating something that never changes?

Because you are putting a rule in the wrong place. Prompt-level reminders get treated as context for that particular task — not as operating principles. They can fade mid-session. CLAUDE.md does not — it loads into system context and stays there throughout.

But only if you write it correctly.

01Two kinds of CLAUDE.md — and why one of them does not work

✕ CLAUDE.md as README

Describes directory structure, tech stack, project purpose

▼

Agent reads it, understands context, still makes unguided decisions

▼

You are still repeating the same instructions that should not need repeating

✓ CLAUDE.md as forcing function

Defines clearly what is allowed and what is not — conditions, exceptions, when to stop and ask

▼

Agent does not need to guess → behavior is predictable and consistent across sessions

▼

You only update CLAUDE.md when the rule genuinely changes — not as a reminder

Same file, two completely different roles. Most people's CLAUDE.md currently looks more like the left column — enough for the agent to understand context, not enough to shape behavior.

The difference is not about length or detail. It is about type of information. A README explains the current state. A forcing function sets rules for future behavior.

The test: "If I removed this line, would the agent do anything differently?" If not — it is a description, not a rule. And descriptions do not change behavior.

02Four things a working CLAUDE.md actually needs

Not everything belongs here. Four categories form the skeleton:

Hard behavioral rules — "never" and "always"

Things with no exceptions: "Never edit files outside the directory I specify." / "Always ask before deleting anything." / "If unsure about scope, stop and ask — do not guess." These must be commands, not suggestions. "You should ask when…" is much weaker than "Stop and ask when…"

Clear conditions for stopping and asking

Agents tend to either ask too much (confirming every step) or not enough (until it is too late). Define the trigger conditions explicitly: "If the change touches shared config or anything outside the current module — stop and ask first."

Output standards you need — format, language, level of detail

If you want it to report in a specific format, write commit messages in a specific convention, or keep to one language throughout — define it once here. Every time you correct the format in a prompt is a time you should not have needed to.

Context about the dangerous zones in your system

"The infra/prod/ directory is read-only — do not write to it." / "config.json is the source of truth — do not modify it autonomously." / "Service A and B share state — a change to one affects the other." The agent does not know your system's history. You have to tell it where the landmines are.

These four are enough for a working CLAUDE.md. Not complete enough, not long enough — the right kind. Add to it when you discover new patterns worth encoding, not to make it comprehensive from the start.

03Signs your setup is working against you

Your setup is doing this to you

You paste the same instruction block at the start of every sessionif it does not change based on the task, it belongs in CLAUDE.md — not in the prompt

The agent asks questions you have answered many times beforestable facts — your language preference, your conventions, who needs to be notified — belong in context, not in prompts

The same mistake, across different sessions and different tasksif the agent keeps repeating a pattern you do not want, that is a signal to add a rule to CLAUDE.md — not to correct the prompt again

You do not remember what your own CLAUDE.md saystoo long, too descriptive, no actionable rules — re-read it with one question: "which line changes behavior?"

Each signal above is a small energy drain you have learned to ignore — because it happens gradually and nothing gives it a name.

04CLAUDE.md as a one-person culture document

The most useful way to think about CLAUDE.md is not as a configuration file. Think of it as an operating-principles document — the kind you would hand a new colleague before their first task.

A new colleague needs to know the things you treat as obvious — because nothing is obvious to someone new. They need to know which areas are fragile. They need to know when to stop and ask rather than decide on their own. And they need to know what format you expect when they report back.

You can say all of that at the start of every task — or you can write it once, in the right place, and never have to say it again. CLAUDE.md is that one time.

The only difference from a real colleague: the agent re-reads CLAUDE.md fresh every session and applies it exactly as written. Colleagues sometimes forget. The agent does not — but only if you have written the right things into it.