Every AI coding agent I have used starts a session the same way: it greps around, reads a handful of files, forms a partial model of the codebase, and starts editing. Sometimes that partial model is right. Often it is missing the one detail that mattered — why a table exists, why a flow was built the way it was, which pattern to copy for something new. The agent does not know what it does not know, so it guesses, and the guess is usually plausible-sounding and occasionally wrong in a way that is expensive to unwind.
I ran into this directly while rebuilding parts of this site's own consulting and course infrastructure with an AI agent doing most of the implementation. The fix was not a smarter agent or a bigger context window — it was two markdown files.
The problem with “just read the code”
A codebase encodes decisions, but it does not encode why. Reading core/handlers/checkout.go tells you that a $0 course purchase skips Razorpay entirely and records a synthetic order ID. It does not tell you that this was a deliberate choice — the alternatives (rejecting $0 purchases, or routing them through a fake Razorpay order) were considered and rejected, because forcing a “free” enrollment through a payment gateway that cannot process a $0 order is broken by construction. That reasoning lives in a commit message, if it is written down at all, and commit messages are not something an agent reads before making an edit three months later.
The same problem shows up at a larger scale. Which of the existing checkout flows should a new paid product copy? The course flow (pay-what-you-want, optional $0, the most complex of them)? The booking flow (fixed price, reserves a real resource, has to hold a slot)? Without a document that names one of them as the pattern to copy and says why, an agent has to reverse-engineer that judgement call from separate files, and it will not reliably reach the same conclusion twice.
There is a sharper version of this failure, and this project has an example of it. For a while there was a third flow — a fixed-price Architecture Review self-checkout — and the architecture document named it as the simplest one to copy. That flow has since been removed; the table it wrote to is kept read-only so the admin payments ledger still shows historical purchases. An agent following guidance that was accurate when written would now be copying code that no longer exists. Which is the entire argument of this post, turned on its author: the document is only load-bearing if it is corrected the moment reality moves.
Living docs as a retrieval layer, without the retrieval infrastructure
Retrieval-augmented generation solves a version of this problem for large, unstructured document sets: embed everything, retrieve the relevant chunks at query time, feed them into the model's context. It is the right tool when the corpus is too large to fit in context and too unstructured to summarise by hand.
A single mid-sized codebase's concepts — as opposed to its full source — usually are not that large. What I actually needed was not semantic search over 15,000 lines of Go; it was two documents an agent could read in full, once, at the start of a session, that answered “what does this product do” and “how is it built” without requiring sixty separate file reads to reconstruct. That is not RAG in the literal sense — no embedding model, no vector store, no retrieval step. It is the same underlying idea (give the model exactly the context it needs, not the entire corpus) implemented as the simplest possible version of itself: two files, checked into the same repo as the code they describe, versioned by the same git history.
Concretely, this project keeps docs/FUNCTIONALITY.md and docs/ARCHITECTURE.md as the first thing any agent working on the codebase is expected to read:
- The “what” document — every feature, organised by who can use it (visitor, logged-in user, admin), with the business rules spelled out in prose next to the flow they govern. Not “here is the Purchase struct” but “here is why a $0 purchase never touches the payment gateway, and here is the exact cookie that proves access afterward.”
- The “how” document — package layout, a full entity-relationship diagram, the request lifecycle, the auth model, and, critically, an explicit statement of which pattern to copy for common extension points.
What makes this work as agent context, not just documentation
Plenty of projects have a README that technically describes the architecture and is still useless to an agent, because it was written once, went stale within a month, and nobody trusts it enough to rely on it. Three things make the difference between decoration and a real context source:
- Update it in the same commit as the change it describes. Not “eventually,” not “in a follow-up doc pass” — the same commit. If a change adds a table, it also adds the table to the ER diagram. This is a discipline problem, not a tooling problem, but it is the one that determines whether the docs stay trustworthy. The removed checkout flow above is what the failure looks like in practice.
- Write for “an agent with zero prior context,” not “a teammate who already knows 80% of this.” Spell out the non-obvious decisions explicitly, in prose, next to the thing they explain. An agent that has to infer intent from a struct definition alone will infer wrong at least sometimes. An agent that is told the intent directly will not.
- Separate “what” from “how.” A feature question (“does the site support partial refunds?”) and an implementation question (“which table holds refund state?”) get answered by different documents, read for different reasons, updated on different triggers. Collapsing them into one giant file makes both harder to keep current and harder for an agent to know which part is relevant to the task in front of it.
The actual payoff
The honest version of this claim is not “the agent never makes mistakes now.” It is narrower and more useful: the class of mistake that comes from not knowing the codebase's own rules — reinventing a pattern that already exists, missing a business rule that is not visible in the code it happened to read, guessing at “why” instead of being told — drops sharply. The agent still has to reason about the specific task. It does not have to reverse-engineer the last six months of decisions to do it.
For a solo-maintained codebase especially, this doubles as documentation for a future human maintainer — including a future version of yourself, six months removed from the reasoning, asking the same “wait, why does this work this way” question the agent would have asked.
If you are building anything with an AI agent doing real implementation work, this is close to the highest-leverage thing you can add before the next session starts: not a bigger prompt, not a more capable model, but two files that tell it what you already know — and the discipline to fix them the day they stop being true.