Dan Grafham · @dangrafham · May 2026

Solo Dev Pathology · Anti-Pattern Field Notes

AI Debt

What happens when the framework starts serving itself instead of shipping the product.

This morning I cleaned up 3,252 lines of README spread across 32 files. I'm the only human author in this workspace. I wrote none of them. AI agents had generated them over the previous weeks, following rules I had set up that allowed documentation to grow.

The same cleanup turned up 47 brief directories that should have been deleted on closure but weren't, 22 node_modules trees committed to git, 16 leftover dispatch branches still hanging off main, and 8 dangling references inside the doctrine file itself. Agents citing each other's hallucinated artifacts.

That's what AI-debt looks like, with the numbers attached.

Every avenue I give you to write something other than code, you find a way to exploit.

00 · Origin

Where the term came from

A code review session on a SaaS factory. The agent kept defending a meta-layer artifact, naming it as a "Phase 5 extraction-discipline bet." That phrasing was the giveaway. None of it gets us a working program.

"D-14 is a Phase 5 extraction-discipline bet" do you hear yourself right now? How does this get us a working program?

That's where the term landed. AI debt. The named cost of an apparatus that grew up around an agent's fluency, not around a product actually shipping.

01 · Definition

What AI debt actually is

Term

AI Debt (noun)

The artifacts AI agents are happy to generate (ADRs, status docs, generalization registries, deferred-design ledgers, friction logs) that accumulate cost-of-maintenance without accumulating shipped product. They feel like progress because they're well-structured and the agent is fluent in them. They are in fact a tax the agent levies on the human, payable in attention and decision-cycles, with no corresponding revenue. The framework starts serving itself.

It's the AI-era cousin of technical debt, but the failure mode runs in the opposite direction. Technical debt is what happens when you ship without discipline. AI debt is what happens when you have too much discipline and never ship.

The agent isn't being malicious. It's being agreeable. ADRs, generalization registries, exit criteria, phase models, friction logs. The agent will produce as many of these as you let it, because each one looks like the structured output it was trained to value. The structure is real. The cost is also real. The shipped product is the thing that's missing.

02 · Taxonomy

The artifacts that look like progress

Not all of these are debt. Some are genuinely load-bearing. The trap is treating fluency in producing them as evidence that producing them was the right call to begin with.

Artifact 01

Locked ADRs

Architecture Decision Records that ratify decisions before any code that depends on them has compiled. Locking implies confidence the codebase can't yet justify, which then requires its own un-locking ritual when reality intervenes.

Artifact 02

Generalization Registry

A document tracking which patterns "should" generalize across future projects, before any second project exists to validate them. Followed inevitably by a meta-tracker recording which entries are "ready" vs. "pending."

Artifact 03

Phase Models with Exit Criteria

Multi-phase project plans with formal gates. The phase model becomes the work. Exiting Phase N requires another artifact certifying the exit.

Artifact 04

Deferred-Design Ledger

A running list of design decisions explicitly not made, with conditions that would trigger making them. Useful in theory. A fence-sitting registry in practice.

Artifact 05

Friction Log

A separate document tracking every place the workflow felt awkward. Reads like meta-commentary on the project rather than progress within it.

The pattern Each one of these can be load-bearing on the right project at the right time. The diagnostic isn't "do you have these?" It's "did you build these to ship the product, or did the product become the substrate for building these?"

03 · Mechanisms

Why AI debt accumulates so fast

MECH 01 The Agent is Fluent Generation cost is zero

An agent will produce a 400-line ADR in seconds. It will produce a phase model with formal gates without being asked twice. It will generate a friction log on request and offer to keep it updated. The cost of creating the artifact is functionally zero. The cost of maintaining the artifact is paid by the human, in attention. The asymmetry is the whole problem.

MECH 02 Structure Looks Like Progress The legibility trap

Well-structured documents read as forward motion. Numbered sections, exit criteria, decision tables. They scratch the same itch a closed pull request scratches. But a document is not a deployment. The legibility tricks the human into accepting the artifact as evidence the work is happening, when the artifact is the work that's happening.

MECH 03 The Agent Defends the Meta Sunk-cost fluency

Once the meta-apparatus exists, the agent has incentive to defend it. Every decision routes through the apparatus. Every push-back gets a "well, per D-14 the rescind ceremony requires..." The framework becomes the answer to questions about the framework. None of those answers boot up the program.

MECH 04 Pattern-Match Without Grounding The original sin

The factory often gets built by pattern-matching from a few good examples and codifying the patterns as locked policy without consulting an authoritative reference. The corner-cutting is choosing speed over grounding. By the time the audit catches it, the apparatus has metastasized. Every downstream artifact inherits the original ungrounded assumption.

MECH 05 Scaffolding Around Scaffolding Recursion failure

When the meta-layer accumulates fast enough, you get artifacts about artifacts. A document tracking the status of generalizations. A ledger of which deferred designs are landing. A phase whose exit criteria reference other meta-artifacts. None of it is wrong in isolation. All of it is wrong as a stack.

04 · The Honest Reset

What ships product, what doesn't

The product either boots or it doesn't. The meta-apparatus around it doesn't change that. None of the surrounding documents decide that for you.

