Visualizations are the best way for a human to review a large code change.

I converged on this several weeks ago, but somehow never wrote about it.

Here's the simple mental model. The human brain is ultra-powerful compared to the model. Unless you're doing some very advanced low-level machinery, though, that power shows up mainly when it comes to the big picture.

So, to review a 10K+ LOC pull request, or an entirely new feature, the only way to use the human brain efficiently is to present that big picture to it.

Of course, this will not replace ordinary code reviews. Bugs do creep in from time to time. And various agents — humans and AIs — are good at digging deep and hunting them down. But, all in all, those are details.

Simply put, I believe agents are already good enough that, in a good engineering team today, the density of bugs per feature — or per line of code — is actually lower than in most software products shipped over the past few decades. So our code is not perfect, but local bugs are certainly not a problem per se.

What is a problem is complexity creep and architecture slop. Agents appear to endorse it, and even, to a certain degree, long for it. They are too bureaucratic, and too focused on showing some result, no matter how ugly things are behind the scenes.

And it's this ugliness that we, humans, have to protect our codebases against. My CEO calls it "architecture slop," and it's a good term.

Figuring out what is essential and what is architecture slop is no easy task. For every precisely targeted question, the agent will have a perfect answer. And reading all the code is already infeasible.

So my solution here is twofold. First, best architectural practices. Second, visualizations.

For best architectural practices, the dataflow-first, events-first, CQRS + CRDT + actor-model way of thinking has never let me down. I need to understand what follows from what. What downstream events can asynchronously affect upstream components. What the acceptable and unacceptable not-quite-right states of the data are. What the failure modes are. And when I ask the model to explain the dataflow from this angle, and to write targeted tests focused on component isolation and logical ordering, things do come together quite nicely.

But visualization is separate, and it's a damn superpower. If a feature takes ~days, then allocating ~hours to have it plot itself as a nice diagram is far too revealing to pass up. Especially if this diagram is code-first — as in, not a description of what is 𝑚𝑒𝑎𝑛𝑡 to be, but a description of what it 𝑖𝑠. And doubly so if the diagram is ℎ𝑦𝑑𝑟𝑎𝑡𝑒𝑑 — that is, it shows how real data, usually from tests or benchmarks, flows through the system, with interactive drill-down capabilities.

I'm not sure I can explain this well in text, and all the examples I have today are proprietary. I'll share one right away as soon as something open comes up.

The moral is that good engineering and architecture practices are not dead. They remain extremely useful. We just need to apply them inward — to find better ways for us, humans, to understand and manage the complexity of what we are building and shipping as we speak.