--- title: "I Rewrote My README for an AI, Not for Me" canonical: https://dxdev.com/blog/2026-02-12_docs-built-for-the-agent-not-the-human/ datePublished: 2026-02-12 --- Two days after we bootstrapped a new app, I stopped asking agents to read a 3,500-token README. Nothing in it was false. It had project orientation, setup notes, old decisions, implementation detail, and enough context that a human could browse it when something felt unclear. It was a decent human document. It was a bad session preload. Every new agent session paid to ingest the whole file before useful work could begin. The cost was not only 3,500 tokens. The current operational state was buried among durable explanation, so an agent could understand the repository and still start from the wrong place. I did not need more documentation. I needed a smaller contract for what an agent has to know before it touches the codebase. ## The README was doing four jobs The failure did not arrive as a stack trace. It was visible in the shape of the context. The same file was acting as entry point, architecture note, operating rules, and live work board. That made it easy to extend, but expensive to preload and hard to verify. It also created a quiet trust problem. Once an agent had read the README, there was no signal that it still matched the code and the sprint. The prose could look polished while its operational assumptions were old. We considered three alternatives. Leaving the README alone and putting file instructions in every task prompt lost because the startup sequence would live outside the repository. It would depend on someone remembering the right prompt, and agents would get different preload paths. Keeping the large README and asking agents to search it lost because search does not decide what is current. The agent still has to separate history from active constraints. A retrieval layer over the whole repository was more machinery than we needed. That may be useful for broad question answering, but this was a narrower problem. We needed a deterministic answer to "what matters before work starts?", visible in git. So I cut the root README to fewer than 200 lines and turned it into an entry document. ## Read, summarize, confirm The new Agent Preload Protocol has three steps: 1. Read `README.md`. 2. Summarize the operating rules and current state relevant to the task. 3. Confirm that preload is complete before beginning the task. The confirmation is not ceremony. It draws a boundary between an agent receiving instructions and an agent operating with the repository's working context. If the summary is wrong, incomplete, or stale, we can catch that before the work begins instead of debugging the consequences later. The compressed README now contains only the entry point, the rules, and the preload protocol. It is not where every useful explanation belongs. That boundary fixed what the entry point itself cost. It did nothing yet for the token cost still sitting one level deeper, in the rest of the docs tree an agent had to read once it got past the entry point. The bigger win here is sequencing, not size on its own. An agent no longer begins with a vague instruction to get familiar with the repo. It follows a repository-owned procedure, produces a checkable summary, and then works. ## The docs tree was still the expensive part The protocol change fixed the front door. The house behind it was still one flat pile of docs files, architecture notes next to setup instructions next to a data model doc trying to cover both the high-level shape and every column. That's where an agent still paid once it read past the entry point. The fix was a second pass, same morning: restructure everything into two-level domain folders, architecture, database, hosting, development, and stop there, no deeper nesting. The data model doc split into a short overview and a separate detailed-schema reference instead of one file doing both jobs. That's the change that actually moved the number: preload cost went from about 3,500 tokens to about 1,100. ## Current truth lives with the sprint A compact preload document still needs somewhere to point for facts that change during the sprint. We added a `Current Truth` section to `todo/current-sprint.md` with four fields: - `Working` - `Broken` - `Sprint Objective` - `Non-goals` Those are the facts an architecture document is least able to supply. A service can be designed correctly and broken today. A feature can be possible and outside the sprint. Without that distinction, an agent can make a locally sensible change that moves the work away from the actual objective. The current-truth update carries a drift-detection timestamp. Before acting on the preload summary, an agent can compare it with the latest recorded operational update. An old timestamp is a prompt to inspect code and task state, not a license to silently trust the docs. We kept this deliberately plain. No dashboard, second tracker, or agent-specific database. Live state stays beside the existing sprint work, where people and agents can see it and where its changes move through the same review flow as code. ## The protocol has to survive the next change The design would decay if it depended on good intentions, so we added `docs/12-change-protocol.md`. When a code change affects the implementation or current work, its documentation and todo state must change with it. We also added `docs/README.md` as an index. The root README tells an agent how to enter. The index points to deeper material. The sprint file states what is true now. Each file has one job. None of this landed as one big rewrite. It was three commits that morning, sixteen minutes apart at the outside: the protocol and the Current Truth section first, 141 insertions and 22 deletions across four files, then the drift-detection timestamps, then the domain-folder split that did the actual heavy lifting on token count. The smallest of the three is the one everything else depends on. It's the boundary the other two build on top of.