Documentation That Scales: Constitution, Contracts, and Runbooks
Documentation drift looks harmless until you try to ship a change at 1 a.m. and spend fifteen minutes deciding which conflicting note deserved to be true. I hit that wall after handing more work to AI agents. They read every doc literally, so contradictions turned into slowdowns and risk.
The fix was not "write more documentation." The fix was deciding that every word falls into one of three roles and lives in a known place in the repo. Anything else gets deleted.
Documentation drift wastes time
Before this system, I had:
- Three Markdown files describing navigation, all slightly wrong.
- A roadmap that drifted into architecture guidance.
- How-to notes that mutated into contracts.
Every edit meant chasing references across /docs hoping nothing contradicted production. That overhead compounds the moment someone else, human or agent, needs clarity.
Three files, three jobs
All documentation now lives as Markdown in /docs. Each file declares its own role in the frontmatter so agents and humans can filter quickly. The buckets:
- Constitution (
docs/constitution.md). The non-negotiables: dual-output rule for HAL, no em dashes, router invariants. Any change requires explicit approval. - Contracts (
docs/contracts/*.md). Each file mirrors one subsystem such as navigation, analytics, brand tokens, or content schema. It states what exists today and the interface another system can rely on. No future tense, no runbook steps. - Runbooks (
docs/runbooks/*.md). Markdown checklists paired with the relevant contract. They capture cadence ("roll analytics 05:00 UTC"), commands, verification steps, and rollback notes.
If a note does not clearly belong to one of those files, it either moves into the backlog or the trash. That ruthless scoping keeps the doc tree small enough to read end-to-end when onboarding someone new.
How it fits into the repo workflow
- Every PR that changes behavior edits the matching contract and, if needed, the runbook in the same commit. The constitution only changes when leadership decisions change.
- Contracts and runbooks link to each other instead of duplicating steps, so a navigation change updates
docs/contracts/navigation.mdonce and points to the single runbook. - AI task briefs include direct links. Agents see the constitution first, then the contract, then the runbook. No guessing, no “best practices” overrides.
Why AI work gets faster
Agents fail in two predictable ways: assuming generic conventions or optimizing locally while breaking an invariant. The constitution tells them what never moves, the contract tells them what exists now, and the runbook tells them how to operate it. That structure took PR review cycles from three passes to one because there are no hidden rules.
What’s next
Now that the doc system behaves, I can safely extract a multi-brand token layer, wire a CMS, and expose more automation to collaborators without turning documentation into sludge. The guardrails are simple: keep each Markdown file in its lane, link to the canonical source instead of copying, and never merge a behavior change without updating the doc that defines it.