Docs-as-runtime: making AI coding agents ship production code

This piece is an outline in progress — the structure is here, the full write-up is coming.

Why agents drift on real codebases

An AI coding agent is only as good as its model of the system it's changing. Point one at a large, real codebase with no structured context and it fills the gaps with plausible guesses — which is exactly where it goes wrong.

The fix isn't a bigger prompt. It's treating documentation as something the agent loads at runtime, not something humans read occasionally.

The context layer

Four artifacts, kept machine-readable and loaded at the start of every session:

Domain model — the entities and how they relate
System invariants — the rules that must always hold
ERD — the data model, explicitly
API contracts — the boundaries between modules

Outline in progress. The full piece walks through how each artifact is authored, kept in sync, and consumed by the agent.

Governance: routing context, not dumping it

A multi-agent governance layer — intent-driven directory hierarchies with trust levels, and AGENTS.md routing contracts that form deterministic context chains — lets agents load only the context relevant to the task.

What changes

Agents reason about the architecture on their own, the specification gaps that cause hallucinations close, and production-grade code ships from sessions that humans review rather than rewrite.