Do You Actually Understands Your Codebase?
AI agents can improve code while eroding the shared understanding teams need to debug, evolve, and defend it.
Get the guide to build your first AI agent directly in your inbox on newsletter signup:
Apologies for writing this one with a 1-day delay! Some tight deadlines and my pager ringing in the middle of the night got my time and attention this past week 🙇
I have multiple AI agents finish work before I arrive.
One can inspect a pull request. Another can investigate a test failure blocking me from raising a PR. Another can implement an approved plan and return with a ready-to-review diff
But I have also opened the queue of completed work and realized that the passing build did not solve the actual ticket. Or that the AI tried to reconstruct the whole system instead of solving only the task at hand. In those cases, it removed my implementation effort to move it into review effort.
Let’s focus on how to make good use of AI and avoid the common pitfalls.
In this post, you’ll learn
What codebase cognitive debt means in software engineering
How cognitive debt differs from technical debt and intent debt
Why AI coding agents can improve code while weakening team understanding
How to detect and reduce cognitive debt before it becomes a production or career problem
What Codebase Cognitive Debt Is and Why AI Accelerates It
Codebase cognitive debt is the gap between how a software system works and the team’s ability to explain why it works. AI coding agents increase that gap when they produce changes faster than engineers can review and understand.
Margaret-Anne Storey introduced this idea as part of a Triple Debt Model. Martin Fowler later summarized the framework for software practitioners. The model separates three kinds of software health:
Technical debt lives in code. Implementation choices make future changes harder or riskier.
Cognitive debt lives in people. The team’s shared mental model erodes faster than it is rebuilt.
Intent debt lives in artifacts. The goals, rationale, and constraints behind the system are missing, stale, or trapped inside old conversations.
A team can reduce technical debt by asking an agent to remove duplication, add tests, rename confusing abstractions, and simplify a module. The resulting code may be objectively easier to read. But if the agent made the decisions, the reviewer skimmed the diff, and nobody recorded why one option was chosen over another, the team may still owe more cognitive and intent debt than before.
The code improved. But it’ll be one of these scenarios where history is doomed to repeat itself.
This is why I like focusing now on this cognitive debt vs technical debt. Technical debt limits how easily the code can change. Cognitive debt limits how safely the team can reason about that change. Intent debt limits whether anyone can prove that the change still serves the original goal. Even if the code is easy to change and you understand what it’s doing, you don’t know why you’re doing it.
Thoughtworks Technology Radar Vol. 34 treats managing cognitive debt as a theme across the AI engineering landscape. Its codebase cognitive debt entry carries a Caution recommendation. They warn that weaker understanding makes it harder for developers to guide AI, spot hidden coupling, and steer agents away from architectural mistakes.
That creates a downward spiral, a spiral of bad outcomes that keep growing. The less the team understands, the more it depends on the agent to explain and modify the system. The more it delegates without rebuilding that understanding, the larger the gap becomes.
AI is not creating this as a new problem. Before AI, teams have always lost knowledge when people left, documentation became stale, or an abstraction hid too much. AI changes the speed and scale. A team can now create more changes, across more parts of a system, with fewer moments where a human has to build the complete model first. I’m creating in a month the amount of PRs that I created in a year before.
AI is useful only if you understand the bottleneck.
The Code Can Improve While the Team Gets Weaker
I see the first symptom in code reviews.
AI can prepare several changes while I work on something else. When I reach the review queue, every pull request can have green tests, a plausible summary, and a tidy diff. But they only include the evidence the agent remembered to collect, what the human remembered to point to the AI.
They do not automatically give me the model that connects the change to the rest of the system.
This is the pattern:
Agents increase the number and speed.
Humans review the result more shallowly
Important decisions remain inside a chat, a prompt, or the agent’s temporary context. At best, 1 human knows it. At worst, nobody is paying attention
The team becomes worse at explaining the system, worse at prompting for the next change.
More generated work is used to repair symptoms, so all three debts keep growing.
This is a bad snowball effect. If nobody can explain its behavior, constraints, and failure modes after the agent session disappears, the team has become more dependent on regenerating the explanation later.
Some skeptics may think that this is fine. We can always use AI to explain the system back to us. But then we’ve lost our ability to become the Senior Engineer that guides the AI towards the good path.
We have always traded low-level knowledge for higher-level abstractions. Python developers do not need to reason about every machine instruction. A well-designed abstraction removes unnecessary cognitive load.
The difference is whether the abstraction preserves the concepts the team needs to make the next decision.
We don’t need every engineer to remember every line. But we need the team to know how to verify whether a future change is safe.
But it’s not all bad news. Good agent instructions can reduce the debt. That is useful, but it also reveals the limit of prose instructions. A growing rule file records lessons, yet the model can still miss or deprioritize them. The team also needs to know why those boundaries exist and which ones are important enough to enforce in code.
I learned this while building my AI code-review workflow. A generic reviewer gave me noise. Specialist reviewers became more useful when I combined them. The report did not replace my understanding. It gave me a better place to start rebuilding it.
Maybe you’ve heard that AI cybersecurity attacks need a stronger AI defending the system. We have the same situation here: AI-generated code changes need an even stronger AI reviewing those changes to help the human.
Notice I keep the human understanding as one of the goals. Doing changes faster, more reliably, and more safely are great, but they can’t be achieved with zero human understanding
Automation removes mechanical work. Understanding preserves ownership.