There’s a kind of debt nobody puts on the board.
Not technical debt — most teams at least know that exists, even if they don’t pay it down. This one is quieter. It accumulates in the gaps between what your system does and what anyone can explain about why.
Call it context debt. Every decision you made but didn’t write down. Every constraint you internalized but never documented. Every “we don’t do it that way” that lives in one person’s head and nowhere else.
You’ve been paying interest on it for years. You just didn’t have a name for it.
How It Accumulates
Context debt doesn’t feel like debt when it’s forming. It feels like efficiency.
You make a decision. It’s obvious to everyone in the room. Writing it down seems like overhead — the kind of thing you’ll do later, when things slow down. Things don’t slow down. The decision becomes assumption. The assumption becomes invisible. Six months later someone violates it without knowing it existed, and you spend two hours in a postmortem explaining something that should have taken two minutes to write down.
Every codebase has these. The table that can never be truncated because of a dependency three systems away that nobody mapped. The API endpoint that silently ignores certain inputs because of a business rule from 2019 that got baked into the code instead of the docs. The deployment sequence that has to happen in a specific order that lives in one engineer’s muscle memory.
These aren’t bugs. They’re decisions — good ones, usually — that outlived the context that made them legible.
That’s the debt. Not the decision. The missing explanation.
Why AI Made It Visible
Context debt existed before AI. What AI did was make it expensive in a new way.
When you onboard a new developer, context debt costs you onboarding time. They ask questions, they make mistakes, they slowly absorb the invisible rules. Painful, but bounded. One person, weeks to months, eventually productive.
When you onboard an AI session, context debt costs you every single session. The model has no memory of what you told it last time. Every conversation starts from scratch. Every invisible rule has to be re-explained, or the model violates it with confidence and you spend time cleaning up output that was wrong for reasons the model couldn’t have known.
The AI doesn’t ask questions. It makes assumptions. And it makes them fast.
A new developer’s wrong assumption costs you a code review. An AI’s wrong assumption at scale costs you a lot more — especially if you’re not reviewing carefully because you trusted the context you forgot to provide.
The teams getting the most out of AI aren’t the ones with the best prompts. They’re the ones with the lowest context debt — the ones who have been writing things down, keeping the instruction set current, maintaining the record of why the system is the way it is.
The copilot-instructions file I wrote about earlier is one answer. But it’s downstream of the real discipline: deciding that context is an asset worth maintaining, not overhead to defer.
What Paying It Down Looks Like
You don’t pay down context debt in a sprint. You pay it down the same way it accumulated — decision by decision, written down at the moment it’s made rather than reconstructed later when it’s already half-forgotten.
Three practices that actually work:
Write the why, not the what. Code tells you what the system does. Comments that describe what the code does are redundant. Comments that describe *why* the code does it that way — what constraint it’s working around, what decision it reflects, what the alternative was and why you rejected it — are the ones that age well.
Capture decisions at the moment of making them. Not in a retrospective. Not in a quarterly doc review. At the moment. A two-sentence note in the right place — the PR description, the architecture doc, the instructions file — is worth ten pages of documentation written six months later from memory.
Treat the instructions file as a living record. Every time an AI session surfaces something unexpected — a pattern you hadn’t consciously articulated, a constraint you’d internalized but never written down — that goes in the file. The next session starts smarter. The debt doesn’t accumulate from that point.
This is what makes tools like BMAD compelling in practice. The methodology enforces decision capture as part of the workflow — not as a separate documentation step that gets deferred, but as a condition of moving forward. Every architectural decision recorded at the moment it’s made, in the artifact that travels with the work. The context doesn’t accumulate as debt because the process won’t let you skip it.
The goal isn’t perfect documentation. It’s a low enough debt load that the system remains legible — to new developers, to AI sessions, to future you at 9pm on a Thursday when something is broken and you need to understand it fast.
The Compounding Problem
Context debt compounds the same way financial debt does — except the interest rate goes up as the system grows.
A small codebase with high context debt is manageable. One or two people who know where the bodies are buried. Expensive when they leave, survivable before then.
A large codebase with high context debt is a different problem. The invisible rules multiply. The dependencies between them multiply faster. The cost of violating one unknowingly goes up because the blast radius is larger. And the people who could explain it are increasingly scarce — retired, moved on, promoted out of the code and into meetings.
This is the legacy system problem. Not old code — invisible context. Code that runs fine but that nobody can safely change because nobody fully understands why it works.
AI doesn’t solve this. AI makes it worse, faster, if you let it. A model confidently extending a system it doesn’t understand will extend it wrong, at speed, in ways that look right until they don’t.
The teams that will use AI well in complex systems are the ones who treat context as infrastructure. Not documentation for its own sake — living, maintained, decision-level context that makes the system legible to anyone who needs to work in it.
That’s not a new discipline. It’s an old one that just became urgent.
The Debt You Don’t Know You Have
Here’s the hardest part: most context debt is invisible to the people who created it.
You don’t experience your own assumptions as assumptions. You experience them as obvious facts about how things work. The constraint you never wrote down doesn’t feel like missing context — it feels like common knowledge. Until it isn’t.
The signal is usually a question you can’t answer quickly. Someone asks why the system works a certain way and you find yourself saying “I’d have to think about it” or “there’s a history there” or “just don’t touch that part.” Those phrases are the sound of context debt coming due.
A useful audit: take the part of your system you understand best and try to write down everything a capable developer would need to know to work in it safely — not what it does, but why it is the way it is. The gaps between what you can write and what you actually know are your context debt inventory.
Most people find it larger than they expected.
What This Has to Do with AI
Everything.
The promise of AI in software development is leverage — the ability to move faster, cover more ground, handle more complexity than you could alone. That promise is real. But leverage amplifies what’s already there. A well-understood system with low context debt gets dramatically more capable with AI assistance. A poorly understood system with high context debt gets dramatically more dangerous.
The teams failing with AI aren’t failing because the model is bad. They’re failing because they’re asking the model to work in systems it can’t understand — systems nobody fully understands — and then being surprised when the output is confidently wrong.
Pay down the context debt. Not for the AI. For yourself, for your team, for the engineers who will work in this system after you’re gone.
The AI just made the cost of not doing it visible.