This article by Addy Osmani originally appeared on Addy Osmani’s blog and is republished here with the author’s permission. Osmani frames the discussion using Margaret-Anne Storey’s Triple Debt Model, which separates software health into technical debt, cognitive debt, and intent debt.
The three debts, at a glance
-
Technical debt: lives in the code. It is the accumulation of implementation choices that make a system harder to change later — tangled modules, deadline shortcuts, leaking abstractions. Developers have recognized this for decades: slow builds, brittle tests, and the dread of touching a particular file are familiar signs.
-
Cognitive debt: lives in people. It describes erosion of shared understanding — the gap between how much code exists and how much any person actually understands. Osmani has also called this "comprehension debt": it grows when the system outpaces the team’s mental model.
-
Intent debt: lives in artifacts. It is the absence or erosion of externalized rationale, goals, and constraints that explain why the system is the way it is. The key word is externalized: the rationale must be written where a teammate, a future you, or an agent can read it, not kept only in someone's head. High intent debt means the system drifts from the intended design and no one can say when or why.
These three debts are independent: you can have low technical debt but high intent debt, or understand a system personally (no cognitive debt for you) while its intent exists nowhere outside your skull (huge intent debt for everyone else).
Why intent debt is the one agents can't pay off
AI can now generate code faster, which makes taking on and paying down technical debt cheaper. An agent can refactor a tangled module.
Cognitive debt is also partly recoverable: when you don’t understand a part of the system, you ask an agent to explain it and rebuild some of the lost mental model on demand, because the code still exists and the model can read it back to you.
Intent is different. An agent cannot generate intent — intent is the one input that must come from humans. A model can infer a plausible rationale from code, just as you can guess why a previous engineer made a choice. A guess about intent is not the intent. The model does not know whether a 300 ms debounce is a deliberate UX decision, a benchmarking result, or a number someone typed once and never revisited; it will invent a confident-sounding reason rather than admit ignorance.
Of the three debts, intent debt is the only one where the agent cannot bail you out. It can write code and restore comprehension. The why is the thing it can only fabricate.
Agents compound the cost of unwritten intent
Teams got away with high intent debt for years because the intent lived in people’s heads and in scattered old docs. New hires picked intent up over time through hallway conversations, code review notes, and historical context like “we don’t do it that way because of an incident in 2023.” The veteran engineer effectively served as the intent documentation — expensive and lossy, but workable.
Agents break that model. Adding agents to a team effectively doubles its size overnight with junior collaborators that have no long-term memory. An agent usually starts sessions cold and brings none of the tacit intent humans accumulated over time. Whatever you haven't externalized into an artifact it can read, it doesn't have.
That changes the economics of not writing things down. Unexternalized intent used to cost you periodically (onboarding or staff changes). Now you pay it every session, multiplied across every agent you run.
Imagine the 20 agents you parallelize: each is a teammate who has never met you, cannot read your mind, and will fill any intent gap with a plausible guess. The orchestration tax some teams experience is partly an intent-debt tax. Much of what makes managing many agents exhausting is resupplying the intent you never documented.
The other side of the comprehension-debt argument
Previously, Osmani argued that detailed specs are not a complete answer: translating a spec into working code requires many implicit decisions no spec ever captures, and a spec detailed enough to be the program is essentially the program in a slower language. He still believes that.
Intent debt is the complementary truth. Not being able to capture all intent is no license to capture none. The implicit decisions an agent now makes on your behalf — those a spec will never enumerate — are the ones whose rationale evaporates if you don't at least record the load-bearing reasons. You cannot write down everything, but you must write down the why behind choices that would be expensive to reconstruct incorrectly.
Comprehension debt warns you not to trust that code is correct just because it exists. Intent debt warns you not to trust that the reason survives just because the code does. Code is the answer; intent was the question it answered. AI excels at producing answers to questions you forgot to write down.
What high intent debt looks like in practice
Intent debt rarely manifests as friction; it appears as a particular helplessness:
- An agent “fixes” a bug by deleting a guard clause, and no one can say whether that guard was load-bearing or leftover because no document or commit message recorded why it was there.
- A refactor changes behavior users depend on. The review passed because the diff looked clean and tests were green, but the tests encoded only the previous behavior, not the intent.
- You ask why two services communicate over a queue instead of a direct call, and someone answers: “An agent suggested it and it seemed fine.” That is intent debt starting to accrue interest.
If you’ve experienced the cognitive-surrender version — defending a design you can’t reconstruct — intent debt is the team-scale, written-down outcome of many such moments.
Paying it down: externalize intent as a first-class artifact
Osmani’s practical recommendations are:
- Take the intent out of your head and put it where an agent can read it.
- Write the spec for the intent, not the implementation. A good spec captures goals, constraints, nonnegotiables, and an explicit definition of done (fast, accessible, secure, delightful — beyond just “functionally correct”). The spec carries the intent that code alone cannot.
- Treat AGENTS.md as your intent ledger, not your config. Auto-generated init files describe what the code is; an intent file describes what the team means: conventions, “we don’t do it this way because…,” and constraints invisible in any single file. Agents can’t infer that, and they need it most.
- Capture decisions where they happen. Lightweight decision logs (ADRs) pay down intent debt: recording the why when you decide costs almost nothing; reconstructing it months later after the person who knew why has moved teams costs a fortune. Agents make logging cheaper, so the old excuse is gone.
- Make the learning loop write intent back down. Self-improving agents that update a learnings file at session end can reverse the intent-debt pump: each recorded root cause and “we tried X and it didn’t work because Y” becomes intent that otherwise would live only in someone’s memory of a bad afternoon.
None of these are new tools. They’re a discipline: refuse to let the why exist only in your head in an era when your head is no longer where most of the work happens.
Where value has shifted
For a long time, the scarce, valuable skill in software was producing a correct implementation; code was expensive, and we optimized for writing it. AI has made code cheap and comprehension recoverable. Intent — the goals, constraints, and reasons — still has to originate with humans, and it’s the one input we’re worst at externalizing because for decades we got away with carrying it in our heads.
That worked when teams were small and intent transferred via long-term shared context. It does not work when half the team are agents that start every session as strangers.
Technical debt makes your system hard to change. Cognitive debt makes it hard to understand. Intent debt makes it hard to know whether the system still does what you wanted — and it’s the only one of the three your agents can’t pay back for you. That burden remains human. Write down the why: it’s becoming the most valuable thing you can leave in the repo.
