Eighteen months after Komati Commerce, the fictional South African commerce platform in this series, started using coding agents across its teams, the delivery numbers looked excellent. Lead time was down, the change queue was shorter, and defect rates were flat. Then a stock-reservation timeout during a holiday sale took orders offline for most of an evening, and the incident review found something nobody had been measuring.
There were three ways to reserve stock in the platform. One lived in the order service, one in a promotions module added for flash sales, and one in a newer checkout path. Each had been written by an agent, reviewed by a person, covered by tests and merged in good faith. Each worked. Nobody in the room could explain why there were three, which one the checkout used under load, or which team owned the timeout. The code worked, but nobody understood the system any more.
This article is about that gap. It is not about code quality, which was fine. It is about the team's understanding, which had fallen behind the code.
Cognitive debt is not technical debt
Margaret-Anne Storey, a professor of computer science at the University of Victoria, describes this in How Generative and Agentic AI Shift Concern from Technical Debt to Cognitive Debt (February 2026), using a term she notes is gaining traction. Her short version is: "Technical debt lives in the code; cognitive debt lives in developers' minds". Cognitive debt is the shared understanding a team loses when a system changes faster than the people responsible for it can follow.
The idea has an older root, which Storey cites. In 1985, Peter Naur argued in "Programming as Theory Building" that a program is a theory held by the people who build it, and the source code is only a partial record of that theory. When the people who hold the theory leave, the program becomes hard to change safely, even if the code is unchanged.
Coding agents create a new way to lose the theory. Nobody leaves. The theory is simply never formed, because the person who approved each change did not need to understand the whole system to approve it.
Keeping Systems Fit: Technical Debt in the Age of Cheap Code argued that agents make some technical debt cheaper to pay down. Cognitive debt behaves differently. Agents can make it accumulate faster, because they remove the friction that used to force understanding.
How agent speed produces it
Each step in the loop is reasonable on its own, which is why it is hard to see.
An agent makes a fast, local change that is correct. Review reads the diff, and the diff is small and tidy. The tests pass, so the change merges. None of these steps asks whether the system already had a way of doing this, or whether the change connects two parts that were meant to be separate.
Over months, the results build up. Patterns are duplicated, because the agent wrote a new reservation path rather than finding the old one. Coupling becomes hidden, because the promotions module now reads the order table directly. Fewer people can explain any given area. The team relies on the agent more, because it is faster than working it out, and the next change is quicker and understood a little less.
AI code review is a filter, not a sign-off warned about a clean AI review becoming an approval nobody actually gave. Cognitive debt is the long-term version of the same risk, where a series of approvals adds up to a system nobody actually understands.
Three symptoms a map can show
Cognitive debt is in people's heads, so it cannot be measured directly. Three of its symptoms are visible in the code, and the map from part 1 can show them.
Architecture drift. The intended dependencies say the promotions module may call the pricing engine but not read the order table. The actual dependency graph says it does. Drift is the gap between the two. Architecture fitness functions for the modular monolith covers how to turn intended rules into automated checks, and a code graph makes the actual side of the comparison cheap to produce.
Duplicated patterns. Three reservation functions with similar shapes, similar names and the same table writes are a pattern the graph can surface: several nodes that write the same data, or several subgraphs with the same structure. Clone-detection tools find copied text. The graph also finds independent implementations of the same responsibility, which is the more common result of agent work.
Hidden coupling. Some coupling has no import at all. Version history shows files that keep changing together even though neither refers to the other. That change-coupling signal, set against the dependency graph, points to links that exist through a shared table, a shared event or a shared assumption.
None of these signals proves that understanding has been lost. Each one tells you where to ask.
Review gates that preserve understanding
Storey's remedies are practical. They include requiring that at least one person fully understands each AI-generated change before it ships, documenting why a change was made and not only what changed, and holding regular checkpoints that rebuild shared understanding. Komati Commerce turned these into five gates.
- Explain it back. The person approving an agent-written change states, in their own words in the pull request, what the change does to the system and why. If they cannot, the change is not ready. This is the gate that matters most, and for a small, local change it is the only one needed.
- Does it exist already? Before a new function, module or pattern merges, someone checks the map for an existing implementation of the same responsibility. The agent can do the search, but a person accepts the answer.
- Map delta reviewed. For changes that add dependencies between modules, the pull request shows the new edges. The Diagrams as Code series covers how to put architecture diagrams in the pull request. The gate here is narrower: a reviewer must accept each new cross-module edge by name.
- Decision recorded. A new pattern, or a deliberate second implementation, gets a short decision record that says why. Living architecture documentation covers how to keep records like this current without pretending it happens automatically.
- Monthly walkthrough. Each module owner walks one other engineer through what changed in their area that month, using the map. The aim is that at least two people can explain every module.
These gates sit beside the acceptance authority described in Agentic development still needs an acceptance authority. That article asks who decides a change is done. These gates ask whether the person deciding understands what was done.
Measuring without crude metrics
Storey treats the measurement of cognitive debt as an open research question rather than a solved one. That is a reason to be careful with crude measures: a target such as "explain-back comments per pull request" would be met with boilerplate within a week.
Komati Commerce tracks a few signals instead, reviews them quarterly and sets no targets.
| Signal | What it suggests |
|---|---|
| Modules that only one person can approve | Understanding is concentrated and fragile |
| New cross-module edges merged without a named reviewer | Coupling is being added unseen |
| Responsibilities with more than one implementation | Duplication is growing |
| Time an on-call engineer needs to explain an incident path | The theory has gaps where it is needed most |
| Explain-back statements that a second reviewer finds wrong | The first gate is being passed on trust |
The last signal is the most useful and the least comfortable. A sample of explain-back statements, checked by a second engineer, shows whether the first gate is real.
What Komati changed
After the reservation incident, the platform team consolidated the three reservation paths into one, recorded why the flash-sale path had once needed different timeouts, and added a fitness function that fails the build if anything outside the inventory module writes to the reservation table. They then added the five gates, starting with explain-back for every agent-written change and the map delta for every change that touches two modules.
Delivery slowed slightly for about a month. After that, it returned to roughly where it had been, and incident reviews got shorter, because more people could explain what they were looking at.
A checklist
| Question | If the answer is no |
|---|---|
| Can a named person explain each agent-written change in their own words? | Add explain-back as a merge condition |
| Do you check for an existing implementation before accepting a new one? | Make the map search part of the pull-request template |
| Are new cross-module dependencies visible and accepted by name? | Show the map delta and require a named reviewer |
| Do deliberate duplicates have a recorded reason? | Require a short decision record |
| Can at least two people explain every module? | Start monthly walkthroughs with the map |
| Are your intended dependency rules checked automatically? | Add fitness functions for the most important boundaries |
Key points
- Cognitive debt is lost shared understanding. The code can be correct, tested and well reviewed while nobody can explain the system.
- Agents make it accumulate faster because each local change is correct and easy to approve without understanding the whole.
- Three symptoms are visible in code: architecture drift, duplicated responsibilities and hidden coupling. A code map, combined with version history, shows where to look.
- Review gates preserve understanding: explain-back, a check for existing implementations, a reviewed map delta, decision records and regular walkthroughs.
- Track signals, not targets, and check a sample of explain-back statements to keep the first gate honest.
This is part 4 of Codebase Intelligence for AI-Assisted Engineering. Previous: RAG finds similar text. A code graph finds relationships. Next: Change impact before code generation.
Background reading: Margaret-Anne Storey, How Generative and Agentic AI Shift Concern from Technical Debt to Cognitive Debt (9 February 2026), and Peter Naur, "Programming as Theory Building" (1985).
How CloudNala can help
CloudNala helps engineering leaders find and reduce cognitive debt in systems that agents now change every day. We use your code map and version history to locate drift, duplicated responsibilities and hidden coupling, identify the modules only one person understands, and introduce proportionate review gates, starting with explain-back, so your teams keep the theory of the system while they keep the speed.
Work with CloudNala
CloudNala helps organisations move from technology ambition to practical execution across cloud, AI, data, platform engineering and digital services.
Whether you are exploring AI, modernising your cloud environment, building a public-sector digital service, or turning an idea into a working MVP, we can help you shape the roadmap and deliver the next step.
Book a Codebase Intelligence Review or write to us at consult@cloudnala.co.za