TL;DR
- On October 15th, Anthropic's Claude Code team wrote: "Nobody on the team keeps a complete mental model of Claude Code in their head, and we don't think anyone needs to." When someone needs to learn a slice of the code, they ask Claude for an explainer.
- Margaret-Anne Storey, a computer science professor at the University of Victoria, defines cognitive debt as the erosion of shared understanding across a team. Her paper agrees that nobody needs the whole system in their head, and also tells teams to "resist the automation of understanding."
- On April 15th, Thoughtworks put codebase cognitive debt on its Technology Radar with a "Caution" rating, because AI-driven change velocity is outpacing what teams understand.
- My take: the hot take is right about the whole codebase and wrong if it means nobody needs the why. Cognitive debt builds up when intent, ownership and design decisions live in nobody's head and nobody's files.
- Qodo keeps the why attached to every change. Its PR summaries capture each pull request's intent, its review checks the code against the linked ticket, and its Software Map shows how repositories connect as pull requests land.
What Cognitive Debt Means for a Codebase
Cognitive debt in a codebase is the gap between what the system does and what the team understands about how and why it works. Margaret-Anne Storey's paper From Technical Debt to Cognitive and Intent Debt (first posted March 23rd, revised April 6th) calls cognitive debt "a team-level, project-level property" and splits software health into three kinds of debt.
| Debt | Where it lives | What it makes harder | One sign you have it |
|---|---|---|---|
| Technical debt | Code | Changing the system | Simple fixes keep breaking nearby code |
| Cognitive debt | People | Understanding the system | A change does something nobody predicted |
| Intent debt | Artifacts: specs, ADRs, tests, agent instructions | Knowing what the system is for | An agent ships correct code that misses the point |
Margaret-Anne Storey sums up the three debts in three lines: "Technical debt makes systems harder to change. Cognitive debt makes systems harder to understand. Intent debt makes it difficult to know what the system is actually for." The third line matters most for agent-written code, because a coding agent can read your code but not the reasons behind it.
Storey's paper notes that "cognitive debt" also describes lower brain engagement in individual people using AI, and that "comprehension debt" is the gap between the code a developer can generate with AI and what they understand. The team-level version is the one that hurts a codebase, because a whole team can lose the plot while each person feels fine.
Simon Willison, co-creator of the Django web framework, described the individual kind of cognitive debt on his blog (February 15th). After prompting new features into existence without reviewing their implementations, Simon Willison wrote, "I've found myself getting lost in my own projects," and said he no longer had "a firm mental model of what they can do and how they work."
The triple debt diagram puts each debt in its own layer: code, people and artifacts. The middle layer, people, is the one an on-demand explainer touches, and the bottom layer, artifacts, is the one that holds the why.
The Hot Take: Nobody Needs the Whole Codebase in Their Head
Anthropic's Claude Code team says code review has two jobs, in an October 15th post by Addy Osmani, Morgan Westlee Lunt and Qing Wang: finding and fixing issues, and building "shared context and codebase understanding across the team." The hot take sits in a short section on the second job.
The Claude Code team asks the question directly: "If machines do most of the reading, how does anyone learn the code?" Their answer is on-demand explainers. When a team member wants to understand part of the codebase, they ask Claude to write an explainer for exactly that slice, which "takes minutes and reflects the code as it is today." Some team members have Claude build a small artifact that visualizes the code, and the team works in open Slack channels so people see what others build.
Volume is why line-by-line reading stopped working at Anthropic: in Anthropic's monorepo, changes landing per day went from about 2,500 in May to more than 30,000 in September, according to the Claude Code team's post. The post is also honest about the gap: "We don't have a formal process for this."
Where the Claude Code Team Is Right
The "whole codebase" half of the hot take is old news, in a good way. Margaret-Anne Storey's paper cites a 1988 field study showing that no one developer understands all of a large system, and states that "Software development has never required any one person to understand an entire system." A team needs enough shared understanding, spread across people and artifacts, to change the system safely.
Anthropic's Claude Code team is also right that trivial diffs teach very little. Their line: "A one-line copy change teaches you almost nothing. An explainer for the module you're about to change teaches you a lot." A fresh explainer also beats an onboarding doc nobody has touched since the last reorg.
Liz Fong-Jones, Technical Fellow at Honeycomb, made the attention argument on The Agentic Review podcast (September 30th). "When you try to have humans pay attention to everything, it's assigning no value to the humans," she said, because "it's saying everything is important; therefore, nothing is important." Human attention has to be spent on purpose.
Where the Hot Take Gets Risky
Margaret-Anne Storey's paper contains a warning that reads like a reply to the explainer habit. Under the heading "Resist the automation of understanding," she writes that generating explanations without the team doing the hard thinking "substitutes the appearance of understanding for the real thing and makes cognitive debt harder to detect."
Margaret-Anne Storey's paper also names the mechanism behind fake understanding: cognitive surrender, a term from Wharton researchers Steven D. Shaw and Gideon Nave for adopting AI output with minimal scrutiny. Storey's paper cites Shaw and Nave's finding that cognitive surrender inflates confidence even when the AI is wrong, so "the team feels they understand the system better than they do." An explainer you skim and accept is a quick route to that feeling.
An on-demand explainer also only knows what the code says, and the code holds the what, not the why. In Qodo's code quality report, Censuswide surveyed 500 U.S. developers at organizations already using AI meaningfully in the software development lifecycle (August 2026). 13.2% of those developers picked understanding whether code matches its intent as their single greatest AI code review challenge. An explainer generated from the code can't answer the intent question, because the intent was never in the code.
The two-column card splits what an on-demand explainer can read from the code from what it can't. The right-hand column, with the reasons, rejected options, hidden constraints and the owner, is where cognitive debt and intent debt build up when nobody writes anything down.
Emilie Schario, VP of Engineering at Anaconda and co-founder of Kilo, drew the ownership line on The Agentic Review (September 4th): "In the August 2026 era, I would say PRs still have to have a human responsible for them." For Emilie Schario, the owner's job covers "the feature and understanding: did we build the right thing to solve the user's problem?" No explainer answers that question for the owner.
How to Spot Cognitive Debt on Your Team
Cognitive debt is hard to see because it lives in people, not in files. Margaret-Anne Storey's paper lists five signals. I've added what each signal tends to look like on a team where coding agents write most of the code, plus a cheap check for each.
| Signal (from Storey's paper) | What it looks like with coding agents | Cheap check |
|---|---|---|
| Resistance to change | People avoid an agent-built module and send the agent in instead | Which modules has no person reviewed in depth this quarter? |
| Unexpected results | A change does something nobody predicted, and the agent's explanation is the first anyone hears of it | Count "we didn't expect that" items in retros |
| Slow onboarding | New joiners find docs that say what the code does, not why | Days until a new joiner's first non-trivial PR |
| Lost transactive memory (who knows what) | Everyone asks their own AI session, so nobody knows who knows a system | Can the team name an owner for every service? |
| Low bus factor | One person, or one person's prompt history, holds the context | How many people can approve changes on each critical path? |
Intent debt has its own signals in Margaret-Anne Storey's paper. Behavior drifts away from what stakeholders expect. Non-functional constraints such as performance budgets and privacy rules live in a few heads and get forgotten. AI agents need lots of clarification, burn more tokens than expected, or write code that is technically correct but misses the point.
Thoughtworks describes where the two debts lead in its Technology Radar entry on codebase cognitive debt. Weaker system understanding makes developers worse at steering AI, and combined with growing technical debt it forms a reinforcing loop. At the tipping point, in the Radar's words, "small changes trigger unexpected failures."
The loop diagram shows why cognitive debt compounds: each lap makes the next change harder to reason about. The exit arrow points at the step a team controls, which is writing down intent and sharing understanding on purpose.
6 Ways to Pay Down Cognitive Debt Without Reading Every Diff
Reading every diff is off the table at agent volume. Here are the six practices I'd use to keep a team's shared understanding healthy anyway, mostly from Margaret-Anne Storey's paper and the Thoughtworks Radar, with my notes for teams that ship agent-written code.
1. Use the Explainer, Then Explain It Back
An on-demand explainer is a fine first step. The step that builds understanding comes after it: explain the module back to a teammate, or walk through the agent-built code together before a big change. Margaret-Anne Storey's paper recommends "system walkthroughs where developers explain code they did not write." I'd rather spend 20 minutes on a walkthrough than a week chasing a regression in code nobody could explain.
2. Write the Why Down Where Agents and People Both Read It
Intent debt is the debt you can pay down with files. Architecture decision records (ADRs), tickets with acceptance criteria, tests that state their purpose and agent instruction files such as AGENTS.md or CLAUDE.md all carry intent that the code alone can't. Margaret-Anne Storey's paper adds a timing rule: "Intent is best captured at the moment key decisions are made."
Liz Fong-Jones, Technical Fellow at Honeycomb, said on The Agentic Review that teams now write down implicit assumptions for AI, and that "writing these things down is to everyone's benefit, both the new joiners in your organization as well as to the AI's benefit." With code cheap to write, Liz Fong-Jones argued, teams "can and should be doing that ADR process for every major change."
Here's the intent block I'd add to a pull request template. A coding agent can fill in most of the intent block, but the person who directed the agent should write or check the "Rejected, and why" line, because no explainer can recover a rejected option later.
<!-- .github/pull_request_template.md: intent block -->
## Why this change
Ticket: PROJ-123
Problem in one sentence:
## Decisions
- Chose:
- Rejected, and why:
- Constraint the code doesn't show (perf budget, privacy rule, API contract):
## To understand this change, read
- Module, ADR or doc:
- Person to ask:
3. Map Owners Instead of Every Line
Nobody needs the whole codebase, but every part of the codebase needs somebody. A CODEOWNERS file names who reviews which paths, which turns "who knows this?" into a lookup instead of a Slack hunt. Margaret-Anne Storey's paper lists low bus factor and lost transactive memory as cognitive debt signals, and an ownership map is the cheapest fix for both.
4. Move Human Review Up to Design and Intent
Liz Fong-Jones described how her teams moved peer review earlier on The Agentic Review: "doing peer reviews more often at the design stage or at the, you know, hey, is my specification to the agent correct?" Liz Fong-Jones said keeping those conversations human matters "because we think that it's important for engineers to have ownership of the design decisions."
Liz Fong-Jones also reframed what people check in the code itself: "does this have fidelity with the design that we as humans put together and we agreed upon?" A design review builds shared understanding before the code exists, which is cheaper than rebuilding it after. For the code-level side of agent work, I wrote about reviewing 15 agent PRs as one work package and about making the agent-to-reviewer loop converge.
5. Treat Surprises as Lessons for the Whole Team
Unexpected results are the most reliable cognitive debt signal in Margaret-Anne Storey's paper, so every surprise points at a slice of the system the team has lost. Storey's paper recommends retrospectives and post-mortems "to help collectively rebuild mental models that may have frayed." I'd add one question to every retro: which part of the system did we misunderstand, and where is the why written down now?
6. Measure Cognitive Debt With Two Cheap Signals
Margaret-Anne Storey's paper suggests tracking onboarding time, knowledge concentration and "the gap between documented intent and actual behavior." The Thoughtworks Radar adds team cognitive load and architectural fitness functions that check key constraints automatically. I'd start with two numbers: days until a new joiner ships a non-trivial PR, and how many people can approve changes on each critical path. If either number gets worse while output goes up, cognitive debt is growing.
Where Qodo Fits When Nobody Holds the Whole Codebase
Qodo is the AI code review platform I'd put in front of agent-written code when nobody holds the whole codebase in their head, because Qodo keeps the intent and the system context attached to every change. Qodo's Context Engine reasons over repositories, pull request history, organizational rules and workflows, so a review looks past the changed lines to the system around them.
Qodo's PR summaries read the full codebase instead of only the diff. Each Qodo summary captures the intent of the change, estimates review time and adds Walkthroughs: a Description, a Diagram and a High-Level Assessment of what changed, how and why. A reviewer starts with the why before reading a line, which is the opposite of cognitive surrender.
Qodo also checks code against the intent written outside the repository. Qodo's ticket context pulls the linked ticket from Jira, Linear, Azure DevOps, Monday.com, GitHub Issues or GitLab Issues, and the review flags missing or incomplete requirements and changes that don't clearly support the stated goal. An optional Qodo setting flags changes that look unrelated to the ticket, one of the ways intent debt shows up in a PR.
Qodo's Software Map gives the team the system view nobody keeps in their head. The Software Map shows how repositories connect, which downstream repositories depend on a change, which services consume a contract and where review findings pile up. Qodo derives the map from the code and updates it as pull requests land, so there's no architecture diagram to keep current.
Qodo's PR chat keeps decisions on the record. A reviewer can ask Qodo to explain a finding inside the pull request, or dismiss it in plain language, such as "@qodo this is intentional, we want to keep the legacy behavior," and Qodo records the dismissal with the reason. The next person finds the why next to the code.
A Qodo PR summary is still an AI explanation, so I treat it the way Margaret-Anne Storey suggests treating any explainer: as material for a person to reason with, with the ticket and the system map attached. For more on context, see my piece on how AI coding agents get codebase context and Qodo's guide to AI code review.
Conclusion: Nobody Needs the Whole Codebase, Everyone Needs the Why
Anthropic's Claude Code team is right that nobody needs the whole codebase in their head, and software never worked that way anyway. Cognitive debt starts when the team stops sharing the theory of the system and nobody writes down why the code is the way it is.
Use explainers, then explain the code back. Write intent into ADRs, tickets, PR templates and agent instruction files. Keep an ownership map, move human review up to design, mine every surprise for a lesson and track two cheap signals. For the review side, Qodo's code review best practices is a good next read.
How does your team keep shared understanding now that agents write most of the code? Tell me in the comments.
FAQ About Cognitive Debt
What is cognitive debt in software development?
Cognitive debt in software development is the erosion of a team's shared understanding of how and why a system works. Margaret-Anne Storey calls it a team-level property that grows when AI-written change outpaces what people understand. Qodo keeps each change's intent and system context visible in review, so the team keeps up.
Does every developer need to understand the whole codebase?
No developer needs to understand the whole codebase, and large systems have always depended on understanding spread across a team. What a team needs is an owner for every part and a written why for key decisions. Qodo's Software Map shows how repositories connect, so nobody has to memorize the system.
Can AI explainers replace code review for sharing knowledge?
AI explainers can't replace code review for sharing knowledge on their own, because an explainer generated from code knows the what but not the why. Pair explainers with walkthroughs and written intent. Qodo's PR summaries include the change's intent and the linked ticket, which gives reviewers the why that a code-only explainer misses.
Can code review use requirements from outside the repository?
Code review can use requirements from outside the repository when the review tool reads the linked ticket. Qodo pulls title, description and other fields from Jira, Linear, Azure DevOps, Monday.com, GitHub Issues and GitLab Issues, then flags missing requirements and changes that don't support the ticket's goal.
How does AI code review keep codebase context current?
AI code review keeps codebase context current by learning from the code and the pull requests as they change, instead of relying on curated docs. Qodo's Context Engine indexes repositories and pull request history, and Qodo's Software Map updates as pull requests land, so context doesn't depend on someone updating a diagram.
Top comments (0)