Blog

We’ve all been there: a production outage happens, and the team spends most of the crisis call just trying to figure out how the services are connected and what they actually do. The bug itself takes second place. The real culprit? A slow, silent loss of shared understanding. If your team doesn’t truly get the system, you cannot change it safely.

What Does “Comprehension” Really Mean?

It’s not just reading the code. As Peter Naur famously said, a program is more than its source – it’s the mental “theory” in the developers’ heads: the why behind the what. When that theory stays locked inside one or two people, the system becomes fragile. Margaret-Anne Storey adds that this creates two hidden burdens: cognitive debt (lost shared understanding) and intent debt (lost reasons for decisions). Both erode quietly, and unlike performance or uptime, they don’t trigger alarms until it’s too late.

---

Three Modern Forces That Destroy Shared Understanding

1. Decentralization & Silos – When teams split to move faster, each group masters its own small piece. But the big picture fades. People stop knowing why boundaries were drawn in the first place, and local theories drift apart.
2. Team Churn – When veterans leave, they take chunks of the “theory” with them. Newcomers inherit code but not the historical context. Lacking the original rationale, they often make quick patches instead of sound improvements, slowly degrading the architecture.
3. GenAI (the fastest force) – AI writes code in seconds, which is great, but it also steals the learning that used to happen during design, implementation, and testing. That hands-on effort was what built a developer’s mental model. Today, you can ship a feature without ever really understanding it – and that debt surfaces later, often during a client demo when you can’t explain your own work.

---

How to Spot That You’re Losing Comprehension

You can’t just ask “does everyone understand?” – but you can watch for warning signs:

• Pull Requests that are too large – knowledge can’t flow through a massive diff. Break them down.
• Reviews are a formality – if only a few people review, or if seniors never get challenged, approval becomes meaningless.
• “Let’s wait for Dave” – a low “truck factor” means critical knowledge sits with one person.
• Onboarding takes forever – if new hires struggle to contribute meaningfully, the system is too opaque.
• Missing “why” in docs – changes that touch core parts without an explanation of rationale.
• Domain leakage – when changes in one area break something unrelated, local reasoning is broken.

Some of these can be automated (e.g., blocking huge PRs), but others just need regular human attention. Treat metrics as triggers for conversation, not as hard gates to game.

---

The Human Checkpoint: Don’t Let AI Be the Only Reviewer

A human reviewer isn’t there just to catch syntax errors – they are there to hold the theory. This is a “comprehension checkpoint,” not merely a quality gate. Design reviews matter even more than code reviews now.

Crucially, there is a big difference between pre-hoc understanding (thinking through the problem before the code is written) and post-hoc understanding (trying to figure it out afterward). Pre-hoc keeps you in control of the design; post-hoc often leaves you with the LLM’s average, generic solution, not one tailored to your domain.

So, delegate boring grunt work to AI, but for the complex core, require the engineer to explain the change in their own words – in the PR description or commit message, written manually. That friction is a probe: if they can’t write it clearly, they haven’t truly grasped it.

---

Keeping the Shared Model Alive

Individual understanding is good, but it’s not enough. That knowledge must flow to the rest of the team – especially across service boundaries, where behavioral contracts (idempotency, retries, ordering) are rarely captured in an API schema. Tools like ADRs and context maps help, but they don’t replace human interaction.

You sustain shared understanding through deliberate habits: pair programming, rotating engineers across modules, and decentralized decision-making that still includes shared governance.

With GenAI, there’s now an extra hop: from the agent to the individual. The comprehension checkpoint ensures that hop works. Then, the usual practices (pairing, rotation, docs) ensure the individual-to-team flow works. Comprehension isn’t a one-off project – it’s a daily discipline, built for the engineer who hasn’t joined the team yet.

---

The Bottom Line

Treat comprehension as seriously as you treat scalability or security. Watch the leading indicators, automate what you can, and bake understanding into your process. If you only discover you don’t understand the system after AI-generated code is already in production, you’ve missed your cheapest chance to fix it. Evolutionary architecture only works if the shared understanding underneath it is deliberately and continuously engineered.