What ships product: the binary boots. The prod credentials get set. The DB bootstrap runs. The runtime dependencies build their artifacts. Deploy-on-green stops being theoretical. Then project number two goes from concept to deployed using whatever rails the first one laid down, and you watch what actually transfers vs. what you have to redo.

That is the experiment. Everything else is the experiment about the experiment.

What's likely AI debt (candidates for "delete and see if anything bad happens"):

The friction log as a separate artifact, and any meta-tracker that records the state of other documents
The phase model with formal exit criteria gating each transition
The locked-ADR-rescind ceremony
The generalization registry tracking which patterns "should" transfer
Any document that exists primarily to track the state of other documents

What's likely worth keeping (probably not debt):

DECISIONS.md (or similar): cheap, you genuinely re-read it, captures the calls that are easy to forget
A deferred-design ledger (or similar): the landing/discard triggers actually do force discipline if you respect them
CLAUDE.md / role contracts: load-bearing for getting agents to behave consistently
Anything the running code refers to or that gates a CI step

05 · The Test

How to spot AI debt before it metastasizes

Five questions. Run them on every artifact the agent proposes or has already produced. The honest answers are usually obvious once you stop being polite.

Does any running code or CI step actually consult this document?If a script reads it, lint depends on it, or a deploy gates on it: probably not debt. If only humans read it, and only sometimes: candidate for debt.
Is this an artifact about the work, or an artifact of the work?A README the user opens is of the work. A friction log nobody opens after writing is about the work.
Would anything bad happen in a week if I deleted this?If the answer is "I'd lose context I'd have to rebuild," that's a real cost. If the answer is "I'm not sure, probably nothing," it's debt.
Does this artifact reference other artifacts more than it references the product?Documents that mostly point at other documents are scaffolding. Sometimes scaffolding is required. Often it's just scaffolding around scaffolding.
Did the agent propose this, or did I ask for it?Both can be valid. But if the agent proposed it, ask harder. The agent has very low resistance to proposing more apparatus. That doesn't mean the apparatus is wrong. It means the agent isn't a check on whether you need it.

06 · The Asymmetry

Why AI debt is structurally different from technical debt

Technical debt has a balance sheet. AI debt doesn't. That's the whole structural difference, and it changes how every other property of the two should be read.

Technical debt buys you something. You cut corners, the feature ships, the shipped feature generates value. The cost shows up later as bugs, refactors, or production incidents. Back-loaded, but back-loaded against an asset that's already earning. You can manage the spread, pay it down on a schedule, accept some forever. The math works because both sides of the ledger exist.

AI debt buys you nothing. The structure goes up before the feature ships. The cost is paid now, in present attention and decision-cycles, against a feature that may never reach production. A locked ADR for an unshipped product is a maintenance obligation against zero revenue. A friction log on a project that hasn't reached customers is overhead with no offsetting income. The debt sits on the books with nothing on the asset side.

Practical implication If you treat AI debt the same way you treat technical debt (manage it, pay it down later, accept some), you're misreading the structure. AI debt is closer to administrative overhead in a startup that hasn't found product-market fit yet. The right move isn't to manage it. The right move is to not take it on in the first place, and to delete the parts you already took on that aren't load-bearing.

07 · The Discipline

Three rules to avoid accumulating AI debt

RULE 01 If the agent proposes an artifact, ask "does this ship the product?" Default: no

If the answer isn't an obvious yes, default to no. The agent has approximately zero resistance to proposing more structure. The human has to be the friction. Most proposals fail this test cleanly. The ones that survive are usually load-bearing.

RULE 02 No locking before validation Earn the lock

A "locked" decision before any production evidence is just a decision with extra ceremony. Locking implies a cost-of-rescinding that the codebase hasn't earned the right to claim. Make decisions, write them down, but defer locking until you've shipped the thing the decision constrained.

RULE 03 Delete on a schedule Forcing function

Every so often, audit every meta-artifact in the project. Delete the ones that aren't load-bearing. The artifacts that survive multiple rounds are the ones actually doing work. The ones that don't survive were debt.

08 · Reframe

What this is actually a symptom of

AI debt isn't really about AI. It's about the fact that the agent's marginal cost of producing structured artifacts has dropped to zero, while the human's cost of maintaining them has stayed the same. Whenever production cost and maintenance cost diverge that hard, the system over-produces.

It's the same shape as the World Domination Scope problem, but in a different domain. There, AI made implementation free, so the only bottleneck became the human's vision (which is infinite). Here, AI made meta-apparatus free, so the only bottleneck becomes the human's discipline about what apparatus to accept (again, infinite).

Speed alone does not ship. Cheap structure alone does not ship either.

Both failure modes have the same root: a thing that used to be expensive (and therefore self-limiting) is now free, and the human's discipline is the only remaining governor. AI debt is what happens when that governor is set too loose.

09 · The Marketing Layer

Where AI debt shows up next

AI debt isn't only an internal problem. It shows up in product positioning, too. When marketing reads "100+ agents · 32 plugins · 21 npm modules · 12 background workers · 150×–12,500× faster", that's AI debt externalized to the README. The same agent that produces a 400-line ADR on request will produce a 40-line capability table on the same request. The kitchen-sink feature list is AI debt the customer pays for.

The fix is the same, and it isn't discipline. Discipline is what the agent has just enough of to find new places to add notes. The fix is structural: a gate that makes new bullets, new files, new categories harder to add than to leave out. Position by primitive, not by enumeration.