Document your projects for agents
30 September 2026
A short CLAUDE.md, an AGENTS.md, a .ai/ folder once the project grows. The agent writes, you review. Here is how to set it up, and how to keep it up to date.
In I don't write the documentation, I explain why every one of my projects now carries its own manual, written by the agent and reviewed by me, and what that prevents in production.
Here is how to set it up on yours.
You don't write anything: the agent writes, you review.
Step 1: a short CLAUDE.md at the root
This is the file the agent reads at the start of every session, before your first sentence.
If you have been working with an agent for a few months, you probably already have one. Open it. If it doesn't exist, Claude Code's /init command reads the project and writes it for you. With another agent, ask for the same thing in plain words.
What it should contain:
- what the project does, in three lines
- the stack, and the commands to run, build and test it
- the conventions to follow
- what we don't touch, named explicitly
- where to find the rest
Then look at its length. It is loaded in full at the start of every session. The longer it is, the more context it costs in every conversation, and the less weight each instruction carries among the others. Ours are between thirty and seventy lines. Yours is three hundred? That is step 3.
To review it, three questions. Is it right. Does it say clearly what we don't touch. Has it made up a rule you have never followed.
Step 2: an AGENTS.md next to it
CLAUDE.md is Claude Code's convention. Codex reads AGENTS.md, and other tools will read something else tomorrow.
No need to maintain two versions. Ours is three lines long:
# My project
See [CLAUDE.md](./CLAUDE.md).One content to maintain, and the project stays readable the day you switch agents.
Step 3: the .ai/ folder once the project grows
For a small project, CLAUDE.md is enough. Don't create the rest on principle.
Move on to this step the day CLAUDE.md can no longer carry everything without bloating. A server, security rules, a design system, scheduled tasks, and that's it. You then move the detail into a separate folder, one file per topic, and CLAUDE.md goes back to being a table of contents that points to it. The agent only reads what the task needs.
The skeleton we use, the same on twenty-eight projects:
my-project/
├── CLAUDE.md the table of contents, read every session
├── AGENTS.md the same contract, for another agent
└── .ai/
├── AGENTS.md entry point, reading order
├── ARCHITECTURE.md stack, folders, dependencies
├── DOMAIN.md what the project is about
├── FLOWS.md the main journeys, end to end
├── RULES.md what is forbidden, and why
├── TASKS.md step-by-step procedures
└── TOOLS.md tools, access, connectorsDOMAIN.md is the domain in the business sense, not the domain name. It says what the project is about, in its own words. For our radio: the shows, the episodes, the hosts, and the states an episode goes through, from scheduled to aired to published. For a showcase website: its pages and sections. For a Shopify store: its collections, its product pages, and what section, block or template mean in its theme. Without it, the agent mixes up two notions that look alike in the code.
TASKS.md holds the procedures for what comes up often: adding a field, creating an API endpoint, rotating an access key. Step by step, with what you can change safely and what you don't touch without checking.
The skeleton is fixed, the list isn't. You add a file when a project has a constraint the others don't: an INFRA.md where there are servers, an AUTOMATIONS.md where scheduled tasks run, a BRAND.md on a client project.
The entry point, .ai/AGENTS.md, tells the agent what to read, and in what order, depending on the task. "Working on the player? Read the architecture, then the flows, then the rules." Without it, the agent reads everything or nothing.
The prompt to set it up
You don't write these files either. Open a session in the project, fill in the three lines at the top, paste the rest as is. It works on a blank project as well as on one that already has a CLAUDE.md that is too long: the agent starts from what exists, proposes a plan, waits for your approval, then writes.
You are going to write, or put back in order, this project's manual:
the instructions agents will read before working on it. A human must
be able to read it too.
WHAT THE PROJECT IS: [IN ONE SENTENCE]
WHAT MUST NEVER BREAK: [PRODUCTION, A FLOW, DATA]
WHAT I EXPLAIN MOST OFTEN: [A PROCEDURE, A CONVENTION]
THE LOGIC
CLAUDE.md is loaded in full at the start of every session. It stays
a table of contents, one page at most: what the project does, the
stack, the commands, what we don't touch, and where to read the
detail.
The detail goes in a .ai/ folder, one file per topic, so that an
agent only reads what its task needs:
- .ai/AGENTS.md: the entry point. What to read, in what order,
depending on the task.
- ARCHITECTURE.md: the stack, the folders, what depends on what.
- DOMAIN.md: what the project is about, in the business sense: its
notions, what they mean here, their states.
- FLOWS.md: the important journeys, end to end.
- RULES.md: what is forbidden or risky, and why.
- TASKS.md: step-by-step procedures for what comes up often.
- TOOLS.md: the tools, commands, access and connectors in use.
Add a file only for a constraint specific to the project: INFRA.md
if there are servers, AUTOMATIONS.md if there are scheduled tasks.
AGENTS.md, at the root, simply points to CLAUDE.md, for other
agents.
BEFORE WRITING
If there is already a CLAUDE.md, a README or documentation, read
them first: that is material, don't overwrite it. Then read the code,
the config, the scripts and the git history. Then ask me up to five
questions, one at a time, only the ones whose answer would change
what you write.
THE PLAN, THEN THE WRITING
First propose the plan: which files you create, and what you move
from an existing CLAUDE.md into .ai/. Wait for my approval. Then
write. Only create the files you actually have content for.
RULES
Describe what you read, not what would be desirable.
Name what we don't touch, and why.
Also write down what isn't what it looks like: a folder that looks
like the source and isn't, a dangerous script.
Write in the language of the existing documentation. If there is
none, ask me.
When information is missing, write [TO COMPLETE] and carry on.
Don't make up any rule the code doesn't show.
TO FINISH
List the points you are unsure about, so I can review them first.Review the points it flags itself first, then everything that touches what must never break.
In the infrastructure manual of our radio, one line says a folder on the server is not the source of truth: it is a cache of the next twenty-four hours, and a missing file is not a lost file. Without it, an agent that can't find an episode concludes that data has been lost.
Keeping it up to date
A manual describes the project at a given moment. The project moves, the manual doesn't. A wrong manual is more dangerous than no manual, because the agent believes it.
Two habits are enough.
When you change something the manual describes, a command, a rule, a procedure, ask the agent to update it right away. It has just made the change, it knows exactly what to fix.
And every now and then, ask the question as is:
Is this project's manual still up to date? Compare it with the code
and the recent git history. Tell me what has changed and what needs
fixing, then wait for my approval before editing.It gives you a list, you approve, it fixes. After the third time, ask it to turn this into a skill: it knows the process, it has just followed it three times with you.
What not to do
Don't write it yourself. You would describe the project from memory, the agent describes it from the code.
Don't fill in all seven files at once on a project that doesn't need them. A short, well-reviewed CLAUDE.md is worth more than a half-empty .ai/ folder.
And don't keep a wrong line telling yourself you will fix it later. Fix it, or delete it.
To start, open the CLAUDE.md of the project you work on most. If it is long, paste the prompt: the agent will offer to split it. If it doesn't exist, run /init. The next time you open a session on that project, you will see what you no longer need to explain.