Docs Are Executable Context Now
Docs used to be for humans who never read them. Now your AI reads every word. That flips the economics of documentation: a page nobody opened last year is now injected into an agent's context on every task that touches your codebase. Documentation stopped being a chore for future humans and became executable context — text that directly steers what your coding agent builds next.
Code shows what. It never shows why
An agent (or a new teammate) can read your code and reconstruct what got built. What the code can never show is why: which constraint forced the design, which three alternatives you evaluated, and why you rejected them. Without that, an agent asked to "improve" a module will happily re-litigate a settled question — swapping your deliberately chosen queue for the shiny one you already ruled out.
The fix is a 15-year-old practice with new leverage: the Architecture Decision Record (ADR), introduced by Michael Nygard in 2011. One short file per significant decision, kept in the repo next to the code it governs. Thoughtworks' Technology Radar has held "lightweight architecture decision records" in its Adopt ring since 2018 — and specifically recommends storing them in source control, not a wiki, so they travel with the code. Source control is exactly where coding agents read.
The 10-minute record
Nygard's template is one or two pages, five sections. The lightweight version most teams use today needs four:
| Section | Question it answers | One-liner example |
|---|---|---|
| Context | What forces were at play? | "Bursts of 10k jobs/min; team already runs Postgres, no ops budget for new infra." |
| Decision | What did we choose? Active voice: "We will…" | "We will use Postgres SKIP LOCKED as the job queue." |
| Alternatives | What did we consider and reject, and why? | "Redis (another service to run), SQS (vendor lock-in for a portable product)." |
| Consequences | What gets easier, what gets harder? | "Zero new infra; queue throughput capped by DB — revisit past 50k jobs/min." |
Number the files and never delete one. A superseded decision gets status: superseded by ADR-0012 — the history of changed minds is context too. If you want a maintained, machine-friendly format with YAML front matter, use MADR (Markdown Any Decision Records); it adds optional sections like Decision Drivers and Pros/Cons of the Options.
# ADR-0007: Postgres SKIP LOCKED as the job queue
Status: accepted
Context: 10k jobs/min bursts; team runs Postgres; no ops budget.
Decision: We will use Postgres SKIP LOCKED. No new broker.
Alternatives: Redis Streams (new service), SQS (vendor lock-in).
Consequences: zero new infra; revisit if we exceed 50k jobs/min.Ten minutes to write. It pays out twice: your agent stops re-deciding the question, and the humans stop re-debating it six months later.
Power-user moves
- Point your agent at the folder. Add one line to your agent instructions file (
CLAUDE.md,AGENTS.md, or equivalent): "Before proposing architectural changes, readdocs/decisions/and treat accepted ADRs as constraints." Now every record you write is enforced automatically. - Make the agent write the first draft. After a design discussion in an agent session, end with: "Write an ADR for what we just decided — context, decision, alternatives we rejected, consequences." You edit; the agent drafts. The 10 minutes drops to 3.
- Gate PRs on decisions. A PR that changes a datastore, a framework, or a public API without touching
docs/decisions/should trigger a review question. Some teams encode this as a lint rule or PR checklist item. - Write the rejection, not just the winner. The single highest-value line for an agent is the alternative you rejected and why — it's the only thing that prevents confident regression to the obvious-but-wrong choice.
Resources
- Documenting Architecture Decisions — Michael Nygard (2011) — the original ADR template: title, context, decision, status, consequences.
- ADR GitHub organization — definitions, background, and the hub for templates and tooling.
- MADR — Markdown Any Decision Records — maintained lightweight template with YAML front matter.
- Lightweight Architecture Decision Records — Thoughtworks Technology Radar — Adopt ring; keep records in source control.
- architecture-decision-record — templates and real examples — Nygard, MADR, arc42 and more, plus worked examples.
Building an AI feature? Yeda AI designs, audits, and ships production LLM systems.