The four files your agent reads first
By the end of this lesson you can:
- Say what each of the four governing files is for
- Find the answer to “what should I work on next?” without reading the whole graph
- Tell the difference between a rule that persists and a state that changes
Four files, four jobs
A graph can hold hundreds of files. Four of them govern, and an assistant reads those before anything else. Learning what each is for is most of what you need to navigate a graph you have never seen.
CLAUDE.md — the rules
This is the constitution. It says what this graph is, how work is done here, and what an assistant must or must not do. Standing rules live here: never change these files directly, always open a session record before editing, route questions about the machine itself somewhere else.
The test for whether something belongs in CLAUDE.md is durability. If it should still be true in
six months, it is a rule. If it is true this week, it is state, and it belongs in the next file.
STATE.md — what is happening right now
The live snapshot. What is in progress, what is blocked, what happens next. This file changes constantly, and that is the point of keeping it separate from the rules — mixing the two produces a constitution nobody trusts, because half of it is stale by Thursday.
This is where you look when you sit down and think “where was I?” A well-kept graph answers that in one short read near the top of the file, and the habit of keeping it accurate is the single highest-value thing you can do for whoever opens the folder next. That person is often you, in three weeks, having forgotten everything.
MANIFEST.md — the identity card
Short and stable. What this graph is called, what kind of graph it is, what version of the standard it follows. You will rarely edit it after the first day. Other graphs read it when they need to know what they are dealing with.
AGENTS.md — local conventions
Guidance scoped to one directory. A graph can have many of these, and each applies only inside its own folder: how to name things here, what this directory is for, what to be careful about.
They exist so the top-level rules can stay short. Detail that only matters inside one folder should live in that folder, not in the file every single session has to read.
Rules, state, identity, local detail
That is the whole shape, and the split is doing real work:
| File | Answers | Changes |
|---|---|---|
CLAUDE.md | ”What are the rules here?” | Rarely |
STATE.md | ”What is happening right now?” | Constantly |
MANIFEST.md | ”What is this thing?” | Almost never |
AGENTS.md | ”What applies in this folder?” | Occasionally |
Put a rule in the state file and it gets lost in the churn. Put state in the rules file and people stop believing the rules. The separation is not bureaucracy; it is what keeps each file worth reading.
What your agent does with this
Your assistant reads these in a deliberate order, and knowing the order tells you where to put things so they actually get used.
It loads the governing file first, because that sets the rules for everything that follows. It reads the state file to find out what is live. Then — and only then — it goes looking for the specific context your request needs, guided by what those two files told it. When it enters a subdirectory, it picks up that directory’s local guidance.
The practical consequence: anything you want your assistant to always do belongs in the governing file, not in a note buried three folders down. A rule the assistant never reads is a rule that does not exist. Likewise, keeping the state file honest is not paperwork — it is the difference between an assistant that resumes your work and one that has to ask you what is going on every time.