You know what technical debt is. You've felt it: the code that works but resists change, the abstraction that made sense in 2023 but is now a wall between you and shipping, the "temporary" solution that's been in production for three years.
Context debt is the same concept applied to the reasoning behind your code.
Every time an AI session ends without capturing why a decision was made, you accumulate context debt. Every implementation that doesn't explain its constraints. Every architecture choice that lives only in a developer's head, or in a Slack thread, or nowhere at all. That's context debt accruing.
Like technical debt, you pay for it later. Unlike technical debt, it's completely invisible until you hit the wall.
The Two Kinds of Debt
Technical debt has a tell. The code is there; you can see it's messy. A sufficiently motivated engineer can audit the codebase, identify the debt, and estimate the cost to clean it up. It's painful and often deprioritized, but it's observable.
Context debt leaves no trace. The code that resulted from a decision looks the same whether the decision was carefully reasoned or completely arbitrary. You cannot look at a function and know whether the implementation was chosen after evaluating three alternatives, or whether the developer was tired on a Friday and went with the first thing that worked.
This matters more now than it ever has, because AI changes the failure mode.
When a human developer maintains a codebase over time, they accumulate context organically. They remember the reasoning. They learn the constraints. They know which walls are load-bearing, even if it's never written down. This works—imperfectly, but well enough—when the same person is around.
AI development breaks this model entirely. Every session starts fresh. The AI you work with today has no memory of the AI you worked with last month. If the context doesn't exist somewhere accessible, the session begins from zero.
This isn't a limitation to work around. It's a structural property of how AI development works. And context debt is what happens when you don't account for it.
The Compound Rate
Technical debt has a compound rate. The longer you leave it, the worse it gets. A messy abstraction that costs one hour to work around today costs two hours in six months, because other code has grown up around it.
Context debt compounds faster.
Here's why: when a human developer encounters a decision they don't understand, they can reason about it. They can look at the code, think about why someone might have done it this way, make an educated guess, and usually get close enough. This is expensive—good engineers spend a surprisingly large fraction of their time on this forensics work—but it's possible.
When an AI encounters a decision it doesn't understand, it invents a reason. Not with malice, but with confidence. It infers the most plausible explanation from the surrounding code, and proceeds as if that explanation is correct. If the inferred explanation is wrong—if the constraint was unusual, if the decision accounted for something not obvious from the code—the AI will make changes that violate the real constraint, producing bugs that are extremely difficult to diagnose because the failure mode doesn't match any obvious cause.
Context debt compounds because every bad AI decision creates more code that other AI sessions have to reason about, with no more context than the last session had. The debt multiplies.
What Context Debt Looks Like
There are three forms.
Decision debt. You made a choice and didn't explain why. Common choices that create decision debt: library selection, data structure choices, API shape decisions, performance optimizations that sacrifice clarity, security constraints that aren't obvious from the code. When someone else—or another AI session—encounters the choice, they don't know if it was deliberate or accidental. They work around it, change it, or copy it for the wrong reasons.
Constraint debt. The code works within constraints that aren't visible in the code itself. The external service has a rate limit. The database has a specific behavior under contention. The mobile client has a legacy version that must be supported. The business requirement is unusual. These constraints shape implementation choices without appearing in the code. When the code is modified later, the constraint is violated.
Evolution debt. The code's current shape is the result of iterations that aren't documented. You tried three approaches and this was the fourth, the one that worked. But the code looks like a first attempt. Future engineers—and future AI sessions—don't know what won't work, and will try it again.
All three are invisible. All three compound.
The Interest Rate
Here's a useful mental model for measuring context debt: the first-session success rate.
Take any significant piece of your codebase. Give an AI—with no prior context about your system—a meaningful modification task. Measure how often it succeeds on the first attempt without violating a constraint or introducing a bug.
If the rate is high, your context debt is low. The code carries its own reasoning.
If the rate is low, you have context debt. The AI is making good decisions based on bad information. Everything looks plausible; nothing is actually right.
Most teams, if they run this test, will find that their first-session success rate is lower than they expect. Not because the AI is bad, but because the codebase is carrying significant context debt.
Paying It Down
Context debt doesn't have to accumulate. The practices that prevent it are not complicated—they're just unfamiliar, because we've never needed them before.
Decision logs. When you make a significant architectural choice, write a sentence about why. Not what you chose—that's in the code—but why this over the alternatives. One sentence is enough for most decisions. For important ones, a paragraph.
Constraint annotations. When your code works within a constraint that isn't visible from the code, make it visible. A comment. A doc block. A test that explicitly checks the constraint and explains why it exists. This is cheap to write and expensive not to have.
Session summaries. When you end an AI-assisted work session, spend two minutes summarizing what was learned, what was decided, and what the next session needs to know to continue effectively. Store it where AI can find it. This is the highest-leverage context capture practice I've found.
None of these require new tools. They require the discipline to capture reasoning at the moment it exists—which is the only moment it's cheap to capture.
After the session ends, the context is gone. You can reconstruct it—sometimes—by reading the code carefully. But reconstruction is expensive, error-prone, and creates new context debt of its own.
The Asymmetry
The fundamental asymmetry of context debt: it's expensive to accumulate and cheap to prevent.
A decision log written at the moment of decision takes thirty seconds. The same information, reconstructed six months later from a codebase, takes hours—and may still be wrong.
A constraint annotation written while the constraint is fresh takes one minute. The debugging session after a future AI session violates that constraint takes a day.
A session summary written while the reasoning is active takes two minutes. The investigation into why the codebase does something unexpected takes a week.
Technical debt is often accumulated deliberately—teams decide to ship now and pay later, because the payoff is worth it. Context debt is almost always accumulated accidentally, because nobody thought to capture the reasoning at the moment it existed.
The teams that win the agentic development era will not be the ones who write the best prompts or use the best tools. They'll be the ones who treat context capture as a first-class engineering discipline—who recognize that in a world where AI sessions start fresh, the only continuity is the context you build.
Code is generated. Context is authored. The authoring is the work.
_Context Debt is part of the Context-Driven Development framework for building AI-native software that stays maintainable._