Cognitive debt
Technical debt is code you wish was cleaner. Cognitive debt is code you wish you understood. AI pays down the first and accelerates the second. That is the real risk.
The mechanism
- Cognitive surrender. Developers accept the diff because tests pass, without forming a mental model. Fine for one PR; fatal across a quarter.
- Knowledge erosion. The team's collective theory drifts from the system. When something breaks, no one knows where to look.
Cognitive debt is invisible to linters and tests. It surfaces during incidents.
Three kinds of debt
| Type | Indicator | AI's effect | Repayment |
|---|---|---|---|
| Technical | Duplication, dead code | Reduces it | Linting, refactor passes |
| Cognitive | Slow onboarding, "no one understands X" | Accelerates it | Plan reviews, active design |
| Intent | "Why was this built this way?" has no answer | Accelerates it | ADRs, negative-space docs |
Intent debt is the most subtle: the code works, but the next change reverse-engineers the choices from scratch.
Context rot in long sessions
Even with good files, long sessions degrade. History accumulates, the runtime compacts it, the original rules become vague. Four patterns:
| Rot | What it looks like | Mitigation |
|---|---|---|
| Poisoning | Uses deprecated APIs. | Stale-context checks; explicit "use X, not Y" rules. |
| Distraction | Irrelevant rules fire. | Scoped rules. Split-file architecture. |
| Confusion | Similar objects conflated (User vs UserAccount). | Namespace mapping. Before/after examples. |
| Clash | Two rules contradict; last seen wins. | One canonical source. Consistency checks. |
Distraction at hour two; Poisoning at hour four. Frequent session clears
(/clear) force the agent to reload from disk rather than
relying on compacted history.
The four repayment practices
- Atomic interaction and review. Small changes, reviewed individually. Human stays the architect. →
plan - Externalise intent. ADRs for the why, negative-space docs for the rejected. →
adr - Plan Mode discipline. A reviewed plan before any code. →
plan - Verification first. Tests, linters, types baked into context. Agent iterates until they pass. →
verify
What to do with this
Run audit to find which
kind of debt your repo has. The audit scores each layer with one sentence
of evidence and names the highest-leverage next moves.