Original URL: https://getagenttools.com/blog/agents-md-is-not-your-documentation/

# Your AGENTS.md is a router, not the whole project documentation

20 Sep 2026Marek.

- agent-documentation
- context-engineering
- claude-code

Your AGENTS.md or CLAUDE.md file is not your project's documentation. It is a router that tells an agent where the documentation lives, and the day you start treating it like the encyclopedia itself is the day it starts to rot.

 

The failure mode is always the same. An agent hits a gotcha, someone fixes it, and the fix gets written down in the one file guaranteed to load before anything else happens. A year of that and the file is not documentation anymore. It is a timeline: what the project is, how to deploy it, a style opinion left over from a model nobody runs anymore, a rule written after one bad night, all filed in arrival order instead of by subject. None of it is wrong. It is just stored in the one place that cannot afford to hold all of it.

 

- **The bloat pattern.** Why a file that has to load every session ends up as the dumping ground for everything, instead of a description of anything.
- **The router in practice.** What a short entry file backed by a set of topic pages looks like after months of actually running it, not just describing it.
- **What OpenWiki automates.** An open source LangChain project that builds and keeps the same kind of structure current without a person filing anything by hand.
- **The verdict.** Who should adopt that automation, and who already gets the same result from a folder of files and one habit.

  

## Why the entry file keeps growing

 

The growth is structural, not a discipline failure that belongs to any one person. AGENTS.md or CLAUDE.md is the one file an agent is guaranteed to read before it does anything else, which makes it the obvious place to put a fact you need the agent to know without being asked. So every fix earns a paragraph. A bad deploy earns a rule written in capital letters. A confused agent earns one more clarifying sentence, added right where the last one was added, because that is where the file was already open.

 

