Intent Debt: The Invisible Cost of Software
In the AI era, undocumented design rationale becomes the most expensive technical debt
1The Three Debts of Software
Margaret-Anne Storey's Triple Debt Model classifies software health into technical, cognitive, and intent debt. Technical debt stems from quick fixes in code, cognitive debt from the team's lack of system understanding, while intent debt arises from missing documentation of design rationale. These debt types accumulate independently and incur different costs throughout a system's lifecycle.
2Technical Debt: The Visible Burden
For decades, the industry has recognized technical debt - poor abstractions, rushed modules, or untested solutions manifesting through slow builds and fragile tests. Modern AI tools can significantly reduce this debt through automated refactoring. However, these tools cannot address intent debt because they lack access to the 'why' behind system design. Technical debt becomes cheaper to incur and pay down in the AI era.
3Cognitive Debt: Erosion of Mental Models
As systems grow, no single engineer fully understands all code. Cognitive debt represents the gap between codebase size and team comprehension. AI assistants can partially alleviate this debt by generating code explanations. However, these explanations don't reflect the original design intent behind decisions. The most valuable system knowledge often remains tacit in engineers' minds.
4The Unique Danger of Intent Debt
AI cannot determine whether a 300ms debounce was a deliberate UX choice, performance optimization, or arbitrary value. Intent debt causes systems to drift from original purposes over time. During team transitions, this debt compounds as newcomers build understanding upon incorrect assumptions. This debt type becomes critical in long-lived projects where original designers may no longer be available for consultation.
5The Cost of Intent Debt in AI Era
Traditional teams transmitted intent through hallway conversations and code reviews. AI assistants break this knowledge transfer model. Each new AI session starts with zero context and may generate incorrect assumptions about undocumented intent. Running 20 parallel AI agents means 20 different intent interpretations. This dramatically increases the hidden cost of every undocumented design decision in your system.
6The Documentation Paradox
No specification can document all design decisions - at that point, the spec becomes the program. However, this isn't license to document nothing. Critical design decisions (load-bearing ones) must be recorded. AI-generated 'plausible guesses' cannot substitute original intent. Rationale behind decisions that would be expensive to get wrong should be preserved, as nobody will reconstruct them accurately later.
7The Orchestration Tax
Part of what makes managing multiple AI assistants exhausting is constantly re-supplying intent you never documented. Each undocumented design decision requires re-explanation in every AI session. This 'orchestration tax' can erode productivity gains from AI, especially in large-scale projects. Teams must account for these hidden costs when adopting AI coding assistants at scale.
8Solutions for Sustainable Systems
1) Maintain ADRs (Architecture Decision Records) for critical choices. 2) Include 'Why This Way' sections in important modules. 3) Document 'why' rather than 'what' in code comments. 4) Flag AI-generated code and conduct periodic intent audits. 5) Establish team knowledge-sharing rituals. These practices prevent intent debt's compounding effects over time.
9Future of Software Architecture
In AI-assisted development, intent debt emerges as the most critical technical debt type. Code existence doesn't guarantee correctness, nor does it preserve original purposes. To sustain AI's productivity promise, teams must center intent management in project lifecycles. Remember: Code is the answer, but intent was the original question being answered. The next frontier of software engineering lies in intentional system design.
Original article: O'Reilly Radar — Yazılımda Niyet Borcu: Görünmeyen Maliyet