Every AI coding agent I've 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's 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 doesn't know what it doesn't know, so it guesses, and the guess is usually plausible-sounding and occasionally wrong in a way that's 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 wasn't 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 doesn't encode why. Reading core/handlers/checkout.go tells you that a $0 course purchase skips Razorpay entirely and writes a synthetic order ID. It doesn't tell you that this was a deliberate choice — the alternative (rejecting $0 purchases entirely, or routing them through a fake Razorpay order) was considered and rejected, because forcing every "free" enrollment through a payment gateway that can't actually process $0 orders is broken by construction. That reasoning lives in a commit message, if it's 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 three near-identical checkout flows should a new "fourth paid product" copy? The course flow (pay-what-you-want, complex)? The booking flow (fixed price, reserves a resource)? The audit-request flow (fixed price, no resource)? Without a document that says "copy the audit-request pattern, it's the simplest of the three," an agent has to reverse-engineer that judgment call from three separate files, and it won't reliably reach the same conclusion twice.

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's the right tool when the corpus is too large to fit in context and too unstructured to summarize by hand.

A single mid-sized codebase's concepts — as opposed to its full source — usually aren't that large. What I actually needed wasn't 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's not RAG in the literal sense — there's no embedding model, no vector store, no retrieval step. It's 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 now 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, organized 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's the Purchase struct" — "here's why a $0 purchase never touches the payment gateway, and here's 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 ("to add a fourth fixed-price product, copy the audit-request pattern, not the course or booking pattern").

What makes this actually 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:

  1. 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 PR adds a table, that PR also adds the table to the ER diagram. This is a discipline problem, not a tooling problem, but it's the one that actually determines whether the docs stay trustworthy.
  2. 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 — not "see the Course model" but "every course defaults to a $0 minimum contribution as of [date]; a positive minimum is an opt-in, not the norm; here's the exact method that renders that as copy." An agent that has to infer intent from a struct definition alone will infer wrong at least sometimes. An agent that's told the intent directly won't.
  3. 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 actually relevant to the task in front of it.

The actual payoff

The honest version of this claim isn't "the agent never makes mistakes now." It's narrower and more useful than that: 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 isn't 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 doesn't 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're 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.