Documentation Is Agent Infrastructure

Bread and butter

For agentic coding, docs are closer to infrastructure than garnish. You could say they are the bread and butter of the repo, and honestly, one of the most impactful parts of the implementation process for agents.

Think of it as the Dwyane Wade to the LeBron James, the Troy to the Abed, SGA and the refs (IYKYK). They are the part of the repo that tells an agent what kind of project it just walked into, what rules matter, where the sharp edges are, and what it should absolutely not improvise.

That sounds dramatic until you run a few serious agent workflows in the same repo for more than a week. Then it gets very obvious, very fast. The difference between a repo with maintained agent-facing docs and a repo with scattered tribal knowledge is the difference between saying:

"go implement this"

and spending half the session re-explaining the codebase like you're onboarding a new hire who keeps forgetting what database driver you use.

My stance here is pretty simple: if you're using agents to do real work in a codebase, documentation structure is one of the foundational things to get right. It should sit near the core of the project, not as an afterthought.

The better the docs are, the less time you spend steering, correcting, and reminding. The agent can spend more of its context budget on the actual task instead of rediscovering the repo every time.

The bar I like is this:

Your repo docs should be clear enough that a developer can clone the project cold, point an agent at the work, and still get useful changes without a private briefing.

That doesn't mean the docs need to be massive. It means they need to be shaped correctly.

The root file is the map, not the encyclopedia

For me, everything starts with the AGENTS.md or CLAUDE.md. The documentation pathways branch from there.

Agent-facing Markdown doesn't have a hard standard or settled best practice yet. A lot of it depends on the repo, the workflow, and the developer's taste. Some people want one big instruction file. Some want tiny section docs. Some want tool-specific files everywhere. There is still a lot of taste and workflow design mixed into this.

My own root directions are heavily based on the original style I picked up from Geoffrey Huntley, then adapted for the way I actually work. Since I use Claude and Codex, I prefer making one canonical file and symlinking the other:

ln -sf AGENTS.md CLAUDE.md

The root file should stay light enough to load every session. It is the map, not the encyclopedia. It should tell the agent what the project is, how to verify work, where the important docs live, and which rules are non-negotiable.

Something like this is the right level of specificity:

## Build & Verification Commands

| Command | What it checks |
|---------|----------------|
| npm run test:run | Vitest unit tests |
| npm run lint | TypeScript + ESLint |
| npm run build | SvelteKit production build |

Never skip the fast checks before marking a task done.

Or this:

## Maintaining Docs

Docs must stay current with the code. Update the relevant doc in the same commit as the code change. Never defer a doc update to a follow-up task.

That second line matters more than it looks like. The goal isn't to have a pretty docs folder. The goal is to make docs upkeep part of the operating system of the repo. If behavior changes and the docs don't, the next agent run is working from stale context.

That's how you get confident edits built on old assumptions, and nobody needs more of that crap.

The deeper docs should be relational

The root file should not carry every detail. It should point.

This is the shape I keep coming back to now, written as a routing map instead of pretending the fence is going to render like a fancy diagram:

AGENTS.md / CLAUDE.md
│
├─ Start here every session
│  ├─ What is this project?
│  ├─ What commands verify work?
│  ├─ What rules are non-negotiable?
│  └─ Which docs should the agent open next?
│
└─ docs/INDEX.md
   ├─ docs/ARCHITECTURE.md  -> system topology, boundaries, data flow
   ├─ docs/CONVENTIONS.md   -> coding patterns, naming, implementation rules
   ├─ docs/ENV_VARS.md      -> runtime config and secrets matrix
   ├─ docs/TESTING.md       -> test strategy and verification inventory
   └─ docs/DECISIONS.md     -> why past choices were made

That structure is boring on purpose. The agent does not need a clever documentation system. It needs a tried and true structure that is scoped to specific categories.

If the task touches environment variables, go to docs/ENV_VARS.md. If it touches system boundaries, go to docs/ARCHITECTURE.md. If it changes a repeated coding pattern, update docs/CONVENTIONS.md. If it changes how tests are organized, update docs/TESTING.md. If it raises or resolves an architectural decision, record it in docs/DECISIONS.md.

The point is not that the agent reads everything. The point is that it knows where the next useful piece of context lives.

The index is the second hop

This is why I like having a docs/INDEX.md, and why I think it is extremely crucial to the overall success of the doc structure. It is the docs folder's own map.

The root agent file gives the agent enough orientation to start. The index gives it a second-hop navigation layer so it can pull the narrow file it needs instead of dragging the whole repo history into context.

