Why an AI agent needs project documentation
What an agent does not know about a project
In Within a Budding Grove, Proust has the painter Elstir tell the narrator that "we are not provided with wisdom, we must discover it for ourselves", at the end of a journey nobody else can make for us. A project is learned the same way. What we know about it comes from the decisions we made and the mistakes we fixed along the way. An AI agent has made none of that journey, and it starts again from the code in every session.
It reads that code in seconds, and works out most of the technical choices from it. What the code does not give it is why a decision was made, or which options we tried and dropped. So it repeats searches we have already done and walks back into mistakes we have already fixed.
Giving it the project's full history does not solve the problem. The study we cited in our article on agent memory found that models answer worse as their context grows. The agent also ends up sorting through that history itself, when it should be doing the work we asked for.
Project documentation has to answer both problems. It has to give the agent the decisions and the reasons behind them, and it has to stay short enough to leave room in the context. When it does both, we consider it the main lever of development with agents.
Where our method comes from
Our earlier articles covered one source of context, the memory our agents share, which we set up with Cognee and then filtered with memsift. Documentation is the other one. It lives in the repository itself, a practice usually called docs as code.
The way we apply it comes from our own projects first. We wrote the method down after the fact, and kept only the rules that had held up from one project to the next. It also lines up with current research on memory and context management. Anthropic describes agent memory as a stack of layers, where only the smallest one is loaded in every session. OpenAI, in its article on harness engineering, makes the point that anything missing from the repository does not exist as far as the agent is concerned.
What we ended up with is seven files and a folder of guides, and we publish their templates in agent-docs-starter, an open source repository. The diagram below groups the files by the role they play in a project.
A project's documents and the role of each
AGENTS.md and CLAUDE.md, the files an AI agent reads every session
The first group in that diagram reaches the agent before we have asked it anything. Because those files sit in its context for the whole session, we keep them to two jobs. They tell the agent how to behave, and they tell it where to look.
What goes in AGENTS.md
AGENTS.md is where we correct the agent's behaviour. When it gets something wrong, we ask two questions, whether the mistake keeps coming back and where it comes from. If it comes from the agent's own working habits, it goes in the file. If it comes from the business the project serves, it belongs in a guide or a reference document instead.
The file itself is laid out in the order a task unfolds, from reading the code to finishing the work. The outline below is translated from the repository of an online shop we built, with two of its instructions left in place. Each one is there because of a habit the agent had.
AGENTS.md
├── Working method
│ └── pointer to INDEX.md, to read first
├── Before changing anything
│ └── Explain first the concrete effect
│ for the product or operations.
├── Sources of truth
├── During the work
│ └── Do not commit without an explicit
│ request from the project owner.
├── Branches, commit and merge
└── Before declaring it doneAn index so the agent can find the rest
The agent then needs to know where everything else is. That is the job of INDEX.md, which gives each document a single line saying what it contains and when to read it.
# Document index
- `README.md`: getting started with the project, for the client.
- `docs/ARCHITECTURE.md`: technical decisions and their reasons. Read before touching the structure.
- `docs/DESIGN-SYSTEM.md`: visual rules. Update after a decision is approved, never before.
- `docs/guides/deployment.md`: release procedure. Reread before every deployment.
- `BACKLOG.md`: remaining work.With the index loaded, the agent goes straight to the right file, where it would otherwise run a string of commands to explore the repository. A different agent opening the project for the first time gets the same map.
Claude Code and Codex do not load it the same way. In Claude Code, CLAUDE.md imports both AGENTS.md and INDEX.md, so they arrive in every session. Codex loads AGENTS.md on its own, but its documentation describes no import mechanism, so AGENTS.md carries an instruction pointing to the index.
What it costs in context
The index is not free, because it takes up context in every session. Our first idea was to leave it in the README. On one of our brochure sites, though, the README is 155 lines written for the client, and the agent would have loaded all of them to read six. We ruled out the docs folder for a similar reason, since an index is something you look for at the root. So it became its own file, and the cost stays reasonable as long as each document gets one line.
Anthropic describes the same trade-off. In its article, the part of memory injected into every session has to stay small, because a wrong note placed there is repeated in every session. OpenAI reached the same conclusion the hard way. Its team started with a single large instruction file, which went stale quickly, and ended up cutting AGENTS.md to about a hundred lines that work as a table of contents.
Architecture, design system, guides: where a project's decisions get written
Most of what the index points to is where we record decisions. We write each decision down with its reason, and we accept that a test may overturn it later. Each of these documents follows a fixed outline and opens with a few lines saying what it covers.
A decision and the reason behind it
ARCHITECTURE.md explains how the system is built and why. Every structural decision goes in as a decision in its own right, separate from the discussion that led to it. Every project we build has this file, even a brochure site. Its outline runs from the summary down to the detail.
ARCHITECTURE.md
├── header
│ └── what the document covers, what it
│ leaves to the backlog and the guides
├── Quick read
│ └── the invariants to preserve
├── System topology
├── Sources of truth
├── Decision index
├── Detailed decisions
│ └── by domain
└── Known pitfallsWriting a decision down does not make it final. With memsift, our memory plugin, we set out the principles and the data flow first. Testing then showed that the first questions we put to the decision model were the wrong ones. We fixed the behaviour, and we updated the document only once the fix had been confirmed.
A design system to stop drift
Design has a similar problem. As a front end grows and goes through iterations, small variations creep in from one page to the next. DESIGN-SYSTEM.md exists to stop that drift. We define the styles in code first, and write the document from them when the art direction is set. After that, every addition is checked against the system. If it does not fit, we decide whether it should become part of it.
The document has the same backbone on every project, and wherever we can we write its rules as closed counts, such as a fixed number of colours.
DESIGN-SYSTEM.md
├── The spirit in one sentence
├── Technical source of truth
├── Typography
├── Colours
├── Spacing
├── Components
└── ApplicationWhat we decided against is writing the rule before the code. A visual adjustment has to be judged by eye, so we update the document only after we have approved the result on screen.
Runbooks and checklists
Operations we repeat get their own documents in docs/guides. There are two kinds. A runbook describes an operation on the production system, such as a release. A checklist lists the verifications to run again before a deployment or a merge.
A runbook follows the outline below, while a checklist runs from the most automated check to the most manual.
docs/guides/deployment.md
├── context
│ └── pointer to the architecture decisions
├── Prerequisites
├── Procedure
├── Special case
├── Verification
└── TroubleshootingEither way, a guide says how to do something and leaves the why to the architecture document. The deployment guide gives the procedure, and the reason we chose that hosting stays in ARCHITECTURE.md. All of these files are Markdown, the format agents work in best.
Who writes the documentation, the AI agent or a human?
That leaves the question of who decides what goes into these documents. An agent will write in the right place if we tell it where. What it still does poorly is judge what is worth keeping after an important decision. A study from ETH Zurich and LogicStar on agent files points in the same direction. Files written by a model slightly lowered its results, while files written by developers improved them a little. So that decision stays with us.
What is worth writing down
In practice, every event in a project raises the same question, which document it belongs to. The diagram below shows the four cases.
Where each project event gets written
In every case, a rule is written down only after it has been tested. A principle becomes a source of truth once it has proved itself. In the same way, recording the agent's mistakes reduces the project's risk surface, as long as we keep only the ones that recur.
Keeping the backlog current
The end of an exchange with the agent is where this review is most concrete. That is when we update BACKLOG.md, which tracks day by day what has been done and what is left. New tasks turn up during a project, after a test, a difficulty or a request from the client, and they go there too. We also check whether the agent introduced an idea nobody asked for, which may become a task.
The file is there to run the project, and we write it for ourselves rather than for the agent. Current and upcoming tasks come first, and completed tasks sit at the end.
BACKLOG.md
├── header
│ └── what the file contains,
│ where the constraints are
├── How to write a task
├── In progress
├── Upcoming
└── DoneAgent memory or documentation
None of this replaces the memory described in our earlier articles. Memory keeps, from one session to the next, whatever saves the agent from repeating a search, and a decision model does the sorting. Documentation keeps what a person has approved. It also travels with the project to the client, who may not have a memory set up at all.
What OpenAI does differently
OpenAI made a different call here. Its repository is organised much like ours, with a short agent file, an architecture document and a folder of documents. The difference is that its agents write the documentation, and automated checks verify it afterwards. Scale explains part of that, since the repository holds about a million lines. On a project delivered to a client, a person can still read everything that goes in.
Taking your project over with your own AI agent
All of these documents are used during the project, and all of them are delivered to the client with the code. Only one is written for the client, the README.
What goes in the README
The README follows the client's needs in the order they come up. It says what the project contains, then how to use it day to day, then how to change the code.
README.md
├── introduction
│ └── a paragraph saying what the project is
├── What this project contains
├── Getting started
├── Deployment
└── pointer to INDEX.mdThe other documents are not written with the client in mind. But a file an agent can read is one a person can read too, so the client is free to open them.
What it changes for the client
That last part matters most to a client with no technical background. On one of our brochure sites, the README takes the client from opening a terminal to installing Claude Code in six steps, in about an hour. It then explains how to phrase a request to the agent. From there, the agent finds the instructions and the decisions it needs in the repository, just as it did while we were building the site.
This is how the client comes to own what we build for them. They can take the project over without us, or ask us to carry on.
Scaling the documentation to the project
The system is not the same size on every project, and each of its rules can be adjusted.
When the repository grows
In a small repository like memsift's, the architecture document can keep a record of what we tried. In a large one, the same habit would bury the agent in context, so we drop it. Guides stay in a single flat folder until there are about ten of them, then move into subfolders. And we write a specification only on projects where it reduces risk.
What is still open
The part of the sorting we keep for ourselves may change too. Anthropic reports that recent models are better at judging what is worth keeping. In its tests, Claude Sonnet 3.7 wrote 413 memory files where Claude Fable 5 wrote about ten. OpenAI says it does not yet know where human judgement adds the most. Some of the questions we ask today may be the agent's to answer later.
An open source repository to document your own project
The outlines shown in this article are collected in agent-docs-starter, a public repository under the MIT licence. The repository is the template. Its nine files are already in place, ready to be copied into a project as they are, and a conventions file explains the reason behind each rule.
agents-md · ai-agents · claude-code
agent-docs-starter
The Markdown files for documenting a project that AI agents work in, with an agent file, an index and an outline for each document.
git clone https://github.com/nualt/agent-docs-starterAt Nualt, every project ships with its documentation
This documentation is written during the project and leaves with it. We update it each time a decision is approved, and we hand it to the client with the code and the access credentials.
We work this way on an online shop and on an agentic AI project alike. In both cases the client keeps a project their own agents can read, and can develop it with or without us.
Frequently asked questions
Answers to the questions we hear most often on this topic.
What is docs as code?
Docs as code means writing a project's documentation as plain text files, usually Markdown, and keeping it in the same repository as the code. The documentation is then versioned and reviewed in the same commits as the code it describes.
What is the difference between AGENTS.md and CLAUDE.md?
Both are instruction files loaded at the start of a session. Codex and several other agents read AGENTS.md, while Claude Code reads CLAUDE.md. In our repositories CLAUDE.md does nothing but import AGENTS.md and the index, so there is only one set of instructions to maintain.
How long should an AGENTS.md file be?
OpenAI reports using a file of about a hundred lines that works as a table of contents. Ours run from about ten lines to a little over a hundred, depending on the project. Whatever the length, the file sticks to instructions about behaviour, and the index points to everything else.
Who should write the documentation, the AI agent or a human?
An agent can draft a document and put it in the right place. On our projects, a person decides what is worth putting in, above all for important decisions. OpenAI works differently on a repository of about a million lines, where agents write the documentation and automated checks verify it.
What documentation does a brochure site need?
A brochure site needs a README for the client, an agent file, an index and an architecture document, even a short one. A design system joins them once the site has an art direction, and a deployment guide once it is live.
Is a document index worth its context cost?
Yes, as long as each document gets a single line. The index takes a little context in every session, and in return the agent does not have to explore the repository to find the right file.
What is the difference between repository documentation and agent memory?
Memory keeps, across sessions, whatever saves the agent from repeating a search, and a model sorts what goes in. Repository documentation keeps what a person has approved, and it is delivered to the client with the code.
