Cognitive Debt Is What Accumulates When Code Changes Faster Than Understanding

Technical debt is the version we already know how to talk about

A team takes a shortcut and usually knows it. Logic gets duplicated where a shared abstraction would have been cleaner. A feature ships on top of a shaky interface because the launch date will not move. A migration planned in three phases stops after the first one.

The debt metaphor works because the team understands both sides of the trade. They know what they borrowed against. They know, at least roughly, where the interest will show up.

Cognitive debt is different.

Cognitive debt accumulates when a system changes faster than the people responsible for it can maintain a working theory of how it behaves. Messy code is a separate problem. So is a backlog of refactors. What cognitive debt measures is the widening gap between three things:

• What the code does
• What the team thinks it does
• What the product requires it to do

That distinction matters because AI assisted development changes the economics of software in a specific and uneven way.

Generating plausible code got cheap. Refactors feel cheap too, and a feature request can become a pull request before the team has clarified what the product actually needs. A developer dropped into an unfamiliar codebase can follow its local patterns and produce something that compiles, passes tests, and reads well in review.

What did not get cheaper is knowing whether the change is correct in the full context of the system.

That cost still lives in places AI cannot reach on its own. Product knowledge. Operational history. Architecture. The customer edge cases someone hit two years ago. Security assumptions nobody has revisited. Team conventions that were never written down.

AI helps where those facts already exist somewhere. It writes tests once the invariants are named. It compares an implementation against a spec, if the spec exists. What stays outside its reach is product intent that no one recorded, business rules living only in someone’s memory, and the fragile dependencies that reveal themselves during an incident and nowhere else.

The result is a new form of debt that looks like velocity at first.

Fig 1 – AI can increase code throughput without increasing the team’s ability to understand the resulting system.

The bottleneck moved

For a long time, a lot of engineering process assumed that code production was scarce.

We planned around how long a feature would take to implement. We estimated tickets and argued about developer productivity. Tooling went into removing friction from local development, CI, deployment, and review. Throughput got measured in stories, commits, pull requests, and releases.

AI changed the shape of those constraints without eliminating them. A developer with a coding agent now generates more of everything. More implementation options. More tests and scaffolding. More migrations, more documentation, more diffs than anyone could comfortably write by hand. The ceiling on output has moved. The ceiling on absorption has moved much less.

Every codebase has what we might call a change absorption capacity. It is the amount of change a system can safely accept before the cost of review, integration, incident response, and future maintenance starts rising faster than the value delivered. Architecture quality shapes it. So do ownership boundaries, test coverage, telemetry, and the shared understanding inside the team.

The Stack Overflow blog post “You shipped it fast. But did you ship it right?” frames this well. AI increases the speed at which teams produce changes. Systems still have limits on how quickly they can safely absorb those changes. The post names four guardrails that help speed become durable rather than fragile:

• Contracts
• Automated verification
• Telemetry
• Simplification

That is the practical version of the cognitive debt argument. Speed on its own is not the risk. Speed without absorption capacity is.

This is why AI can make teams feel faster and slower at the same time.

The sprint board moves. Branches multiply, pull requests land, and prototypes turn into real features. Senior engineers meanwhile spend their days reviewing, explaining, unblocking, and tracing regressions. Product managers watch features arrive quickly and then burn cycles reconciling behavior that is technically implemented and semantically wrong. SREs and support teams inherit systems with more moving parts and less clarity.

The bottleneck moved from typing to understanding.

Engineers describing this shift from the trenches tend to report the same two things. Their own pull requests have gone quiet for weeks, because nearly all of their time moved into reviewing code and helping other teams avoid risky changes. And what they wish they had time for is writing explicit sources of truth about the product domain, so that AI tools and humans both have something precise to follow.

The question was never whether AI could produce code. It was whether the organization could still know what it had produced.

Technical debt assumes understanding

The phrase technical debt gets used too broadly. It has become a bucket for everything unpleasant in a codebase. Outdated dependencies go in, along with brittle tests and confusing abstractions. So do half finished migrations, slow builds, risky deployments, and the features nobody wants to touch.

In its strongest form, technical debt contains knowledge. A team knows that a shortcut was taken, why it was taken, and what would need to be done eventually. The debt is painful and legible.

