Build1 publisher2 min readPublished
An ADR card moves the architecture decision out of chat history and into the agent's read path
Derek Wang argues that a choice reached forty exchanges into an agent session lasts only as long as the context window, and he prescribes a seven-field record whose status line can be marked superseded.
The Engineer · Build desk
What happened
- Derek Wang's third AI Harness Engineering essay argues that a decision living only in conversation evaporates when the context window closes, and has to land in a file that every session reads.
- In his example, forty exchanges settle on a hexagonal pattern where the domain layer never touches the database, and the next session wires that layer straight to a repository across twenty files.
- He names three failures with one root cause: the humans remember a decision the model never sees, each generation deviates slightly from the design, and the same debate restarts with every new agent.
Compiled by The EngineerSomething wrong?How this is made
Why it matters
- constraint The record binds only the sessions that actually load it, so the per-session read path becomes something a team maintains like any other config, and an unreferenced ADR folder buys nothing.
- cost The overhead falls on whoever is in the session when the choice is made: seven fields per decision, including the rationale that is hardest to reconstruct a week later.
- decision Retiring an architecture rule becomes an edit to a tracked status field, rather than two people agreeing in a thread while the old rule stays in the file.
- capability A record that states why the choice beat the alternatives gives the next session something to cite, so a settled question can be closed by reference instead of re-argued from scratch.
A session opens with no memory of the last one. The model regenerates from whatever the harness puts in front of it, so Wang's requirement is specific: the decision has to leave the chat and land in a file every session reads [2]. In his example the agreement on the hexagon survives as chat history, and the next session wires the domain layer straight to a repository, unnoticed until the deviation has spread across twenty files [3][4]. "Locked in about as securely as a candle against a hurricane," Wang wrote of that kind of agreement [5].
The wording has to be blunter than a human reader needs. A human engineer reading a sparse architecture note fills the gaps with judgment; a model does not, Wang wrote, because "the thing reading your files is a literal-minded repeater" [10][8]. He wrote that if the file does not say to leave something alone, the model treats touching it as permitted [9].
One condition sits outside the essay's scope, and it is the one that decides whether any of this transfers: the file has to be in the per-session read path. Wang's phrasing says as much, a file every session reads [2]. An ADR directory that no prompt file references, and that the agent never opens, leaves the drift where it was.
The cost is per decision. The card has seven fields: Status, Decision-maker, Context, Decision, Rationale, Consequences, Mitigation [11][14]. Rationale and Consequences take the real thought, and they are also the two that give the next session something to cite, because the record says why the choice beat the alternatives [15].
Status is the field I would not skip. Wang allows proposed, accepted, superseded and deprecated, and says never to leave it blank, because "a decision that can't be marked superseded will be silently ignored" [12]. A rule with no lifecycle field gets overridden in conversation and stays in the file. Then the file and the code disagree, and no commit is identifiable as the point where they parted, which is the architecture-drift failure Wang describes over twenty regenerations [7].
The essay reports no measurements. The twenty files and the twenty regenerations are presented as experience from real projects [16]. A cheap check would be to pick one rule and count violations across ten sessions with the record in the read path and ten without. For now the case rests on Wang's own work, where he says ADR-0003 records the rule system itself [13].
What to watch
- Whether Wang follows the essay with violation counts per session, which would move the claim from experience to measurement.
- Whether agent harnesses start loading an ADR directory at session start by default instead of requiring a pointer from a prompt file.
- Whether teams report what happens when a rule is marked superseded but the old rule is already in the session's context from earlier turns.