I don’t write documentation for developers anymore. I write it for the agent.
That sounds like a small change in audience. It isn’t. It changes what goes in, what stays out, where the files live, and who updates them. Documentation written for a new hire assumes someone who will read it once, ask questions in Slack, and fill the rest in over three months. The agent gets none of that. It reads what’s there, at the moment it needs it, and whatever isn’t written down it will infer from the code.
In the previous piece I put documentation among the five sources the agent assembles its picture from, and named how it fails – absent, stale, or unreachable. This piece is the first half of the fix: getting the documentation into a shape the agent can efficiently work with, so it finds the right thing without being told where to look. The second half is maintenance, and that’s the next piece – how to keep it current so it never becomes a second job.
Why it earns the effort
Before the how, it’s worth being precise about why this layer earns the effort. There are three reasons, and none of them is that documentation is a good practice in general.
- The agent will figure things out differently every time. When it recognizes the rules by itself, the results can be noticeably different between sessions. Same question, different reasoning, different plan, and neither session tells you it was a guess rather than a fact. Writing things down makes the reasoning consistent from one session to the next.
- The agent can recover the facts from the code, but never the reasoning behind them. It sees the decision that was made, not the alternatives that were rejected or the constraint that forced this one. So when something looks strange, it has to guess whether it was done on purpose or just never cleaned up, and then it builds on that guess.
- You pay for the same discovery in every session. Every session starts empty, so before the agent touches your task it works out the layout and the conventions again. It’s the time and the token budget, but not only that – everything spent on orientation is taken from the same context window the work itself needs.
All three go away the moment it’s written down somewhere that survives the session.
Why the old excuse is dead
In the pre-agentic era, especially on agile projects, documentation was the first thing sacrificed to save time and budget. That’s understandable – putting together solid documentation took real effort. But the true pain was never writing it, it was keeping it up to date. One pivot in business direction or one architectural change could turn half your documentation into stale, useless pages.
Fortunately, nowadays this is no longer the case. Agents can write and maintain both business and technical documentation quickly and efficiently. Verbal conversations turn into written transcripts, which the agent can use to create actionable items in the task tracker, write new requirements, or refine existing ones. You can ask it to build system and infrastructure diagrams from the existing code, and to document the practices and recipes already in the project. And you can set the agent up to check the technical documentation against every code change – flag what drifted, update what it can. Not automatic on its own, but a process you set up once and it runs.
The old excuse was that documentation costs more than it’s worth. Today it’s the opposite – not having it costs more than keeping it current.
How to put it all together
Putting documentation back into your process isn’t enough – the process has to be rebuilt around it. This is the part most teams underestimate. The documentation becomes the ground every session reads from, and the process is shaped around keeping it that way. The rest of this section is what that looks like in practice – a handful of steps that get you there.
One thing runs through most of those steps – the ones where the agent does real work – so it’s worth naming it once. You don’t hand the agent a step and turn it loose. You have it analyze what’s there and propose what it wants to do, you review and correct that, and only then it applies the change. It’s the same loop you already use in planning mode, just pointed at documentation instead of code.
The same split tells you which model to run. The proposing is where the reasoning happens, so give that phase your stronger model. The applying just follows a plan you already reviewed and approved, so a cheaper, faster one handles it fine – and you’re not spending top-tier tokens on the part that doesn’t need them.
Make documentation reachable
First of all, list every external system that holds information about your project – Notion, Jira, Google Drive, SharePoint, and the rest. Install and authorize the MCP servers or CLI tools so the agent can reach them. The agent can only work with what it can reach.
Make documentation local
Giving the agent access isn’t enough. Reaching a system and searching it well are two different things, and remote is where that breaks down. An external system can only be searched through its own discovery and search API, usually far more limited than local search tools. So there’s a real chance the agent won’t find the information, even when it’s sitting right there. In local files it searches fast and thoroughly.
The fix is to import the documentation that can live in the repo, stored in version control, side by side with your code. You don’t do this by hand, and you don’t do it in one shot either. You review and approve how they’ll be organized before anything moves – that’s the first step, and the migration is the second.
The one split worth fixing up front is business and technical – that separation holds across every project.
docs/
business/ # requirements, domain rules, the decisions and the reasoning behind them
technical/ # architecture, how it's built, runbooks and recipes
Below it, the agent proposes the grouping from what it actually finds, organized the way it searches, not the way a person clicks through a wiki.
So, first step: have the agent analyze what’s there, set aside the obvious junk, and propose how the rest fits under that split, without moving anything yet:
Look at everything under [space] in [Notion / Confluence]. Don’t migrate anything yet. Tell me what’s there – the pages and roughly what each covers. Set aside anything empty, placeholder, or clearly abandoned, and list what you’d skip so I can check it. For the rest, propose how you’d organize it under `docs/business` and `docs/technical`, grouped for how you’d search it later, not copied from the current layout. Give me the proposal as the target `docs/` tree, each file mapped to the source page it comes from. If there’s anything you’re not sure where to put, say so.
Keep the filtering to the obvious cases – empty pages, placeholders, things clearly abandoned. Whether a page is stale or duplicated is a harder call. It means checking the page against the code and the other docs, so that gets its own step later. Here you’re just keeping the plain noise out of the repo from the start.
You review the proposal, fix the grouping, answer whatever it flagged. Then the second step, the actual import:
Migrate into the structure we agreed on. Move the full content – don’t summarize – and convert formatting to Markdown, keeping code blocks and tables intact; where a table is too complex for Markdown, use HTML. For diagrams, recreate them as Mermaid where they’re simple enough, otherwise export them as images and embed them. Turn each page’s title into a filesystem-safe filename that’s still recognizable. Rewrite links between migrated pages to point at their new local paths; leave links to anything that stayed external as their original URLs. Pull embedded images and attachments into the repo next to the document and update the references. List anything you couldn’t place or convert so I can handle it by hand.
Once a page is migrated, the repo copy becomes the source of truth: you read it and edit it there from now on, and the original goes read-only. You’re not keeping two copies in sync – you’re moving the document and leaving the old location behind. Maintaining both is the drift this is meant to end.
A caveat: on an ongoing project this step is optional, and the usual blocker is people, not tooling. Pulling documentation into the repo means everyone who edits it now edits it in the repo – and business docs are usually owned by product managers and other non-developers who live in Notion or Confluence, not in git.
That blocker is real today, but it’s starting to erode. A tool like Claude Code lets a non-developer change a repo document by describing the change in plain language – though they still meet branches and pull requests, and someone still merges. I wouldn’t plan a migration around that yet, but the set of documents that have to stay outside the repo is shrinking, not fixed. For now, draw the line by owner: migrate what engineers own, and leave stakeholder-owned documents where their authors work.
On a new project there’s nothing to work against, so from my perspective it stops being optional – do it from the start.
Make documentation discoverable
After the migration your documentation lives in two places. Most of it is in the repo. What couldn’t move – task tickets, monitoring dashboards, anything live rather than a document, and the pages you simply couldn’t migrate – stayed where it was.
The external side is where discovery actually breaks. Having a connector installed doesn’t mean the agent will use it. It won’t reach for Jira just because Jira is connected. It has to be told the system exists, what it holds, and what kind of question is worth opening it for – otherwise the connectors you wired up in the first step just sit there.
So you write docs/catalog.md – one entry per external system, each saying what lives there and what kind of question should send a session to it.
The local side needs far less than you’d think. The agent already searches a repo fast and thoroughly; what it can’t know is which place owns which question – that specs live in docs/business and not in Jira, and tickets the other way around. So the local part of the catalog is just two entries, written the same way as the external ones: docs/technical and docs/business, each with what it holds and when to go there. Treat your own top-level folders as one more system on the map. That’s routing, not indexing – it settles where a question belongs before any search runs.
Stop at that level. The temptation is to go deeper – an entry per directory, documents listed by name. Don’t. I measured it, and the deeper inventory does save the agent some searching, about as much as the two top-level entries already saved you. But describing those two folders takes a paragraph, and listing everything underneath them takes four times that, and every line of it goes stale on the first rename and on every directory added after it. The short version stays true for the life of the project.
One prompt builds the whole file:
Build `docs/catalog.md` – a map of where project information lives, for later sessions to read before they search. Start with two local entries, `docs/technical` and `docs/business`. For each, write **Holds** (what information is in there, in the words someone would use to ask about it) and **Reach for it when** (the kind of question that should send a session there rather than to any external system). Then add the external systems:
– Jira – [URL]
– Grafana – [URL]
– Figma – [URL]
For each one, confirm you can reach it through the connectors already set up, and flag anything you can’t reach or any connected system I left off. Then look at what’s actually in it and write the same two fields plus **Access** (the connector, the project or space to scope to, and any filter that narrows the search). Fill Holds and Access from what you find. For Reach for it when, propose what you’re confident about, and where two systems overlap or you can’t tell which one owns a question, ask me rather than guessing.
What comes back is a draft, not the final file. Read the Reach for it when lines first – those are the judgment calls, and they decide whether a later session opens the right system at all. The boundary between the two local folders and their external counterparts deserves the closest look: requirements against Jira, architecture against anything live in Grafana. Holds and Access the agent usually gets right on its own, so they need a lighter pass.
Educate your agent
The catalog now says where everything lives. What it doesn’t say is which of it matters most, and that’s the part that has to be in front of the agent before it starts looking. So you need to reference them from the agent’s instructions file – CLAUDE.md, AGENTS.md, whatever your tool loads before the first prompt.
Two things go in, and nothing else.
The first is a pointer to the catalog, so a session reads it before it starts searching. Without it you’re leaving that to chance. The agent may notice the file while listing the repo, or it may search straight past it, and you won’t know which kind of session you got until the answer comes back wrong.
The second is a short list of the documents worth putting in front of every session – five to eight of them, each a path and one line saying what it’s authoritative for. Write it as a statement of fact, not an instruction. “These are the authoritative sources for the topics named” is enough. Telling the agent to read them before writing code just forces it to open all of them in every session, including the sessions that don’t need them.
I use two conditions. First, every session should get something out of the document. The list loads before every prompt, including the ones that never touch documentation. A document that matters to one task in twenty is carried by the other nineteen for nothing. Coding conventions, an architecture overview, error handling rules: those bear on most work in the repo.
Second, it has to be broad. Narrow documents do real damage. The agent treats one as authoritative, opens it, and answers from it for questions that are near its topic without being about it. I saw this in one of my runs. The agent read a narrow business policy document, answered confidently, and got it wrong. Anything you leave off stays in the catalog, and a session that needs it will search.
Which documents those are isn’t a call to make from memory. You’ve just moved and cataloged everything, so ask the agent to propose the list from what’s actually there:
Read `docs/catalog.md` first so you know where project information lives, then look across `docs/technical`, `docs/business`, and the external systems it lists. Propose the documents most sessions would be better off having read before they start work – broad enough to apply to ordinary work in this repo, not narrow policy or process documents however important those are. The list goes into the instructions file that loads in every session, so keep it to eight at most, ranked by how many sessions each would affect. For each, give the path and one line naming what it’s authoritative for. Where two documents cover the same ground, or you are unsure about a call, ask me rather than deciding it yourself.
Then cut what comes back. It will over-include. The entries you delete cost you nothing; the ones you keep cost you accuracy.
What’s next
At this point the documentation is in place: local where it could be, cataloged, and named in the file every session loads before the first prompt. That’s the setup, and you do it once.
The setup solves discovery, and only discovery. A session now gets to the right document faster, and when that document is named authoritative, the agent opens it and stops looking. That works exactly as long as the document is right. Nothing in the setup verifies that what’s written is still true, and nothing notices what was never written down at all.
That’s the next piece: how to find the documentation that has already gone stale; how to fill the gaps – part of what’s missing the agent can recover from the code, but the decisions and the reasoning behind them only you can supply; and how to make updating the docs part of finishing every task, so you review the changes instead of writing them.