“We hardcoded this because the partner integration was late.” “We duplicated this logic because the shared service was not ready.” “We skipped the cleanup because we needed to launch before the conference.”

Those are real debts, grounded in a known compromise. They might still become expensive, and the team might still procrastinate until the interest compounds.

Cognitive debt is more slippery, because it accumulates without a clear moment of borrowing. Nobody says, “Today we will reduce our collective understanding of the order lifecycle by 7 percent.” A team simply accepts one generated change that looks fine, then another, then another. A developer merges a refactor they can explain locally but not systemically. A generated test suite raises coverage and misses the domain rules that matter. A feature gets implemented against the literal wording of a ticket while violating the intention behind it.

The work looks complete. The understanding behind it is thinner than the work suggests.

This is why cognitive debt is so dangerous in AI assisted development. The code often looks more polished than the understanding behind it. Style conventions hold, helper functions are the right ones, comments are present, and the tests get updated. In review it passes for good code.

What is missing is the theory that connects the change to the product, the architecture, and the world outside the repository.

Peter Naur’s 1985 paper “Programming as Theory Building” is suddenly very current for exactly this reason. Naur argued that programming is not best understood as the production of program text. The deeper work is building a theory in the minds of the programmers, an understanding of how the program relates to the problem it solves, why the parts sit where they do, and how future changes should fit. Code and documentation matter. Neither one is the theory itself.

AI coding tools push directly on this distinction. They are very good at producing and transforming program text, and increasingly good at navigating text that already exists. Software engineering has always been more than text production, and the rest of it is the maintenance of a living theory about how the system should behave.

When code changes faster than theory, cognitive debt grows.

The illusion of local correctness

One of the hardest things about AI assisted code is that it often fails in ways that are not obvious locally.

The function is clean. The types line up. The endpoint returns the expected shape, the test passes, and the pull request is readable. Something is still wrong somewhere in the system.

The wrongness usually lives in an assumption the code never states.

• A boundary assumption. The code treats a field as always present because the nearby examples make it look mandatory. Production data knows better.
• A concurrency assumption. A retry path looks harmless until a customer is charged twice.
• A domain assumption. Two statuses appear equivalent in code and carry different meanings for fulfillment, billing, compliance, or support.
• A security assumption. An internal caller is treated as trusted, and the internal network turns out not to be the real security boundary.

None of these are exotic AI problems. Humans have always made mistakes like this. What changes is the volume and plausibility of the output. AI generates more locally convincing code, faster, against incomplete context. It also makes it easier for less experienced developers, or for non engineers working in low code tools, to produce changes that pass the first layer of scrutiny.

That creates the illusion of local correctness.

The code looks right in the diff, and it might even be right relative to the prompt. A prompt is rarely the full system. Neither is the ticket the full product intent, nor the visible code the full architecture. The test suite holds a fraction of the invariants the business actually relies on.

This is where “the code is the source of truth” becomes a half truth. Code is the source of truth for what the machine will do. What the system ought to do lives elsewhere.

Code encodes accidental behavior. It preserves legacy compromises no one remembers and bugs customers have quietly learned to work around. It omits the rule everyone on the founding team knew and nobody wrote down.

In a world where code was expensive to change, the friction of implementation gave teams more time to think. Much of that friction was waste, and some of it created natural checkpoints. People discussed design because implementation would take time. They clarified requirements because rewriting was costly. They hesitated before touching risky areas, because doing so required sustained effort.

AI removes a lot of friction, including some friction that quietly served as a thinking checkpoint.

Teams still need to move fast. What they need is friction in different places. Friction that makes assumptions harder to smuggle into production, rather than friction that makes code harder to write.

Fig 2 – Cognitive debt often appears when local correctness hides missing system context.

Cognitive debt shows up as review fatigue

Review used to be a quality gate for code. It is increasingly a quality gate for intent.

The reviewer checks whether the implementation is idiomatic. Underneath that sit harder questions:

• Does the change preserve hidden invariants?
• Did the agent misunderstand a pattern?
• Are the tests meaningful?
• Does the behavior match what the user actually needs?
• Is the diff locally tidy and globally harmful?

That is a lot to ask from a human reading a pull request.

