Descrição do Conteúdo / Informações:
-------------------------------------------------------------------------
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.



The decision that survived a lunch break


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.



Three kinds of rot, one hole


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 single source of truth, pointed at the model


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.



The seven fields that make a record hold


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.



The loop comes back as Swarm-Fed ADR


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.



Written is not enforced


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.