# A decision you didn't write down isn't a decision > Source: > Published: 2026-09-20 04:09:00+00:00 *AI Harness Engineering · Essay Three · derek wang (derekwang85)* The most expensive failure in AI coding isn't a wrong decision. It's a decision that was made, then forgotten, then quietly unmade by the next generation. Here's the raw version of that law: **a decision that lives only in conversation does not persist.** It evaporates the moment the context window closes. If making it stick matters at all, it has to leave the chat and land in a file every session reads. That file is the architecture layer of the pyramid — the ADR set. In Essay One I gave you the skeleton; in Essay Two the top. This essay is the layer that stops the drift no one notices until it's cost a week. I've lived the failure too many times to count. You and an agent go forty exchanges deep and finally converge: "OK, hexagonal pattern, the domain layer never touches the database directly. Locking that in." It is, in fact, locked in — as chat history. Locked in about as securely as a candle against a hurricane. Next session opens fresh. The model regenerates, nothing tells it the hexagon was decided, so it wires the domain layer straight to a repository. Nobody spots it until the deviation has spread across twenty files. By then the *why* is gone — the reasoning that justified the pattern is buried in a conversation nobody will scroll back through. What you're really watching is this: a conversation is not a contract. It's a one-time instruction stream — no history, no archive, no power to bind the next session. A decision that stays in the chat thread is as good as undecided. Only a decision that lands in a file anyone — especially any future model — must read is actually in force. When decisions have nowhere to live, three distinct failures follow, and I've seen all three in real projects: **Memory drift.** The humans remember a decision; the AI doesn't, because the decision was never written where the model could read it. So every regeneration quietly re-argues a question you thought was settled. **Architecture drift.** Each generation makes a small, innocent-looking deviation from the design. Twenty regenerations later the code sits half a project away from intent, and no single change is identifiable as the point of failure. The boundary didn't vanish — it just stopped being pinned and started being random. **Repeated-argument drift.** Because nothing is recorded, the same debate happens again with every new face and every new agent. Sometimes the same team talks itself into a different answer than it landed on last time — deciding against its own past decision. All three share a single root cause: **there is no authoritative place where "we chose X, and here's why" lives.** Close that hole and all three lose their fuel at once. The fix has a name engineering has trusted for decades: the *single source of truth*. One decision, one authoritative home, everything else derives from it or cites it. In the AI era this stops being good hygiene and becomes load-bearing — because the thing reading your files is a literal-minded repeater. A human engineer reading a sparse architecture note fills in the gaps with judgment and context. A model doesn't. If the file doesn't say "don't touch this," then to the model, touching it is allowed. You can't rely on the reader's discretion; the file has to pin the boundary by itself. That's exactly what an ADR — an architecture decision record — is: a written choice, kept once, that acts as the judge for disputes rather than a note for readers. AI coding makes it indispensable precisely because the previous failure modes are invisible until too late. You don't need a thesis. A workable ADR is a short card holding everything a future engineer — or future model — must know without re-litigating the question: **Status** — proposed, accepted, superseded, deprecated. Never blank; a decision that can't be marked superseded will be silently ignored. **Decision-maker** — who owned it. Even a record of "delegated to the agent" counts. **Context** — the situation that forced the choice. **Decision** — the choice itself, stated without hedging. **Rationale** — why this beats the alternatives. **Consequences** — what it costs, now and later. **Mitigation** — what you'll do when those costs show up. Set that way, the ADR is a self-contained slice of history. The next session reads *decision plus rationale* and understands not just what was chosen but why — so it doesn't silently reopen it. In my methodology project, ADR-0003 does this for the rule system itself: it records how the constitution gets amended, proving the AR format can govern even the rules that govern the project. The counts are real at the actual scale I work at, measured from my methodology repo's `adr/` directories: TradeOMS holds 20 ADRs pinning trade-domain rules agents must not improvise past [ORIGINAL DATA], and SmartQuant opened with 11 the day it started, recording architecture as it stood up rather than after the fact [ORIGINAL DATA]. The point isn't volume; it's that every directional choice has a paper trail. Here's the AI-era twist that turns ADRs from a top-down cage into a learning record. A **Swarm-Fed ADR** is written *by* the working swarm: when a group of agents resolves an edge case during delivery — a decision reached across models and roles, each attacking it from a different angle — that resolution gets promoted into a formal ADR and fed back into the single source of truth. The choice made in the heat of the job becomes a rule the next generation obeys. This is the return channel from Essay One made concrete: the architecture layer constrains from the top, but it also accumulates what the system learns from below. Decisions stop being ivory-tower declarations and become a living sediment of resolved problems. The objection worth taking seriously: an ADR nobody maps back to the code is a diary with nice formatting. I've watched teams file fifty ADRs in a quarter and still drift, because the records were approved and then ignored — never wired to a gate, never surfaced to the AI, read only at the retrospective. Records are inert without enforcement. An ADR binds only when something checks whether the code follows it. A Swarm-Fed ADR binds only when retrieval actually surfaces it before the next generation. And the riskiest habit in AI coding isn't changing a rule — it's changing it for no recorded reason, so a future model reads an un-sourced edit the way it reads an un-sourced comment: as permission. So the habit to build is the counterintuitive one: **before you move a boundary, write the ADR.** It looks like an extra step. It's actually the thing that makes the change legitimate. Write it down in the moment, and you give every future conversation a coordinate origin that never disappears. Tomorrow, one layer down: the contract layer — how you take a spec and make an AI promise, and prove it kept the promise.