It gets harder when AI assisted changes are large. A fifteen thousand line pull request is an extreme example, and the exact number is beside the point. AI makes it easy to produce diffs whose apparent size exceeds the reviewer’s ability to form a reliable mental model. Even when most of the lines are mechanical, the reviewer still has to know which three lines matter. Until the organization has trustworthy ways to identify risk, the human reviewer remains responsible for the whole blast radius.

This turns senior engineers into defensive infrastructure. Their time goes to protecting the current system from changes that look reasonable and carry hidden risk. They become routers of context, maintainers of tribal knowledge, and last mile interpreters of product intent.

Some of that is healthy senior engineering work. A good senior engineer should raise the level of the system around them. When the ratio flips too far, the work becomes exhausting, because the senior engineer is reviewing code and repeatedly reconstructing context that should have been captured in the delivery system.

That is cognitive debt charging interest.

The organization has debt if any of these are true:

• One person has to review every change in a subsystem, because only they know the real invariants.
• Every AI generated PR requires an archaeology session to determine whether it broke an unstated rule.
• The product can only move safely when a few people hold the whole theory in their heads.

Removing humans from review and hoping AI reviewers solve it does not work. AI review helps with consistency and security patterns. It suggests tests and catches obvious mismatches, and it serves as a useful adversarial reader. An AI reviewer that lacks the same missing product context will reproduce the same failure mode at a different stage.

The deeper fix is to make the theory of the system more explicit and more operational.

Fig 3 – Review capacity becomes the constraint once code is generated faster than the team can read it.

Guardrails are understanding infrastructure

The word guardrails can sound managerial, as if the goal is to restrain developers. That is the wrong frame.

Guardrails are understanding infrastructure. They are the artifacts and feedback loops that help a team preserve its theory of the system while the code changes. Tests. Contracts. Practices. In an AI assisted environment they matter more, because they give both humans and tools something concrete to reason against.

The CATS framework from that same Stack Overflow piece is a useful way to hold this.

Contracts make boundaries explicit. They define the shape of an API or event, and then go further. Field meanings. Ownership. Compatibility expectations. Failure behavior. A contract turns “I thought this was always present” into a testable claim.

Automated verification turns domain rules into executable checks. Generic coverage is not the point, since AI generates plenty of tests for code paths it can infer. The higher value work is naming the invariants humans actually care about:

• Money is not charged twice
• Deleted users do not receive notifications
• Invoices do not move backward in state
• Audit logs cannot be rewritten
• Trial accounts lose paid features at expiry

Telemetry tells the team what the system actually does in production. Code review tells you what the code appears to say. Tests tell you what selected scenarios do under controlled conditions. Only telemetry tells you what real usage, real data, and real failures are doing right now.

Simplification keeps the theory learnable. Complexity is a runtime cost and a maintenance cost. It is also a cognitive cost. A system carrying too many special cases, hidden couplings, and bespoke patterns is harder for humans to understand and harder for AI tools to modify safely.

These practices were valuable before AI. They are becoming load bearing. When code production accelerates, the practices that preserve understanding stop being optional cleanup.

This is the mature version of AI governance for engineering teams. The work is not a policy document naming approved tools. The work is a delivery system that can safely absorb the volume and kind of change it is now capable of producing.

If it cannot, more AI output may reduce net delivery speed.

The leadership trap: measuring the visible thing

Organizations tend to measure what is visible, and AI makes output extremely visible.

Token usage shows up on a dashboard. So do pull request counts and lines changed. So do cycle time, generated tests, and the share of commits that were AI assisted. Those metrics are tempting because they create the feeling of management. Something is happening. A number goes up and to the right.

Visible output and value are different things.

The Pragmatic Engineer’s reporting on “Why is Meta destroying its engineering organization?” is useful as a cautionary case about incentive design. One reported dynamic was that engineers feared low AI usage might be read as poor performance, which encouraged performative usage. Whether or not every detail generalizes beyond Meta, the lesson is broader. When leadership measures adoption, people optimize for adoption.

That is dangerous because cognitive debt hides behind positive looking activity metrics. A team can produce more code and understand the system less well for it. It can merge more changes while incident rates climb. Tickets close faster because the work moved downstream into support, security, and platform teams. Test coverage rises and the invariants that matter stay uncovered.