None of those additions look wrong by themselves. Stacked for a year, they add up to a file that no longer has a subject. It has all of them: what the project does, how to ship it, which library is banned, what happened in March, arranged by when someone thought of it rather than what it is about. I went through exactly that kind of file once it had already grown past the point of being readable, sorting its loudest rules into categories in [an earlier audit](https://getagenttools.com/blog/claude-md-audit/). That post is about grading a file after the fact. This one is about the structure that keeps a file from getting there.

 

The newer wrinkle is that an agent can now save a lesson on its own, mid-session, without a person opening an editor. Claude Code's version of this does not add that lesson to CLAUDE.md. It writes to a separate memory file, capped at 200 lines or 25 KB, kept outside the repository and read alongside the router file rather than folded into it, with its own topic files behind it that only load when a task needs them. That is the router pattern showing up one layer down: even the model provider chose to keep what an agent learns in its own place instead of growing the file every session reads first.

 

An unpleasant read is the smallest part of the cost. Every session pays for the whole thing in context before the actual task starts, whether that task touches any of it or not. And because the file is also the path of least resistance for writing something down, outdated statements end up sitting right next to current ones with nothing to tell them apart.

 

## What a router is supposed to do

 

A router does not hold the answer. It says which of several places holds the answer, then gets out of the way. Applied to a project's documentation, that means the entry file states what the project is in a sentence or two, lists where the rest lives by topic, and stops there. An agent debugging a webhook does not need the file to also carry next month's content plan. An agent planning content does not need the webhook wiring loaded either. Keeping those apart means a session only pays for what the task actually touches.

 

| Dimension | Flat entry file | Router-first entry file |
| --- | --- | --- |
| What it holds | Everything, in the order it was written | A short description, plus links to topic pages |
| Over time | Grows, because every fix adds a paragraph | Stays roughly the same size |
| Session cost | The whole file loads regardless of the task | The file plus whichever topic pages the task needs |
| Old vs current facts | Sit side by side, hard to tell apart | Live one per page, easier to correct in place |

 

There is a second cost beyond tokens. A model reading one long, undifferentiated file has to hold irrelevant sections in mind while it looks for the lines that matter to the current task, and a retired instruction sitting three screens away from a current one is exactly as easy to follow as the current one, because nothing on the page marks it as retired.

 

None of this is a new idea wearing a new name. It is closer to how a well-run internal wiki already works: one entry point, links out, and pages that each own a single subject instead of one page trying to be the whole site. The difference with an agent's entry file is that nothing about it is casual browsing. It gets read cold, at the start of a task, by something that has to decide in the first few lines whether it needs to go look somewhere else.

 

## What this looks like when you actually run it

 

In a system I maintain for my own work with AI agents, the file the agent reads first is short, and pointing is close to its only job. Instead of holding everything, it names the areas the knowledge is organized into:

 

```text
entry file
  -> product positioning
  -> current status
  -> architecture
  -> integrations
  -> content backlog
  -> project system
  -> workflow
  -> content plan
  -> repo sync
```

 

Each of those is a folder, not a single page, and together they now hold more than a hundred documents behind that one entry file. Any folder with more than a handful of documents keeps its own one-line index, and any new document gets a one-line entry in that index the same day it is written. I have never used an automated tool to run this. It is manual, and it mostly holds together, except on the days a document goes in fast and the index line gets skipped.

 

When something new needs recording, a decision, a fact, or a change to how something works, it goes into the folder it belongs to, not back into the entry file. That single rule is the whole mechanism. The file that loads every session stays close to the size it started at, while the actual body of knowledge keeps growing behind it, past a hundred documents and still growing.

 

The alternative could hold the exact same information. One big file can contain everything those documents contain, just arranged by when it was written instead of what it is about. Same knowledge, worse retrieval: an agent working on integrations would have to load the content plan and the workflow notes to reach the integrations material buried between them. A router-first layout means that agent reads the integrations folder's index, the document it points to, and the short entry file. Nothing else.

 

What it costs is a small decision every time you learn something new: which folder this belongs in, before writing it down, instead of appending to whatever file happens to be open. Once the topic boundaries exist, that decision takes seconds. But the boundaries have to exist first, and someone has to actually hold the line when the fast option is one more paragraph in the file that is already open in front of them.

 

Move a repeatable task procedure into [a reusable Codex skill](https://getagenttools.com/blog/codex-skills/) and check it loads from the intended scope.

 

## What OpenWiki automates

 

A public thread on X by [@MAXIMISEART](https://x.com/MAXIMISEART/status/2079602871763345456) pointed me to an open source project from LangChain called OpenWiki, in the repository [langchain-ai/openwiki](https://github.com/langchain-ai/openwiki), that automates a version of the same idea for codebases, and does it more thoroughly than a hundred hand-written pages maintained by one person ever could on their own.

 

Where a hand-maintained set of topic pages depends on a person noticing that a fact belongs on a specific page, OpenWiki reads the repository itself: directory layout, dependency manifests, configuration, git history, whatever documentation already exists. It writes a wiki from the position of someone meeting the project cold, organized by subject the way a person would organize an internal wiki, except generated instead of typed by hand.

 

The part that matters most for the router argument is not the first pass. It is what happens after. Per LangChain's write-up on the project, when the underlying repository changes, the agent maintaining the wiki does not regenerate everything from scratch. It looks at what the change touched and updates only the pages affected by it. That is the automated version of the same discipline behind the folders above: new information goes to its specific page, not into one growing file. Here, a coding agent decides which page that is, instead of a person doing the filing by hand.

 

## The metadata and changelog layer

 

A later release of the same project, OpenWiki 0.2 per the same source, adds pieces that a hand-run set of topic pages usually goes without. Each page carries standardized metadata, a structured header describing the page's role and what it relates to, so a page's function is legible without reading the whole thing. Every directory gets an automatically generated index, so a folder of pages does not depend on someone remembering to update a table of contents. And the wiki as a whole keeps a changelog: a running record of what got added or revised, and when.

 

That changelog is the piece I have no equivalent for in my own setup. When an agent needs to catch up on what changed recently, reading a short log is a different cost than re-reading the pages themselves to guess what moved. I rely on remembering roughly what I touched and when, which holds up across a hundred-plus documents maintained by one person and would not hold up across a much larger set maintained by several.

 

## Where the automation earns its cost

 

A codebase with a large enough surface, an active enough commit history, and more than one person or agent touching it, changes faster than any single maintainer can keep a hand-run wiki honest. In that setting, an agent that watches the repository and updates only the pages a change actually touches is doing filing work that would otherwise fall to whoever has time, which in practice means it falls to nobody and the documentation drifts. The metadata and the changelog on top of that are what let another agent trust the wiki without re-verifying it first, which matters more as more agents read from it.

 

This is also the setting where several agents can be working from the same wiki at once. A stale page one of them wrote from does not just slow a person down later. It feeds a wrong assumption straight into whatever that agent builds next, and the changelog is what lets the next agent notice the page moved before it acts on the old version.

 

## Where the manual version is enough

 

A one-person, one-agent setup does not have an update problem large enough to justify a background agent watching the repository, no matter how many documents have piled up behind the entry file. The folder structure above is past a hundred documents and still runs on one rule enforced by habit: new knowledge goes to its topic, not to the entry file. That habit costs nothing to run, and it has not needed anything smarter than that to keep working as the count grew.

 

Standing up an auto-updating wiki adds a moving part instead: something that can fail quietly, something to babysit, in exchange for solving a filing problem a habit was already solving for free. The signal worth watching for is not how big the project has gotten. It is whether keeping pages current has actually become the bottleneck, meaning changes arrive faster than one person can file them, versus the entry file simply having grown large enough to feel uncomfortable, which a habit fixes on its own without any automation at all.

 

Catching drift does not need tooling either, at that pace. Reading through a folder's index every so often, the way you would reread a short reference before trusting it, finds the same staleness a changelog would flag automatically. It just runs on a slower cycle, and a setup with one or two people filing by hand can afford that cycle.

 

## The verdict

 

Automated or run by hand, the structural claim does not change: the entry file's only job is to route. Held to that job, it stays roughly the same size no matter how much the project has learned, because everything it learns lives one page away instead of one paragraph further down the same file. OpenWiki is that idea built for teams and codebases where hand-filing cannot keep up, with metadata and a changelog on top so other agents can trust what they are reading without re-checking it first. For a smaller setup, the same result comes from drawing a handful of topic boundaries and refusing, every time, to let one more paragraph land back in the file that is only supposed to point the way.

 

Source: a public thread by [@MAXIMISEART on X](https://x.com/MAXIMISEART/status/2079602871763345456), pointing to LangChain's open source [OpenWiki](https://github.com/langchain-ai/openwiki) project and its accompanying blog write-ups.

 

## Frequently asked questions

 

### What goes in AGENTS.md?

 

A short statement of what the project is, the handful of rules an agent cannot infer on its own, such as access boundaries or environment quirks, and links to wherever the rest of the documentation lives by topic. The documentation itself belongs on those pages, not inside the router.

 

### How big should CLAUDE.md be?

 

Small enough that adding one more paragraph feels like the wrong move rather than the easy one. The docs put a number on it: target under 200 lines per CLAUDE.md file, because longer files eat context and get followed less. Past that line the fix is moving a section to a topic page, not shaving sentences. I go through the actual measurement exercise in [the CLAUDE.md audit](https://getagenttools.com/blog/claude-md-audit/).

 

### What is context engineering?

 

Context engineering is deciding what information sits in an agent's context window at each step of a task, instead of assuming that loading more up front is always the safer choice. It covers what loads automatically at the start of a session, what only gets fetched when a task calls for it, and what should not be loaded at all.

 

### Does Claude Code have a memory feature?

 

Yes, but it writes to a separate memory file outside CLAUDE.md instead of appending to it, the same router split this post argues for. See [Claude Code memory](https://getagenttools.com/blog/claude-code-memory/) for the size limits and how it is organized.

Put this into practice

[See the tool list](https://getagenttools.com/tools/)[Train your team](https://getagenttools.com/#training)