Docs as code: documenting a project in the age of AI agents

Nualt documents every project in Markdown files versioned alongside the code. This article covers what Claude Code and Codex load in every session, what they read on demand, and how we decide what gets written down.

Thomas Sarazin
13 min read

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

For project tracking For the client On demand Every session BACKLOG.md README.md docs/ARCHITECTURE.md docs/DESIGN-SYSTEM.md docs/guides/ CLAUDE.md AGENTS.md INDEX.md
Solid lines are imports from CLAUDE.md. Dotted lines are pointers from one document to another.

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
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 done

An 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.

INDEX.md
# 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
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 pitfalls

Writing 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.

agent-memory · ai-agents · claude-code

memsift

Our memory plugin for Claude Code and Codex. Its architecture document records the choices we made and the ones testing overturned.

npx skills add nualt/memsift

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
DESIGN-SYSTEM.md
├── The spirit in one sentence
├── Technical source of truth
├── Typography
├── Colours
├── Spacing
├── Components
└── Application

What 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
docs/guides/deployment.md
├── context
│   └── pointer to the architecture decisions
├── Prerequisites
├── Procedure
├── Special case
├── Verification
└── Troubleshooting

Either 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

affects the architecture? consistent with the system? comes from its habits comes from the domain day-to-day tracking Structuraldecision ARCHITECTURE.md Visual addition DESIGN-SYSTEM.md Agent mistake AGENTS.md Guide Task done ornew BACKLOG.md
What kind of event it is decides which document to update.

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
BACKLOG.md
├── header
│   └── what the file contains,
│       where the constraints are
├── How to write a task
├── In progress
├── Upcoming
└── Done

Agent 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
README.md
├── introduction
│   └── a paragraph saying what the project is
├── What this project contains
├── Getting started
├── Deployment
└── pointer to INDEX.md

The 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-starter

At 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.

Tell us what you want to build.