The same dynamic shows up at the review bar, where AI output optimized for acceptance gets merged under a lighter standard than a human teammate’s pull request would face. The team’s rejection rate on generated code drifts toward zero without anyone deciding that it should.

Engineering leaders need to measure the absorption side of the system as carefully as the production side.

Questions worth asking:

• Are incidents per change going up or down?
• Are rollbacks becoming easier or harder?
• Are reviews taking longer because diffs are larger or riskier?
• Are senior engineers spending more time reviewing generated work than improving the system?
• Are the same hidden assumptions causing repeated regressions?
• Are teams adding contracts and invariant tests as fast as they add AI assisted features?
• Can a new engineer build a useful theory of the system faster than before?
• Are product rules becoming more explicit or more scattered?

These are less glamorous than “How much faster are we coding?” They are closer to the real economics of software delivery.

AI adoption should be judged by system level throughput. If code generation gets 50 percent faster while review, QA, incident response, and maintenance get 80 percent heavier, the organization has moved cost downstream rather than reducing it.

The “Subprime Code Crisis” research synthesis uses similar language. AI assisted coding creates local productivity gains while shifting cost downstream. Into review and QA. Into security and architecture. Into maintenance and the stability of the thing once it is running. That framing avoids both hype and panic. The problem is treating coding speed as the whole delivery system.

The original ShiftMag piece, “CTOs Agree: Cognitive Debt Is the New Technical Debt”, makes a related leadership point. The AI conversation has moved from “are we using it?” to “what are we getting for it?” That shift matters, because ROI cannot be evaluated honestly if the organization counts generated output and ignores the downstream cost of understanding, reviewing, operating, and maintaining that output.

Fig 4 – Absorption signals track whether the team can still carry the system, alongside the production signals that are easier to count.

Product intent is now a first class engineering artifact

One of the most important changes AI brings is that product intent has to become explicit.

For years, many organizations got away with vague tickets because human engineers filled in the blanks. A product manager wrote a story. A designer clarified the flow. An engineer implemented the thing and quietly applied their understanding of the domain, the architecture, the customer, and the team’s past decisions. Where something was ambiguous, the engineer asked, made a judgment call, or followed a convention.

AI tools also fill in blanks, and they use different judgment. They optimize for plausible completion.

• An incomplete prompt leads them to the most common pattern rather than the locally correct one.
• Inconsistent patterns in the codebase lead them to the wrong precedent.
• A ticket describing only the happy path gets exactly that, with the policy rule or compliance constraint left out.

That makes product intent an engineering artifact.

Not every feature needs a fifty page specification. Important behavior needs precise statements of correctness. What must never happen? What states are valid? What transitions are forbidden? Which fields are contractual, which behaviors exist only for legacy customers, and which exceptions are product decisions rather than bugs?

These statements should be useful to humans and machines alike. A good invariant becomes a test. A good contract becomes a schema check. Design notes turn into context an agent can use, and a post incident review can yield both a regression test and a source of truth worth prompting against.

This is where AI can be part of the cure. Agents are good at turning explicit intent into artifacts. They draft tests and checklists. They write docs, migration plans, and contract updates. They scan incidents for patterns and find places where an invariant goes unenforced. Much of the boring machinery of understanding is work they can maintain.

The team still has to decide what is true.

That is the human work at the center of software engineering. It does not go away because code generation improved. It becomes more valuable.

The role of specifications changes

Specs have a bad reputation in some engineering cultures, often for good reasons. They go stale. They turn performative. Many describe an imaginary system rather than the one that exists, and used as approval theater they slow everything down.

AI changes the value of a good spec.

A good spec is a compact representation of intent. It says what matters, what must be preserved, what can vary, and how to tell whether a change is safe. In an AI assisted workflow, that kind of spec becomes executable context.

Practitioners keep converging on this idea from different directions. Some write RFC style definitions of the fundamental rules and invariants that agents must obey. Others use agents to draft normative specs and then run adversarial review loops to improve them. Whether or not every team should adopt that exact workflow, the direction is right. When implementation becomes cheap, specification becomes more valuable.

Big Design Up Front is not the answer. What shifts is the unit of engineering value. Producing code stops being the expensive part, and defining correctness in a way that survives acceleration becomes it.

