Diagrams can't keep up — so make them move with the code

Part 12 ·

The reason a C4 diagram is worth drawing is speed: it lets you have the "will this actually work?" conversation early, before the money is spent. That is the Agile feedback loop applied to architecture — and it's the same lesson the industry learned, painfully, moving from waterfall to iterative delivery. But there's a flip side that has arrived only recently and hits hard. AI now lets us change code so fast that the diagram is out of date before it's finished. This post is about both halves: why fast feedback is the whole game, and why AI has broken the refresh rate of diagrams — plus what to do about it, which is not "try harder to keep them updated."

Why fast feedback is the point

Rewind to the origins. Software development in the 1960s and 70s formalised into methods like SDM and, more famously, the waterfall: a big up-front design, fully specified, signed off, then handed down phase by phase to implementation. There's a lovely irony here worth knowing. The 1970 paper everyone cites as the origin of waterfall — Winston Royce's "Managing the Development of Large Software Systems" — actually presented that strictly-sequential flow as the naïve version, and then argued you must iterate, do it twice, and build in feedback because you will never get the design right on the first pass.1 The industry adopted the diagram and ignored the caveat.

And what happened was exactly what Royce warned about: you'd finish a phase, discover you hadn't thought of everything, and have to climb back up to fix the plan before implementing. Teams went dark for months to produce a small deliverable, and only then got feedback. The Agile Manifesto in 2001 was the corrective — value working software and responding to change over comprehensive up-front specification, and get feedback early and often.2 The core economic claim is simple: the cost of discovering a design is wrong grows the longer you wait to discover it. So you want the "is this a workable solution? are we forgetting people who'll have an opinion?" conversation to happen as early and as cheaply as possible.

That is precisely what a C4 picture buys you. A diagram everyone reads the same way lets you run that conversation in an hour instead of a quarter, so you don't burn time and money building something that turns out not to be needed. Fast, shared understanding is the feedback loop.

Why AI broke the refresh rate

Here's the catch. The same AI that speeds up building also outruns our ability to keep the pictures true. Code now changes fast enough that a diagram is stale by the time it's drawn. This isn't a vague worry; the evidence is piling up from several directions at once.

The volume of change is way up, and its character has shifted. GitClear's analysis of hundreds of millions of lines of code finds that as AI assistants took hold, code churn rose sharply and the share of copy-pasted or cloned code climbed while refactoring ("moved" code) fell — more code, changing faster, with more duplication.3 The 2024 DORA report found that AI adoption raised individual productivity and throughput of code — while, at the same time, being associated with reduced software delivery stability.4 And in a randomised controlled trial in 2025, METR found experienced open-source developers were actually 19% slower on real tasks in their own mature repositories when using AI tools — even though they believed they'd been sped up by 20%.5 Read together, these don't say "AI is bad." They say the rate and shape of change have moved in ways our documentation habits were never built for, and our intuitions about it are unreliable.

But — and this is the load-bearing observation — the change is not uniform. The rate of change differs by altitude. At the highest level of abstraction, systems are fairly stable: very few projects wake up and replace their entire system landscape overnight, so a context diagram is usually still roughly correct months later. At the code level, it's the opposite: pull requests carry huge volumes of change in short windows, and AI has poured fuel on that. This is Lehman's laws of software evolution in modern dress — real-world software must change continuously to stay useful, and its complexity increases over time unless active work is done to reduce it.6 The low-level detail churns; the high-level intent drifts slowly. And uncontrolled, that drift has a name: Perry and Wolf called it architectural erosion and drift back in 1992 — the gap that opens between the intended architecture and the one the code actually implements.7

The fix isn't discipline — it's derivation

The instinct is to solve this with willpower: everyone agrees to keep the diagrams updated. It fails every time, for a structural reason rather than a moral one — updating a diagram is never on the critical path. The PR merges whether or not the box moved. Any process that depends on remembering to do off-path work loses to deadline pressure.

So the answer follows directly from the altitude observation. Because the code level changes fast, that level should be derived from the code, by a tool, on every run — never drawn by hand. A synchronisation pass reads the codebase and updates the structural facts and the new deployable artifacts, so the picture moves with the code instead of lagging it. And because the high level changes slowly, the human effort belongs there — on the intent, the boundaries, the meaning that the code can't tell you (which is the subject of the next post). The two meet in the middle: the machine keeps the facts current; the human keeps the meaning current; and the tool's job is to reconcile them without silently throwing either away.

A re-run's review: one new element proposed as an addition, one no longer seen by extraction — flagged, never silently deleted, because it was hand-authored

That reconciliation is the actual product. A re-run has to propose additions rather than impose them, treat removals as questions rather than deletions, and never discard what a person curated by hand. Get that right and generated diagrams become something you trust and keep; get it wrong and people run the tool exactly once. The goal isn't a diagram that's manually maintained — it's a diagram that's continuously true because the fast-changing part is derived and the slow-changing part is deliberately authored.

Rules of thumb

  1. Optimise for the early conversation. A diagram's job is to make "will this work?" cheap — that's the Agile feedback loop, and it's most of the value.
  2. Never rely on discipline to keep diagrams current. Off-path work loses to deadlines, always.
  3. Derive the fast-changing level. Code-level structure should be extracted on every run, not hand-drawn.
  4. Author the slow-changing level. Intent and boundaries change slowly and can't be generated — spend human effort there.
  5. Distrust the speed-up feeling. AI's productivity gains are real in places and illusory in others; measure change, don't assume it.

CRAYON-C4 is built around this split: a CLI and extension derive the structural skeleton from a repository, and a non-destructive merge keeps human curation intact across re-runs.

Next, and last in this arc: the one thing derivation can never recover — why. Code tells you what and how; it can't tell you why you chose it. That gap is where the model earns its keep, and where it becomes the best context you can hand an AI.

References

Footnotes

  1. Winston W. Royce, "Managing the Development of Large Software Systems," Proceedings of IEEE WESCON, 1970, pp. 1–9. Presents the sequential model and then argues it is risky and must be iterated. Paper (PDF) ↩

  2. Kent Beck et al., Manifesto for Agile Software Development, 2001. agilemanifesto.org ↩

  3. GitClear, AI Copilot Code Quality: 2025 Research (analysis of 150M+ changed lines): rising code churn and a multi-fold increase in duplicated/cloned code alongside declining refactoring. gitclear.com ↩

  4. Google Cloud DORA, Accelerate State of DevOps Report 2024: "AI adoption significantly increases individual productivity … However, it also negatively impacts software delivery stability and throughput." dora.dev ↩

  5. METR, "Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity," 2025. Randomised trial; developers were 19% slower with AI yet estimated a 20% speed-up. arXiv

    .09089 · metr.org ↩

  6. M. M. Lehman, "Programs, Life Cycles, and Laws of Software Evolution," Proceedings of the IEEE, vol. 68, no. 9, 1980, pp. 1060–1076 — the laws of continuing change and increasing complexity. Paper (PDF) ↩

  7. Dewayne E. Perry and Alexander L. Wolf, "Foundations for the Study of Software Architecture," ACM SIGSOFT Software Engineering Notes, vol. 17, no. 4, 1992, pp. 40–52 — introduces architectural erosion and drift. ACM ↩