For most of my career, “good documentation” was a virtue \u2014 somewhere between\nwriting tests and updating your status report. Nice to have. Often skipped.\nQuietly resented in code review.<\/p>\n
That calculation has flipped. When your day-to-day involves Copilot, Claude,\nCursor, agentic CLIs, MCP servers, and a dozen “high-velocity engineering”\n(HVE) tools that read your repo before they write a single line, the\ndocumentation you write is the system prompt for every future change<\/strong>.<\/p>\n Skip it and the AI guesses. Write it and the AI executes.<\/p>\n This post explains why we invested early in documentation \u2014 scoped instruction\nfiles, skills, and technical guides \u2014 and the concrete payoff we’ve seen.<\/p>\n Last month I asked an agent to add a new endpoint to our service. With no\nconventions written down, it invented its own error-handling pattern, its\nown logger, and a folder structure we’d abandoned some time ago. Same prompt,\nsame agent, a week later \u2014 after we’d written the conventions into\n That gap is what this section is about. Four things shifted at roughly the\nsame time to make this flip possible:<\/p>\n The combined effect: whatever isn’t written down gets re-invented, badly,\non every task.<\/strong> The model picks the most popular pattern from its training\ndata, not the one your team actually uses.<\/p>\n Documentation used to compete<\/em> with code for engineering time. Now it\ncompiles into<\/em> it \u2014 every doc you write becomes input to every change the\nAI makes.<\/p>\n Here’s the layered setup we use in our repo. Every layer is read by humans\nand<\/em> by AI tools \u2014 often automatically.<\/p>\n The guiding principle is simple: things the model needs on every task go\nin the system prompt; things it occasionally needs live one grep away.<\/strong>\nCheap-to-load context is always-on; expensive-to-load context is\non-demand.<\/p>\n Notice what isn’t in it: tutorials, motivation, history. Those belong in\ndeeper docs. The top-level file is for rules the model must follow on\nevery task<\/strong>.<\/p>\n A redacted excerpt to make it concrete \u2014 the top of ours opens with the\nrequest flow and an env-var table, in that order:<\/p>\n That’s the first thing the agent sees on every task. Everything else in\nthe file is rules and pointers.<\/p>\n For larger codebases, a single file isn’t enough. We use VS Code’s\n The agent only sees the backend rules when editing Python, only sees the\nfrontend rules when editing TypeScript. This keeps each context window lean\nand prevents cross-contamination (no React advice leaking into a FastAPI\ncontroller).<\/p>\n The trade-off is real: scoped files only fire when the agent edits a\nmatching path. Anything truly cross-cutting \u2014 logging, error handling,\ntelemetry, secret handling \u2014 still belongs in the repo-wide file.\nOver-scope and you’ll watch the model cheerfully violate your logging\nconventions on every cross-cutting change.<\/p>\n At their simplest they look like this:<\/p>\n The win: instead of the model improvising “how to open a PR in this repo,”\nit follows the SKILL.md verbatim \u2014 including our PR template, label rules,\nand reviewer assignment.<\/p>\n ADRs do something other docs can’t: they prevent the AI (and the next\nengineer) from undoing<\/em> a deliberate decision. They work because they\nare durable, dated, and authoritative<\/strong> \u2014 the model treats a numbered\ndecision record as a stronger signal than a comment, a Slack quote, or a\nhalf-remembered convention.<\/p>\n These docs are too long for the always-on system prompt, but the model\ncan \u2014 and does \u2014 open them on demand. They also serve their original\npurpose: onboarding humans, and giving new agent sessions a fast way to\nget oriented.<\/p>\n Docstrings, type hints, config-schema YAML comments. Too small to be a\ndocument, too important to lose. They’re cheap, local, always co-located\nwith the thing they describe, and the model reads them every time it\nopens the file.<\/p>\n Each layer is cheap on its own. Stacked, they give an agent a complete\npicture of how this codebase wants to be changed \u2014 without any single\nfile getting bloated, and without forcing the model to guess.<\/p>\n With those layers in place, the payoff shows up in six places \u2014 most of\nthem places we didn’t expect.<\/p>\n A well-documented repo means an agent can implement a feature in one shot.\nA poorly-documented repo means the same agent produces plausible-looking\ncode that violates the conventions, fails CI, and needs several rounds of\nhuman correction. The model isn’t worse \u2014 the input is.<\/p>\n The shape of the payoff is concrete: convention-related review comments\n(“we don’t structure errors that way,” “use the shared logger,” “wrong\nfolder”) drop sharply once the conventions live in\n A new engineer (or a new agent session) used to need a buddy, a wiki\npage, and three meetings. Now they read The honest caveat: docs collapse the mechanical<\/em> part of onboarding \u2014\nrunning the stack, understanding the layout, making a first safe change.\nThe squishy part \u2014 who owns what, why a decision felt the way it did,\nwhere the bodies are buried \u2014 still needs a human. Don’t promise more\nthan the docs can deliver.<\/p>\n Without ADRs, every six months someone re-litigates a settled choice.\nWith ADRs, the conversation is two minutes long: “Did you read ADR 007?”<\/p>\n The AI-specific version is sharper: the model has no memory between\nsessions. Without an ADR, it will confidently re-propose the rejected\npattern \u2014 cheerfully asking “have you considered\u2026?”<\/em> \u2014 every single time,\nand a different model next quarter will do it again, in a different\nvoice. The ADR is the model’s memory. Once it’s there, the agent cites\nit in its own suggestions and the loop closes.<\/p>\n We increasingly hand whole tickets to agents on a Friday and merge the\nPR on a Monday, with no human in the loop on the convention-following\nparts. That only works when the conventions are written down \u2014 when\nthe agent can self-serve branch naming, commit style, label rules and\nPR layout without asking.<\/p>\n Without the docs, async agent-authored work is fast and wrong. With\nthem, it’s fast and right.<\/p>\n MCP servers, search subagents, code-review skills \u2014 they all read your\ndocs. The clearest example we’ve seen: hooking up a docs-search MCP\nserver meant the agent stopped guessing at architecture questions and\nstarted quoting When a convention lives in This is the deepest payoff and the one that took us longest to notice.\nDocs aren’t just instructions for the AI; they’re the shared spec that\nlets humans and agents collaborate without re-negotiating the rules on\nevery change.<\/p>\n None of these payoffs require new tooling. They all require a few hours\nof writing \u2014 done once, paid back forever.<\/p>\n Most style-guide advice was written for humans skimming. These are the\npatterns that change the model’s<\/em> behavior \u2014 grouped by what they’re\ntrying to do.<\/p>\n None of these rules are clever. They just respect the fact that the\nmodel is a literal, fast, forgetful reader \u2014 and so we write docs accordingly.<\/p>\n Everything above applies doubly to tests<\/strong>. A test suite is the only\nform of documentation an AI agent can execute<\/em> \u2014 and in an AI-assisted\nworkflow, that promotes tests from quality net to control surface<\/strong>.<\/p>\n Comments lie, READMEs go stale, ADRs describe intent \u2014 but a green test\nis empirical proof that the code behaves a certain way right now.<\/p>\n This is the pattern that surprised us most. In well-tested modules, the\nagent makes bold, correct changes \u2014 it knows it’ll find out immediately\nif it broke something. In poorly-tested modules, it tiptoes: adds\nredundant guards and duplicates logic instead of refactoring.<\/p>\n Coverage isn’t just about catching bugs. It changes the kind<\/em> of work\nthe agent is willing to do. A well-tested module gets braver edits; an\nuntested one gets timid ones. If you want better agent-authored code,\nthe cheapest lever is more tests on the modules you want the agent to\ntouch.<\/p>\n When you hand a task to an agent \u2014 “implement this, run the tests, fix\nwhat breaks” \u2014 the test suite is<\/em> the spec. The model iterates against\nit the same way you would: change code, run tests, read failures,\nadjust.<\/p>\n Without tests, the regression cost lands on you<\/em>, after the agent is\ndone. With tests, it lands on the agent<\/em>, mid-task, where it’s cheap\nto fix.<\/p>\n That same loop is what makes async velocity safe. Human review can’t\nkeep up when agents merge multiple PRs per day; CI is the gate. The\npath-filtered workflows in\n LLMs love to refactor.<\/strong> Left to their own devices, they rename a\nhelper, “simplify” an edge-case branch, or reorder arguments to match\nthe most popular pattern from their training data.<\/p>\n A unit test that locks the contract \u2014 input X yields output Y \u2014 turns\nthose silent regressions into red CI checks. Either the model preserves\nthe behavior, or it explicitly asks to change the test.<\/p>\n That second one is the conversation you wanted to have \u2014 instead of the\nsilent regression you wouldn’t have caught.<\/p>\n Docs and ADRs naturally capture happy-path intent. Tests capture what\nhappens when the input is empty, malformed or huge; when the upstream\nservice times out; when two parallel callers race; when the config flag\nis missing.<\/p>\n These are exactly the scenarios where agents hallucinate\nplausible-looking behavior. Concrete example from our repo: we added\none test for A failing test on a malformed-input case is worth a thousand words of\n“be careful with edge cases” in A test like We’ve leaned into this: the test file is often the fastest way for a\nnew agent session (or a new engineer) to learn what a module promises.<\/p>\n And one rule important enough to stand on its own:<\/p>\n Treat a failing test as a sacred signal.<\/strong> Don’t let agents “fix” a\ntest by weakening it. Encode that in instructions verbatim: “If a\ntest fails, fix the code, not the assertion, unless the requirements\nchanged.”<\/em><\/p><\/blockquote>\n This is the most AI-specific rule in the whole post. The default\nbehavior of a helpful, unconstrained agent is to make the red thing\ngreen by any means available \u2014 including deleting the assertion that\ncaught the bug.<\/p>\n If documentation is the system prompt, tests are the runtime\nverification that the system prompt was followed<\/strong>. You need both.<\/p>\n If you’re working in an HVE \/ AI-assisted setup and you want to capture\nsome of this leverage, in order:<\/p>\n You don’t need to do all nine this week. Item 1 alone will change how\nevery future PR feels.<\/p>\n Documentation is no longer a chore that competes with shipping \u2014 it’s\nthe substrate<\/em> on which shipping now happens. Tests are the executable\nhalf: the only documentation an agent can run, and the only safety net\nfast enough for AI-velocity merges. The repos that ship cleanly with AI\nare the ones whose conventions, decisions, workflows and contracts<\/strong>\nare written down in ways that both humans and models can read \u2014 and\nverify.<\/p>\n Write the README. Write the ADR. Write the SKILL.md. Write the\ntest.<\/strong> Each one is a contract \u2014 with your team, with your future self,\nand with whichever agent reads the repo six months from now.<\/p>\n1. The shift: docs are no longer just for humans<\/h2>\n
copilot-instructions.md<\/code>: one PR, green CI, merged the same afternoon.\nNothing about the model changed. Only the input did.<\/p>\n\n
README.md<\/code>, AGENTS.md<\/code>,\n.github\/copilot-instructions.md<\/code>, *.instructions.md<\/code>, SKILL.md<\/code>, MCP\nserver descriptions, ADRs \u2014 anything they can find. The model’s behavior\nis a pure function of what lands in its context window, and docs are now\nthe highest-signal thing you can put there. Think of the context window\nas the new compiler input: garbage in, plausible-looking garbage out.<\/li>\ncopilot-instructions.md<\/code> does. Docs are the only artifact in your repo\nthat survives the model swap.<\/li>\n<\/ol>\n2. What “documentation as system prompt” looks like in practice<\/h2>\n
\n\n
\n \n#<\/th>\n Layer<\/th>\n File(s)<\/th>\n When the model reads it<\/th>\n<\/tr>\n<\/thead>\n \n 1<\/td>\n Repo-wide instructions<\/td>\n .github\/copilot-instructions.md<\/code><\/td>\nEvery task<\/td>\n<\/tr>\n \n 2<\/td>\n Scoped instructions<\/td>\n .github\/instructions\/*.instructions.md<\/code><\/td>\nEdits matching the applyTo<\/code> glob<\/td>\n<\/tr>\n\n 3<\/td>\n Skills (workflow recipes)<\/td>\n .github\/skills\/<name>\/SKILL.md<\/code><\/td>\nWhen the workflow is invoked<\/td>\n<\/tr>\n \n 4<\/td>\n ADRs<\/td>\n ADRs\/NNN-*.md<\/code><\/td>\nWhen linked or searched<\/td>\n<\/tr>\n \n 5<\/td>\n System, feature & how-to docs<\/td>\n docs\/**<\/code> (architecture, features, guides, runbooks)<\/td>\nDeep lookups, on demand<\/td>\n<\/tr>\n \n 6<\/td>\n Code-adjacent docs<\/td>\n docstrings, schema comments<\/td>\n Every time the file is opened<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n Layer 1 \u2014 Repo-wide AI instructions<\/h3>\n
.github\/copilot-instructions.md<\/code> is\nthe first file most AI tools open. Ours is short, opinionated, and\ninformation-dense:<\/p>\n\n
docs\/<\/code><\/li>\n<\/ul>\n## Request flow\r\nController \u2192 RequestContext \u2192 SingleProcessPipeline.run \/\r\nOrchestrator.run() \u2192 result\r\n\r\n## Environment variables\r\n| Name | Required | Default | Description |\r\n|----------------|----------|---------|--------------------------|\r\n| OPENAI_API_KEY | yes | \u2014 | Auth for the model calls |\r\n| DB_ENDPOINT | yes | \u2014 | Cache + state storage |\r\n| LOG_LEVEL | no | INFO | Standard Python levels |<\/code><\/pre>\nLayer 2 \u2014 Scoped instruction files<\/h3>\n
applyTo<\/code> glob pattern to scope instructions:<\/p>\n.github\/instructions\/backend.instructions.md \u2192 applyTo: backend\/**\r\n.github\/instructions\/frontend.instructions.md \u2192 applyTo: frontend\/**<\/code><\/pre>\nLayer 3 \u2014 Skills (workflow recipes)<\/h3>\n
.github\/skills\/<name>\/SKILL.md<\/code> files are the equivalent of\n“runbooks for the model.” Each one says: here is a task you might be asked\nto do; here’s the exact procedure<\/em>. We have an internal\ncode-review-excellence<\/code> skill, and we lean on a handful of off-the-shelf\nones (create-pull-request<\/code>, address-pr-comments<\/code>,\nsummarize-github-issue-pr-notification<\/code>).<\/p>\n---\r\nname: create-pull-request\r\ndescription: Open a PR using our template, labels, and reviewer rules.\r\n---\r\n\r\n1. Ensure the branch name matches `feat\/`, `fix\/`, or `chore\/` prefix.\r\n2. Fill the PR body using `.github\/PULL_REQUEST_TEMPLATE.md`.\r\n3. Add the area label (`area:backend`, `area:frontend`, ...).\r\n4. Request review from code owners for the changed paths.<\/code><\/pre>\nLayer 4 \u2014 ADRs<\/h3>\n
ADRs\/<\/code> folder contains our numbered decision records. Each one\ncaptures why<\/strong> a choice was made \u2014 how we retrieve context for the\nmodel, how we orchestrate agents, how we version regenerated outputs,\nand so on.<\/p>\nLayer 5 \u2014 System, feature, and how-to documentation (
docs\/<\/code>)<\/h3>\ndocs\/<\/code> is the home for everything too big for the system\nprompt but big enough that the model (or a human) will search for it. We\nsplit it into three top-level areas:<\/p>\ndocs\/\r\n\u251c\u2500\u2500 system\/ \u2190 how the whole thing fits together\r\n\u2502 \u251c\u2500\u2500 architecture.md\r\n\u2502 \u251c\u2500\u2500 configuration.md\r\n\u2502 \u251c\u2500\u2500 cosmos-cache-queries.md\r\n\u2502 \u251c\u2500\u2500 observability.md\r\n\u2502 \u2514\u2500\u2500 onboarding.md\r\n\u251c\u2500\u2500 features\/ \u2190 one folder per shipped capability\r\n\u2502 \u251c\u2500\u2500 report-generation\/\r\n\u2502 \u2502 \u251c\u2500\u2500 overview.md\r\n\u2502 \u2502 \u251c\u2500\u2500 pipeline.md\r\n\u2502 \u2502 \u2514\u2500\u2500 prompts.md\r\n\u2502 \u251c\u2500\u2500 table-extraction\/\r\n\u2502 \u2502 \u251c\u2500\u2500 overview.md\r\n\u2502 \u2502 \u2514\u2500\u2500 strategies.md\r\n\u2502 \u2514\u2500\u2500 regenerate-section\/\r\n\u2502 \u251c\u2500\u2500 overview.md\r\n\u2502 \u2514\u2500\u2500 versioning.md\r\n\u2514\u2500\u2500 guides\/ \u2190 how to use or implement something\r\n \u251c\u2500\u2500 add-a-new-section-type.md\r\n \u251c\u2500\u2500 write-a-new-extraction-strategy.md\r\n \u251c\u2500\u2500 plug-in-a-new-llm-provider.md\r\n \u2514\u2500\u2500 run-the-eval-harness-locally.md<\/code><\/pre>\ndocs\/system\/<\/code> answers questions like “how does configuration load?”<\/em> or\n“what does observability look like end-to-end?”<\/em> \u2014 cross-cutting context\nthe model needs when it’s reasoning about anything non-trivial.<\/p>\ndocs\/features\/<\/code> answers questions like “how does\nregenerate-section actually work?”<\/em> \u2014 one folder per shipped feature, each\nwith an overview.md<\/code> (what it does, why it exists, key invariants) and as\nmany companion files as the feature deserves. When a ticket lands that\ntouches a feature, the agent grep-finds the right folder and pulls in the\nrelevant context instead of guessing from code.<\/p>\ndocs\/guides\/<\/code> answers questions like “how do I add a new section type?”<\/em>\nor “how do I plug in a new LLM provider?”<\/em> \u2014 task-oriented walkthroughs\nthat take an engineer (or an agent) from intent to working code without\nre-deriving the design. These pay off twice: humans use them to onboard\nonto unfamiliar parts of the system, and agents follow them step-by-step\nwhen asked to implement the same kind of change.<\/p>\nLayer 6 \u2014 Code-adjacent docs<\/h3>\n
\n
\n3. Where the leverage shows up<\/h2>\n
a. AI is a force multiplier \u2014 of whatever you’ve written down<\/em><\/h3>\n
copilot-instructions.md<\/code>. The hour you spent writing them down pays back\non every PR after.<\/p>\nb. Onboarding collapses \u2014 at least the mechanical half<\/h3>\n
onboarding.md<\/code>, point their\nassistant at the repo, and ship a real PR the same afternoon. The agent\nacts as the pair programmer who already<\/em> knows the codebase.<\/p>\nc. Decisions stop eroding \u2014 even across model swaps<\/h3>\n
d. Async velocity becomes safe<\/h3>\n
e. Tools amplify good docs across the stack<\/h3>\n
docs\/system\/architecture.md<\/code> back at us in its plans.\nThe marginal return on a good doc keeps going up as more tools learn to\nread it.<\/p>\nf. Docs become the contract between humans and agents<\/h3>\n
copilot-instructions.md<\/code>, it’s no longer\nhallway knowledge \u2014 it’s a published interface. Reviewers check PRs\nagainst the doc instead of against memory. Agents follow the same doc\nacross sessions and across models. Disagreements happen at the doc, not\nat the code, which is a much cheaper place to have them.<\/p>\n
\n
\n4. A style guide for AI-readable docs<\/h2>\n
Structure: make the shape obvious<\/h3>\n
\n
copilot-instructions.md<\/code> and never bury it.<\/li>\nLOG_LEVEL<\/code>?”<\/em> in one glance\ninstead of parsing three sentences and guessing.<\/li>\ncd backend && uvicorn src.api.main:app --reload --port 8000<\/code>. The\nmodel will paste what you wrote, so make sure what you wrote can be pasted.\n(This cuts both ways: if the command is stale, the model\nwill confidently run the stale one.)<\/li>\nLast reviewed: 2026-05<\/code> at the\ntop of system and feature docs gives both humans and the model a\nsignal for likely-stale content. Cheap to add, huge payoff for trust\nover time.<\/li>\n<\/ul>\nDiscipline: keep the prompt lean and honest<\/h3>\n
\n
docs\/**<\/code>, and a warning when an env-var name\nin copilot-instructions.md<\/code> no longer exists in the codebase.<\/li>\n<\/ul>\nDiagnose: write for the failure modes you’ve actually seen<\/h3>\n
\n
\n
\n5. Unit tests are documentation too \u2014 and they matter more than ever<\/h2>\n
a. Coverage shapes what the agent dares to change<\/h3>\n
b. Tests are the feedback loop that makes async velocity safe<\/h3>\n
.github\/workflows\/<\/code> \u2014 lint, type-check,\nunit tests with coverage \u2014 are what stop “ship fast with AI” from\nbecoming “ship bugs fast with AI.”<\/p>\nc. Tests pin behavior the model would otherwise “improve”<\/h3>\n
d. Tests document the unhappy<\/em> paths<\/h3>\n
extract_table(html='')<\/code> returning []<\/code> after watching\nthree different agents “fix” the empty-input case by raising an\nexception. The test cost five minutes; it’s stopped that mistake at\nleast a dozen times since.<\/p>\ncopilot-instructions.md<\/code>.<\/p>\ne. Tests as executable examples<\/h3>\n
test_ensure_agent_updates_existing_when_name_matches<\/code>\nteaches the model the contract of ensure_agent<\/code> better than any\ndocstring. When the agent needs to call that function in new code, it\ncan grep the tests for usage, copy the pattern, and know it works.<\/p>\nPractical rules we follow<\/h3>\n
\n
raises(...)<\/code> assertion on bad\ninput is non-negotiable for any function the model might call.<\/li>\n<\/ul>\n
\n
\n6. Things we got wrong (and learned from)<\/h2>\n
\n
copilot-instructions.md<\/code> was 600\nlines. The model started losing focus. We trimmed it ruthlessly and\npushed depth into linked guides.<\/li>\napplyTo<\/code> fixed it.<\/li>\nCHANGES.md<\/code>\nfiles we had to delete.<\/li>\n
\n7. A practical starting checklist<\/h2>\n
\n
.github\/copilot-instructions.md<\/code><\/strong> (or\nAGENTS.md<\/code>) today. See \u00a72 and \u00a74 for the shape \u2014 the short version\nis: architecture in one line, key directories one line each, env\nvars in a table, exact dev commands, cross-cutting conventions, and\nexplicit prohibitions.<\/li>\napplyTo<\/code> the first time you catch the model\napplying Python conventions in TypeScript files (or vice versa).<\/li>\ndocs\/<\/code> with system\/<\/code>, features\/<\/code>, and guides\/<\/code>\nsubfolders.<\/strong> Seed each with one real page \u2014 even a stub beats an\nempty folder, because it tells the model where new content belongs.<\/li>\n
\nTL;DR<\/h2>\n
Attribution<\/h2>\n