Drift
Architecture doesn’t break in one dramatic event. It erodes — one convenient shortcut at a time. Someone’s under a deadline and imports across a boundary that isn’t supposed to exist, “just for now.” A month later someone else sees that import already there and treats it as precedent. Six months after that, the boundary is gone in practice even though it’s still drawn on the wiki diagram — the gap between prescriptive and descriptive architecture from What is software architecture?, widening one commit at a time. No single change looks like a violation; the sum of them is.
The diagram below shows exactly this kind of shortcut: the same three components, baseline vs. today, with one new edge that a diff would catch on the pull request that introduced it.
Simplified — illustrative, not a complete architecture. The billing → auth edge is a
hypothetical example, matching the one used on the landing page.
This isn’t a cosmetic problem. Research on architectural decay has found that decay metrics predict where bugs and churn land next — components whose structure is quietly eroding are the same ones that go on to accumulate more issues and more change activity later (Le et al., “Architectural Decay as Predictor of Issue- and Change-Proneness,” ICSA 2021; see Research). Drift isn’t just untidy — it’s a leading indicator of where the next outage or the next slow, painful refactor is going to come from.
The usual response is a yearly (or never) architecture review: someone blocks out a week, redraws the diagrams, writes a report, and the structure resumes drifting the moment the review ends. That cadence is too slow for how fast drift actually accumulates — by the time the next review rolls around, months of small shortcuts have already compounded.
The fix isn’t a better review, it’s changing what triggers the check: instead of an audit that happens occasionally, commit a snapshot of the actual as-built architecture and diff every change against it continuously. A single new cross-component edge is a two-line comment when it’s caught on the pull request that introduced it. The same edge, discovered eight months and forty commits later during a review, is an afternoon of archaeology to even explain why it’s there.
In arcade-agent: arcade-arch-diff --update-baseline commits the as-built architecture to
.arcade/baseline.json in your repo on every merge, and the same command diffs a pull request’s
architecture against that baseline, posting the result as a markdown comment — see
CI. This site’s own baseline, diffed on every one of its own PRs, is published live
at Self x-ray.