There's a conversation that happens in almost every sprint retrospective I've ever run. Someone says "we really need to address our technical debt." Everyone nods. It gets added to the backlog. Three months later, same retro, same nod, nothing changed.
I used to think that was a prioritization problem. Product keeps pushing features, leadership doesn't see the value of cleanup, the usual. But after inheriting a few systems mid-flight and watching capable engineers struggle with codebases that looked fine on the surface, I started to suspect something else was going on.
The code wasn't always the problem. The problem was that nobody could tell me why the code was the way it was.
Two kinds of debt, very different pain
Technical debt is the stuff your linter can find. Tangled dependencies. Missing tests. A function that does seven things and is named handleData. You know it's there. You know roughly where it lives. On a good team, you can schedule paying it down.
Context debt is different. It's the accumulated loss of institutional knowledge about why your system was built the way it was. Not what it does — why it does it that way and not some other way. The architectural decision that happened after a painful incident. The edge case that's handled by what looks like arbitrary code but was actually the result of three partner integrations and a compliance audit. The service boundary that exists because of an org change eighteen months ago, not because it was the cleanest technical choice.
None of that lives in the code. Very little of it lives in documentation, because documentation is something teams aspire to write and rarely maintain. Most of it lives in the heads of the engineers who were in the room when those decisions were made.
When those engineers leave, that knowledge walks out with them. And they always eventually leave.
Here's what I've noticed managing engineering teams at a company moving fast: context debt doesn't hurt until it suddenly really hurts. Technical debt creates friction gradually. You feel it on every sprint — things take longer than they should, estimates are off, PRs need more review rounds. It's chronic. Context debt is mostly invisible until the moment someone tries to change something load-bearing and discovers they don't understand why it works the way it does. Then it's acute.
The difference matters because you manage them completely differently.
Then AI arrived and made this dramatically more complicated
I want to be careful here because I think some of the discourse around AI and code quality is overblown in one direction or underblown in another, and I'm not sure which.
Here's what I do think is real: AI tools have genuinely shifted the economics of writing code. Generating a working service that passes tests used to be expensive in engineer-hours. Now it's cheap. That's a real capability change and I'd be lying if I said it hasn't changed how my teams work.
But there's a paradox in it that took me a while to articulate clearly. Addy Osmani wrote about this recently as "comprehension debt" — the growing gap between how much code exists in your system and how much of it any human actually understands. He put it well: the codebase looks clean, the tests are green, and the reckoning arrives quietly at the worst possible moment.
I've seen this happen on a smaller scale. A junior engineer uses an AI tool to implement something, the code looks clean, it passes review, it ships. Six weeks later something breaks in production in a way that surprises everyone, including the engineer who wrote the code. Not because the AI wrote bad code. Because nobody fully internalized what the code was doing or why it was doing it that way, and so nobody caught the implicit assumption it was making about a downstream system.
What Osmani is describing as comprehension debt is real. But I think it's actually a symptom of something deeper, which is context debt at the system level. And AI accelerates context debt in a way that's worth being specific about.
When rewriting is cheap, the incentive to understand before replacing drops toward zero. Your AI assistant can regenerate a service in an afternoon. What it cannot regenerate is the institutional knowledge about why that service exists, what edge cases it was patched for over eighteen months, which downstream consumers depend on its specific response shapes. You get code that compiles, passes tests, and handles the happy path. You don't get the scar tissue.
I read a framing I thought was sharp from Michael Tuszynski: "AI can regenerate the code layer fast. It cannot regenerate the institutional context that made that code correct." That's the line I keep coming back to.
What context debt actually looks like on a team
Let me be concrete, because "loss of institutional knowledge" is the kind of phrase that sounds meaningful but doesn't tell you what to do.
Here are the specific places I've seen context debt accumulate:
Architectural rationale that nobody wrote down. Why is this a separate microservice instead of a module in the monolith? Why is the database schema structured this way? If the answer is "because we decided to do it this way two years ago" and the people who made that decision are gone, you have context debt. The next engineer who touches this will either make a change that conflicts with the original rationale, or they'll leave the structure alone out of fear, and neither outcome is good.
Boundary knowledge. Which partners or internal consumers depend on specific response shapes? Which integrations are fragile in ways that aren't obvious from the code? This is the knowledge that shows up as "why did you change that field name, three other systems broke" six hours after deploy. It's invisible until it isn't.
Failure memory. The race condition that an engineer caught after an incident eighteen months ago and quietly patched. The validation logic that exists because of a security audit finding. The retry logic that's tuned the way it is because the default behavior destroyed a downstream system under load. This code looks redundant if you don't know the story. An AI tool rewriting the service will likely strip it out. And you won't know it was wrong until the same failure happens again.
The uncomfortable thing is that all of this is also exactly what AI coding tools are worst at. They operate within a context window. They see the file you're working on, the adjacent files, whatever system prompt describes your stack. They don't see the full topology of your system — every service, every contract, every shared assumption that holds your architecture together. When three engineers independently use AI to build three services that interact, each service can be internally clean and the integration between them can be quietly wrong in ways nobody catches until production.
The measurement gap that makes this a leadership problem
Here's what makes context debt particularly difficult to manage: nothing in your current measurement system captures it.
Your velocity metrics look fine. DORA metrics hold steady. PR counts are up. Code coverage is green. Performance reviews see output volume. The comprehension deficit, the accumulated context loss — none of that appears in any artifact your organization measures.
This is what makes it a leadership problem and not just a technical one. Technical debt is visible enough that engineers can advocate for paying it down. Context debt is invisible to the tools, the metrics, and often to the engineers themselves. They'll approve a PR that looks right, because it does look right. The problem is invisible until it compounds into something that isn't.
I've thought about this a lot in the context of AI adoption. There's genuine pressure right now to show velocity improvements from AI tooling. That pressure is real and not unreasonable. But if your measurement system only captures what moves fast, you'll optimize for speed and discover the context you've shed when something breaks at scale.
What you can actually do about it
I want to be direct here: I don't think this is primarily a culture problem. "Slow down and review more carefully" is advice that sounds reasonable in a blog post and falls apart in a sprint with a deadline. The teams that will manage context debt well are the ones that treat it as an infrastructure problem, not a discipline problem.
Architectural decision records, maintained as living documents. ADRs have been around for years — the format is basically Title, Status, Context, Decision, Consequences. What's changed is the urgency. Before AI-assisted development, context accumulated naturally as engineers wrote code slowly enough to internalize it. Now it dissipates faster than it accumulates unless you deliberately counteract that. An ADR written when a decision is made and living alongside the code is worth ten retrospective explanations after the fact.
The key word is "living." A dusty Confluence page nobody updates is not an ADR. It's archaeology. If your ADRs aren't being referenced and updated as part of the development workflow, they're decoration.
Structured project memory as a first-class artifact. Context documents — system descriptions, constraint inventories, edge case catalogs, partner dependency maps — should be versioned and reviewed with the same rigor as code. Not because engineers will read them compulsively (they won't), but because when an engineer or an AI tool is about to make a change, the context needs to be accessible right there. Embedded in the workflow, not sitting in a separate system someone has to remember to consult.
Explicit integration contracts. If your services are generated independently by AI tools without awareness of each other, you will accumulate integration debt. The data formats, error handling conventions, retry semantics, authentication flows — these will diverge. The fix is defining and maintaining explicit contracts that both engineers and AI tools can reference during generation. The contract becomes the source of truth, not the individual engineer's mental model of how everything connects.
Offboarding as a context transfer ritual. When a senior engineer leaves — and eventually everyone leaves — their departure is the most expensive context loss event your team will experience. I've seen teams do thorough technical offboarding (here's how the systems work) and nothing about contextual offboarding (here's why these systems work this way, here are the decisions I'd revisit, here's the undocumented partner integration that will break if you do X). The latter is what you actually need.
One thing I've started doing: before an engineer leaves, I ask them to record a "walk through the weird parts" session. Not a systems overview. Specifically the things that look wrong but aren't, the things that need to stay exactly the way they are and why, the decisions they made that they'd make differently now. That's the institutional knowledge you can't recover after someone's gone.
Context-aware generation as a deliberate workflow. If your engineers are using AI tools to generate code, the tools should be ingesting project context before they generate. This means investing in the scaffolding — the context files, system prompts, reference documents, constraint catalogs — that give the AI a real understanding of the system it's working within. The alternative is an amnesiac collaborator that produces clean code in a vacuum. That's fine for a proof of concept. It's not fine for production.
What I'm still figuring out
I'll be honest about where I don't have clean answers.
Measuring context debt is genuinely hard. I can measure test coverage, PR cycle times, defect rates. I cannot tell you with a number how much institutional context my team has lost in the last six months of AI-assisted development. I can observe signals — engineers expressing uncertainty about why something works the way it does, changes that break things in surprising ways, architectural discussions that require me to explain history that should be documented — but I don't have a dashboard for this.
I'm also not sure yet how much of this is fundamentally new and how much is the same old context-loss problem that's always existed, just accelerating. My guess is it's both, and the acceleration is the part worth treating seriously right now, before the debt compounds further.
What I'm reasonably confident about: the teams that will do well in the AI era aren't necessarily the ones that generate code fastest. They're the ones that maintain the richest context while moving fast. That combination compounds. A year from now, the team that invested in context architecture will be moving quickly and safely. The team that optimized only for velocity will be drowning in debt they can't see and can't name.
The old tech debt conversation was mostly about code quality. This one is about knowledge architecture. And most teams haven't started having it yet.
If you're thinking about this differently on your team, or you've found approaches that actually work for maintaining context at pace — I want to hear about it. Reach out on Twitter or LinkedIn.
Further reading
These two talks were valuable references while thinking through these ideas: