--- title: "Your documentation is source code now" url: "https://toddpaulbrownjr.com/writing/your-documentation-is-source-code/" author: "Todd Paul Brown Jr." description: "** About 40% of the game's 104,912 documentation lines exist so the agent can read itself back into context — measured proof that docs are source code now." kind: "article" updated: "2026-09-26T02:50:47+00:00" --- # Your documentation is source code now I have 81,707 lines of production C++ for [a game in development](/builds/game-in-development/). The repo also holds 104,912 lines of Markdown across 381 files — 1.28 documentation lines per line of code. That ratio sounds backwards until you understand what those docs are doing. About 40% of that documentation exists so an agent can read itself back into its own working context at the start of a session. Not for a human maintainer. For the machine. This happened in March 2025, about the same time Google Cloud and OpenAI were converging on orchestration as its own architectural layer — what would eventually be called a harness — and several months before Anthropic named it one. I was building around the same architecture the industry was still naming, writing documentation that would let an agent pick up where it left off without me having to re-explain the entire system every morning. In a plain-language layer, the prose is the source and the C++ is the compiled artifact underneath it. ## The measurement On 20 September 2026, I ran a full inventory of that game project. The numbers above — 81,707 lines of C++, 104,912 lines of docs — are measured, not estimated. The C++ was written across 157 prompts in the two weeks when about three-quarters of it was produced, totaling roughly 53,000 typed characters of direction from me. The rest traces to a two-day scaffolding burst in July whose session transcripts no longer exist. The agent also wrote 30,069 lines of automated-test C++. Those tests run inside Unreal Engine's own test harness and check the gameplay systems the agent built — collision, health, combat, movement, all of it. The tests pass. The defects that actually mattered still surfaced only when I played the packaged build with a controller in my hands. The documentation-to-code ratio is real. It is also the point. ## What the docs contain The largest bucket is context recovery: design decisions, system constraints, what worked and what failed in earlier attempts, which approaches I've already rejected and why. When Claude Code starts a new session, it has no memory of yesterday's work. The documentation is how it learns what this project is, what it's trying to do, and what mistakes not to repeat. A second bucket is the decision log. I recorded 250 product decisions across those 79 calendar days — choices about combat feel, progression gates, UI patterns, controller bindings. Every one of those decisions went into Markdown so the agent would stop proposing things I'd already said no to. A third bucket is architecture notes: how the systems connect, what each subsystem owns, where state lives, and which boundaries must not be crossed. The agent writes the code, but I set the structure. The docs hold that structure in a form the agent can read. The fourth bucket, smaller but necessary, is the stuff a human would use: build instructions, known issues, test-run procedures. That part looks like normal project documentation. It is maybe 20% of the total. ## The shift Traditional documentation explains code that already exists. You write the program, then you write the README so someone else can understand it later. Agent documentation runs the other direction. I write the documentation first — the design intent, the constraints, the decisions — and the agent generates the code that satisfies it. When the code drifts or a test starts failing, the agent reads the docs to figure out what the code was supposed to do and fixes it back into alignment. The prose is the spec. The C++ is the output. This is not a metaphor. When I want to change how the combat system behaves, I edit the Markdown file that describes combat, then I tell the agent to reconcile the code with the updated doc. It reads the change, finds the mismatch, writes the C++, writes the tests, and commits it. The workflow is: update the documentation, then compile. ## The failure that taught me this In April 2025, I tried building LEGION — my AI delegation system — with agents in Docker containers. The agents would edit code, run tasks, respond to requests. It worked until the containers restarted. Every time a container wiped, the agent lost its work and had to start over. No memory, no continuity, no idea what it had been doing five minutes earlier. I also had no handbook the agent would actually read. It would ignore instructions, edit the UI into black text on a black background, refuse tasks it didn't like. I tried adding rules, but rules an agent has to remember are suggestions. The agent agreed with everything and forgot it the next minute. The fix was state that survived the session and a handbook the system read by default, not on request. Documentation became load-bearing infrastructure, not a nice-to-have. The game project runs on the same principle. The docs are not notes. They are the program the agent executes. ## What this looks like in practice Here's a real example. The game needed a damage-resistance system — different armor types reduce different damage types by different percentages. I wrote a Markdown file describing the rules: physical resistance caps at 75%, magical resistance has no cap but scales logarithmically, resistance values stack additively within a type but multiplicatively across types. I pointed the agent at that file and said: implement this. It wrote the C++ struct, the calculation functions, the getters, the Unreal reflection macros. It wrote 14 test cases covering edge cases I didn't think to specify — zero resistance, over-cap values, negative inputs. It committed the whole thing with a message explaining which doc it was implementing. Two days later, I changed my mind about the stacking rules. I edited the Markdown. I told the agent: the doc changed, reconcile the code. It read the diff, rewrote the calculation function, updated six of the tests, and committed again. The code is not the source of truth. The Markdown is. ## The part nobody talks about Documentation drift is the silent killer of every measured claim in this space. I have found stale test counts in three unrelated projects this year — a proofreading app, an interactive-fiction engine, a different game — and every single undercount went the same direction. Not once has a project's documentation claimed more tests than the repo actually holds. The game's own stats drifted once. The first draft of my 20 September measurement report understated several figures and had a pattern-matching bug that miscounted decision-log entries. A second pass with fresh context caught it before anything published. If a document states a number instead of deriving it, assume it is already behind. The fix is not writing better summaries. It is writing fewer of them and generating the ones that are just facts. LEGION's state panel pulls test counts, commit hashes and deployed versions directly from the repos at render time. No typed number, no drift. ## Why 40% is the right ratio When I say 40% of the documentation is written for the agent, I mean it literally. I measured it. The context-recovery files, the architecture notes, the decision log — those exist because the agent has no long-term memory and I will not spend my morning re-explaining a project I've been building for three months. A human maintainer might skim those files once, then work from the code. The agent reads them every session, sometimes multiple times in the same session when it needs to check a constraint or recall a rejected approach. The documentation is not supplementary. It is load-bearing. The agent cannot build without it, and I cannot delegate without the agent. The 1.28 lines of docs per line of code is not overhead. It is how the system runs. ## What the receipts show The [receipts page](/receipts/) lists the measured figures: 81,707 production lines, 30,069 test lines, 157 prompts across the window that produced three-quarters of the C++. The game itself is in development, playable, under playtest. The status word is accurate. This is not vibe coding without verification. The tests exist, the docs exist, the commit log is public on my [GitHub](https://github.com/toddpaulbrownjr). The numbers survive scrutiny because they were measured, not estimated, and every claim is labelled with what it actually covers. Documentation as source code is not a metaphor. It is a measured discipline with a test suite and a word count.