An AI coding agent can implement a feature many ways. A useful spec narrows that space. It tells the agent, the developer, and the reviewer what must remain true. Review gets a target, tests get a purpose, and whoever maintains this in two years gets a clue.

Cognitive debt has human costs

Cognitive debt is an architectural and operational problem with a human cost.

When a system becomes harder to understand, work becomes more anxious. Engineers hesitate before making changes, because they cannot predict the blast radius. Reviewers become defensive and senior people become bottlenecks. Newer engineers learn to rely on generated code without building deep ownership. Product teams lose trust when small changes cause strange regressions, and operations teams brace for surprises.

AI also creates a strange emotional split in craft. Many engineers enjoy building things and understanding them deeply. If their role shifts too far toward reviewing machine generated output, they feel less ownership and less pride. The efficiency and learning benefits of AI are real at the same time. That leaves an uncomfortable dual experience, where the work feels more powerful and less grounded at once.

Leaders should take that seriously. The point is to preserve the conditions under which engineers can reason about, own, and improve systems. Pride in craft is connected to accountability. People take better care of systems they understand and feel responsible for.

If AI turns engineers into exhausted reviewers of changes they did not shape, trust and morale and ownership will erode alongside cognitive debt.

What to do Monday morning

The answer is not to stop using AI, which would be unrealistic and, in many cases, unwise. AI assisted development is useful. It removes drudgery, speeds exploration, improves local productivity, and helps teams build better supporting artifacts. The question is how to adopt it without letting code outrun understanding.

Start by treating cognitive debt as something observable.

1. Write down the invariants for one critical flow. Pick one product flow and ask the team for the truths, not the implementation details. What must always be true about payments, permissions, identity, fulfillment, or data deletion? Then check whether those truths are enforced anywhere. In tests? Contracts? Runtime checks? Dashboards? Runbooks? Or only in people’s heads?

2. Trace recent incidents back to the missing understanding. Was it a boundary assumption? A domain rule? A legacy behavior? A security constraint? Use the findings to build a small taxonomy of cognitive debt specific to your own organization.

3. Change review prompts and templates. Every AI assisted pull request should make its assumptions visible. What product rules does this rely on? What invariants does it touch? What did the agent infer? Which domain cases were chosen by a human rather than generated?

The same questions work as a launch bar. Our audit team runs a ten check version of this before a vibe coded app ships to real users, and the check that fails most often is the simplest one, whether someone on the team can explain in a paragraph what a given module does and where it could fail.

4. Invest in contracts at brittle boundaries. Where three teams depend on an event or API, document the fields and their meanings, along with ownership and compatibility expectations. Put schema validation in CI where possible. Make breaking changes loud before they reach production.

5. Improve telemetry for business critical states. The system should tell you when reality diverges from intent. A dashboard that catches a 0.3 percent drift in order state transitions is worth more than a beautiful diff that misses the issue.

6. Make simplification part of feature work. Cognitive debt grows when systems become too bespoke to reason about. Do not make refactoring a heroic quarterly project when small simplifications can ride along with everyday changes. AI helps identify duplication. Humans still decide which simplifications preserve the right boundaries.

7. Measure AI adoption by downstream outcomes. Celebrate the teams that reduce review burden and lower incident rates. Celebrate faster rollbacks, clearer ownership, and easier onboarding. Treat code volume and token usage as insufficient signals of system health.

Fig 5 – The safest AI assisted teams measure whether understanding is improving, and not only whether code output is rising.

The real question

Whether AI can write code is settled. It can.

The question that matters is whether your organization can still understand the system it is changing.

When code changes faster than understanding, cognitive debt accumulates. At first it looks like speed. Then it looks like review fatigue. Later it surfaces as incidents, regressions, brittle ownership, and a handful of people carrying too much context. Eventually you have a system everyone can modify and almost nobody can reason about.

That is an argument for taking software engineering seriously in the AI era.

The teams that do well will be the ones that build understanding infrastructure around accelerated change. That means clear contracts and explicit invariants. It means specs worth reading, telemetry worth trusting, and simplification treated as ordinary work. It also means leadership metrics that reward durable delivery over visible motion.

Code is cheaper now. Understanding is still expensive. The organizations that remember that will move faster for longer.