Auto-generating your architecture docs trades one failure for another

Generated architecture docs do not go stale. They go mute. Rebuild the picture from the repository at every merge and it is always current, and it still cannot say why the system is shaped that way. That is the half agents took away, and the half Backthread records: the reasoning behind each merged change, against the part of the system it touched.

Two failures, and only one of them is loud

A written document describes the code to whoever opens it. It is accurate on the day it is typed and ages from that day forward, and the aging is quiet, because a confident sentence reads exactly the same whether or not it is still true.

Ours was wrong about our own product for weeks. The context file our agents load on every session described one of our diagrams as around a thousand nodes. The live version had 75 nodes and 222 edges, and the largest of all 348 versions ever built was 77. Nothing caught it, it mis-scoped a real piece of validation before anyone checked, and the full incident is written up here. A hand-maintained description of a system agents are changing daily rots the way comments rot, except this one gets injected into every session as authority.

A derived map fails the other way round. Rebuilt from history at each merge, it cannot hold a false claim about the shape of the system, because it is not making a claim — it is a projection of what is there. What it cannot do is argue. It will show you that a queue sits between two services. It has nothing to say about whether that was a considered choice, an accident nobody reversed, or a compromise somebody accepted on a Thursday with a release due.

The trade most teams make without noticing

So generation gets adopted to kill staleness, and then the parts that matter get hand-written anyway: the paragraph above the diagram explaining why the boundary is there, the page on which failures are tolerated on purpose. That paragraph ages on precisely the old schedule. The staleness was not removed, it was relocated into the only section anyone reads twice.

The tooling is more honest about this than its users are. Models-as-code tools hold one model and derive many views from it, which genuinely removes drift between the pictures — and the model itself is written and maintained by people. arc42's guidance on decision records asks for the reasons behind a choice, including the alternatives and the cost-benefit trade-offs, one decision per record, never edited after the fact, only amended or superseded. Those are two artefacts with two different half-lives. Treating them as one document is how teams end up with a current picture and a false story about it.

The symmetry is worth stating plainly. A projection is always right and never explains. A description always explains and is right only on the day it was written. Neither is fixable by making the other one better, and no amount of generation produces a rationale, because a rationale is not derivable from the artefact it produced — the artefact only records the branch that was taken.

Where that leaves a diagram

Stop asking the picture to explain, and stop asking the prose to stay current. Derive the structure; attach the reasoning to the change that caused it. A decision has one honest home, which is the pull request or the agent session where it was made, and from there it can be read against whatever the structure happens to be this week. That ordering also makes the familiar annoyance tractable: a map that reshuffles under you at every commit is a layout problem with a measured fix, not evidence that the system changed.

The uncomfortable part, for anyone selling either artefact, is that the derived map cannot carry the thing a new engineer actually needs. We build one, and it is still the wrong place to put a reason. The map answers where; the record answers why; a team that keeps only the first has a current drawing of a system nobody can account for. What we keep alongside the map is the reasoning behind each merged change, because that is the part that stops existing the moment the session closes.

Connect one repo and the next merge starts leaving its reasoning behind it, attached to the area it touched rather than to a document somebody has to remember to update; the trial runs fourteen days.