A trimmed version of my docs/INDEX.md looks like this:

# Docs Index — Glass Atlas

Navigation map for everything in `docs/`. Every doc is listed here with its purpose.
Keep this file current: add, remove, or rename a row in the same commit as the doc change.

## Core Docs

| File | Purpose |
|---|---|
| [PRD.md](PRD.md) | Product requirements, feature scope, target users, and success criteria |
| [ARCHITECTURE.md](ARCHITECTURE.md) | System topology, runtime boundaries, component responsibilities, and data flow |
| [CONVENTIONS.md](CONVENTIONS.md) | Coding standards, naming rules, and idiomatic SvelteKit/Svelte 5 patterns |
| [ENV_VARS.md](ENV_VARS.md) | Environment variable and secret matrix — names, required/optional, and where used |
| [TESTING.md](TESTING.md) | Test strategy, Vitest configuration, how to run tests, patterns for writing new tests |
| [DECISIONS.md](DECISIONS.md) | Architectural decision log — open questions and resolved decisions |

That table is doing real work. It gives the agent a routing surface:

That is the whole game. The index turns the docs folder from a pile of Markdown files into a routing layer.

Markdown works because it is cheap context

Markdown is a good fit for this because it is plain text, diffable, linkable, and easy for both humans and agents to scan.

You can put rules, examples, tables, fenced snippets, and links in one place without inventing a format. You can quote the exact lines an agent should follow. You can grep it. You can patch it. You can keep it in the same commit as the code it describes. It is entirely suited for agents to work with.

There are fancier ways to encode knowledge. Some of them are useful. But for repo-level agent instructions, Markdown hits the part of the problem that matters most:

It preserves context in a form the agent can load and use immediately.

The important part is not that the file ends in .md. The important part is that the docs are structured around the way the agent will need to retrieve context.

I think about this the same way I think about [[against-infinite-context|context windows in general]]. More context is not automatically better. Infinite context sounds nice until the agent has to sort through a landfill of half-relevant details.

The better move is scoped context: enough information to complete the task end to end, with as little noise as possible.

That is what a good docs structure gives you:

• the root file says, start here
• the linked docs say, for this kind of change, read this
• the maintenance rules say, when the code changes, update the matching context

Now every future run starts with a cleaner view of the project.

Upkeep is the part people skip

The setup is easy to admire and easy to neglect. You can write a beautiful AGENTS.md, feel organized for a day, then slowly let it rot while the repo moves on.

At that point the docs become worse than missing docs because stale instructions still look authoritative.

That is why I bake upkeep directly into the agent directions. My docs don't politely suggest being updated. They say it as part of the workflow:

Always update relevant docs when behavior changes.
Update the relevant doc in the same commit as the code change.
If AGENTS.md summarizes something and the full doc changes, update both.

This has been the biggest quality-of-life improvement in my own projects. Since building my docs this way, especially around my ag.dev quickstart structure, agent workflows have felt much more seamless.

I spend less time asking for docs to be updated after the fact because the instruction is already part of the loop. I spend less time correcting drift because the agent has a clear source of truth. When an agent enters the repo, it can usually pull the right information without me narrating the architecture from scratch.

That is the part I care about:

Not documentation as ceremony. Documentation as preserved working context.

If the codebase knows how it works, and the docs say where that knowledge lives, an agent can move through the repo with much less guessing. A new developer can also do the same thing, and that overlap is important.

Agent-facing docs should not become weird private prompt junk that only one tool understands. They should make the project feel seamless to work in.

The real standard is the workflow

I don't think there is one universal best-practice shape yet. Maybe there will be. Right now, I think the docs structure should come from the workflow of the repo.

If your project has heavy infra, your env and deployment docs probably matter more. If your project has strict UI conventions, your style and component docs need more weight. If your project has a lot of architectural decisions, decision records need to be easy to find.

The point is not to copy my exact folder and call it done. The point is to make the implicit rules of the project explicit enough that an agent can act on them.

My default recommendation is still simple:

Start with one canonical root agent file.
Keep it light.
Link to focused docs.
Make upkeep mandatory.
Use Markdown because it is cheap, readable context.
Treat drift as a bug.

That last one is probably the whole post.

Treat documentation drift like a bug.

Because in an agentic workflow, docs are not meant for, or even regularly read by, humans. They are meant for the agent, so let's not give our #1 employee a headache.

And once you see docs that way, the maintenance stops feeling optional. It becomes the foundation that lets the rest of the workflow actually work.