The Three Dimensions of Software Debt

Software health is defined by three distinct, independent types of debt. While technical debt (implementation shortcuts) and cognitive debt (lack of human understanding) are well-understood, intent debt is the most dangerous in an AI-driven era. Intent debt is the absence of externalized rationale, goals, and constraints. It occurs when the 'why' behind a system exists only in the minds of the team, leaving the codebase without a record of its purpose or the boundaries of its design.

Why AI Cannot Pay Down Intent Debt

AI excels at refactoring code (technical debt) and explaining complex logic (cognitive debt). However, AI is structurally incapable of generating intent. When asked to explain a design choice, an AI will often fabricate a plausible-sounding reason rather than admitting it lacks the context. Because agents start every session 'cold'—lacking the tacit knowledge humans acquire through years of shared experience—they will confidently fill gaps in intent with guesses. This turns unwritten intent into a compounding tax, as every agentic interaction risks diverging from the original product goals.

Strategies for Externalizing Intent

To mitigate intent debt, teams must shift from documenting implementation to documenting the 'why.' This requires treating intent as a first-class artifact:

• Intent-Focused Specs: Write specifications that define goals, constraints, and non-negotiables (e.g., performance, accessibility) rather than just functional requirements.
• The AGENTS.md Ledger: Use an intent file to document team conventions, historical 'lessons learned,' and design constraints that are not visible in the code itself.
• Lightweight Decision Logs: Implement ADRs (Architecture Decision Records) at the moment of decision. The cost of recording the rationale is trivial compared to the cost of reconstructing it months later.
• Self-Improving Loops: Configure agents to write their learnings back into a persistent file. Recording why a specific approach failed or succeeded prevents the loss of institutional knowledge.

Ultimately, as code becomes cheaper to produce via AI, the human-originated 'why' becomes the most valuable asset in a repository. If the intent is not written down, the system may continue to function while losing its original purpose.