Agentic Technical Debt

Sources#

• Claude Opus 5 System Card
• Do Context Files Help Coding Agents? A Two-Agent Ablation Study on Real Repositories
• From Registry to Repository: How AI Agent Skills Are Written, Adapted, and Maintained
• OpenAI Codex lead on the new shape of product work
• The Founder's Playbook: Building an AI-Native Startup

Summary#

A specific failure mode of AI-built codebases articulated in The Founder's Playbook: Building an AI-Native Startup: technical debt that compounds rather than accumulates linearly, because each agentic-coding session re-derives foundational architectural decisions from scratch when no persistent specs or context files exist. The result is a codebase that is functional in pieces but has "no coherent mental model behind it, not because any single piece is bad, but because the pieces were never designed to fit together." The problem tends to surface late — the codebase runs fine until iteration or scale forces a full rewrite.

Why this is different from ordinary technical debt#

Ordinary debt accumulates gradually and can be cleared in a dedicated sprint. Engineers know the shortcuts they took and where; the work is bounded.

Agentic technical debt has three structurally novel properties:

1. Drift, not just shortcut. Each session's "first principles" reasoning lands in a slightly different place. The codebase doesn't just contain compromises; it contains inconsistencies between compromises.
2. Invisible until it isn't. A working feature does not advertise the architectural premise it was built against. The drift is observable only by reading the whole codebase, which the founder typically isn't doing because they're shipping.
3. No natural feedback loop. A traditional engineering team has shared design conversations, code review, ADRs — all of which create human memory of "why this way." A solo founder + agent has neither, so each session genuinely starts from zero on intent.

The mechanism#

"Without specs and architectural constraints written down somewhere the AI can read, each session re-derives foundational decisions from scratch, and those decisions drift."

Each agentic session begins with the agent inferring its own structural assumptions from the current code state. Two sessions reading the same code can infer two different intents (was this pattern intentional? Was that abstraction a constraint or a coincidence?). The agent then builds the next feature against its inferred intent. Repeat over months and the codebase contains multiple "implicit architectures" interleaved.

The remedy: persistent context#

The playbook's prescription is to encode architectural intent in CLAUDE.md markdown files that Claude Code automatically reads at the start of every session. These files serve as project-level instructions — functionally persistent "memory" for the project. The discipline:

1. Before opening Claude Code, open Claude (chat) and define what you're building: core problem, users, six-month scale, architectural principles, dependencies to avoid, tradeoffs being consciously accepted. Save as CLAUDE.md.
2. Start each Claude Code session by (1) revisiting the scope document and (2) providing the model with the CLAUDE.md context document.
3. End each session by updating CLAUDE.md with any decisions the session surfaced.

The playbook's claim: "Five minutes of documentation per session is cheap insurance against architectural drift that compounds into an unmanageable codebase." (Qualified 2026-08-05 — see "What the remedy was measured to buy" below: the insurance is real for cost and process discipline, unevidenced for per-task correctness.)

What the remedy was measured to buy (Khatri, July 2026)#

The prescription above has never been tested in this corpus; Khatri 2026 (arXiv 2607.27250, empirical) is the first controlled ablation of it, and the result cuts a specific way. Across 288 gold-test-evaluated runs on two frontier agents and three real repositories, removing the context file entirely does not lower task correctness (Claude 53.3% with no context vs 55.6% with; Codex 58.8% vs 56.9%; differences bounded <10–15pp), and the real AGENTS.md never converts a near-miss failure into a pass in a 36-cell probe. The mechanism is the load-bearing part: the near-misses fail on implementation skill — a precision bug in a correctly-designed optimization, a reactive-retry pattern chosen where proactive refresh was needed, a rule the agent read off the code and then miswired — not on architectural intent a file could have carried. Full treatment on Agent Context Files.

Three things this does and does not change here:

• It does not touch the drift claim. Khatri measures single-session task correctness against a hidden test oracle. This page's mechanism is cross-session — inconsistencies between compromises accumulating over months, surfacing as a forced rewrite. A per-task pass rate cannot observe that; the experimental design that would (repeated sessions on one codebase, coherence measured at the end) does not exist in the corpus.
• It does narrow the claimed payoff to a channel the playbook doesn't name. What survived the ablation was a process effect with a dose-dependent mechanism: on the one repository whose file warns that the full test suite takes >20 minutes, the agent's blind full-suite runs fall 3.67 → 2.44 → 1.67 as context is delivered more selectively, and wall-clock drops ~24%. That is the "cheap insurance" premise vindicated on token and latency cost — which is precisely the currency the rebuild-from-scratch argument below trades in — while leaving the correctness half unevidenced.
• It sharpens what belongs in the file. The gotchas discipline (Agent Context Files) and the "prune what the agent can infer from the code" rule both survive intact and are, on this evidence, the only content with a demonstrated return: the one file that paid was the one carrying a fact about the environment (test-suite cost) that no amount of reading the repository would surface. Architectural principles and style conventions — the playbook's headline content — are exactly what the ablation found inert.

When the debt matures#

The playbook flags two moments when ordinary AI-built debt becomes a structural liability:

• MVP → Launch transition. Production traffic, new features, and growing complexity expose shortcuts. "That debt starts accruing interest, and the longer it goes unaddressed, the more expensive it is to fix."
• Pre-enterprise audit. Enterprise contracts surface compliance requirements (SOC 2, GDPR, HIPAA) that didn't apply to a prototype. AI scans help but are explicitly not a substitute for qualified compliance review.

The Launch-stage remedy is a systematic architectural audit (Claude Code finds structural weaknesses, test-coverage gaps, refactoring candidates) → Claude triages and sequences remediation → CLAUDE.md is updated with the architectural decisions that lived only in the founder's head during MVP.

The "rebuild from scratch" failure mode#

"Letting Claude Code build without guardrails produces a codebase that will be functional but structurally incoherent, and iterating on and scaling incoherent codebases is ultimately a waste of time and tokens. Sooner or later there's a point where the code inevitably collapses, forcing you to rebuild from scratch."

The economic argument: iterating on incoherent code costs more tokens (longer context, more re-reading, more clarification) than maintaining a coherent codebase from the start. The cost is not principally human time — it's compute. Founders chasing zero-cost iteration trade present minutes for future cost-of-rewrite.

Connections#

• Community Smells Under AI Adoption — this debt's team-level shadow: across five structural models the only path pointing at harm is information governance (AI adoption → worse documentation and informal information flow, β = −.194, marginal at p =.069)
• Unproductive Self-Verification — how the debt gets written: unrequested refactors, extra tests, and speculative verification pipelines that read as productivity, observed across Opus 5's training transcripts
• AI-Native Startup Lifecycle — primary MVP and Launch-stage hazard
• Deep Modules for Agents — Ousterhout-style deep modules + persistent-context discipline are the architectural counter-pressure; Matt Pocock's Sandcastle pattern is one concrete instance
• Agent Context Files — the cross-vendor pattern this page's remedy is one instance of, and where the Khatri ablation is treated in full: the correctness return on generic convention content is bounded near zero, the measured return is on cost and process
• Claude Code Best Practices — official Anthropic guidance on CLAUDE.md; the playbook frames the same discipline as founder survival, not best practice
• Claude Code — the tool where this debt accumulates
• Zero-Friction Scope Creep — companion failure mode; scope creep accrues debt faster
• Harness Shrinkage as Models Improve — counter-pressure: if the harness (including session-context plumbing) shrinks, CLAUDE.md may need to evolve too
• Context Window Smart Zone — CLAUDE.md must fit in the smart zone; over-long context files become their own problem
• Design Concept Grilling — Matt Pocock's grill-me pattern reaches a Brooks "design concept" before code, complementary to CLAUDE.md-as-architectural-context
• Founder as Agent Orchestrator — non-technical founder pipeline raises the stakes: the founders most able to identify problems are least equipped to author the architectural context that prevents this debt
• Problem-Solution Fit Discipline — the twin MVP-stage hazard; epistemic discipline (validate before building) and architectural discipline (persist context before building) are both load-bearing
• Agentic Work Systematization — un-systematized agent use is the re-derive-from-zero / intent-debt failure mode; skills are the persistent-context antidote — but rotting, unmaintained skills are themselves a debt surface as conventions drift
• Unknowns as the Agentic Bottleneck — implementation-notes.md with a Deviations log is intent debt paid down in-flight: the agent records the edge cases that forced it off the plan, so the next session doesn't re-derive them
• Code as Source of Truth — Fiona Fung's positive program against this debt: check specs/skills into the repo so context stays current and Claude can verify spec drift, instead of each session re-deriving it
• Harness Shrinkage as Models Improve — CLAUDE.md is a harness asset that may eventually be inferred; until then, persistent context is the antidote to compounding debt
• Founder as Agent Orchestrator — the recursion problem: non-technical founders may lack the vocabulary to write effective CLAUDE.md
• Loop Engineering — Osmani's intent debt is the same compounding-drift mechanism viewed from the loop: without skills a loop "re-derives your whole project from zero every cycle," each session filling intent gaps with a confident guess; skills (intent written outside) are the antidote, exactly as CLAUDE.md is here
• Outsource Your Thinking, Not Your Understanding — the cognitive twin: comprehension debt (the gap between code-that-exists and what-you-understand) is this architectural debt in the understanding register, and both compound at agentic-coding speed
• Acceleration Whiplash — the same compounding mechanism measured at industry scale; Faros AI's "context engine" (intent derived from how the codebase evolved, not its current state) is the org-scale version of the CLAUDE.md remedy
• AI as Primary Author — an AI author with no persistent intent re-derives architecture each session; this debt is the structural cost of that authorship/accountability gap
• Andrew Ambrosino — the frontier-lab report of the complexity-ratchet: models add code, are bad at deleting, blocking unsupervised development
• Vibe Coding vs. Agentic Engineering — the deletion gap is why "loops are so last week" hasn't yet reached fully-unsupervised autonomous development
• Harness Build-vs-Buy — the other debt that arrives with coding agents, and a different mechanism entirely: not intent drift inside your own code but vendor-branch divergence from someone else's, accruing at ~13 upstream PRs/day from other people's velocity. Same maturity profile (invisible until a forced rebase or a forced rewrite), unrelated cause — don't read its PR counts as evidence about agent-authored code quality
• Security Debt of Agent-Generated Code — the security register of the same debt, measured: it accrues in the CI/container plumbing (87.6% of smells sit in GitHub Actions workflows and Dockerfiles) that no session's architectural context covers, and stays invisible until a credential is exploited rather than until a rewrite is forced
• Agent-Generated Test Quality — "stealth technical debt" in the test suite: agent tests reach the disk and non-deterministic APIs at ~1.4× the human rate, so the suite passes today and costs CI reliability later — the same advertise-nothing property as a working feature that hides its architectural premise, and a debt that accrues in the environment rather than the architecture. The coverage cut on that page is this page's mechanism stated in the testing register by the source itself: untested code paths "create technical debt that accumulates silently until regression failures emerge in production," and it is measured — 50.4% of code-changing agentic PRs carry no test change and existing tests reach 27.0% of changed lines in Python. A working feature advertises nothing about its architectural premise; a green suite advertises nothing about whether it touched the diff
• Review as the Control Point — comprehension debt is this architectural debt's cognitive twin in the CMU code-review theory: low review depth + code opacity accrue it, and it feeds reinforcing loops that erode maintainability, ownership, and future review skill — and it accrues even when review depth stays high ("tasting the dish, not reading the recipe")
• Efficiency Debt of AI-Generated Code — the same missing-context mechanism denominated in compute: AI-generated C++ writes ~2x the explicit loops and 30-40% fewer standard-library calls, which lands as ~5% relative compute and ~8% relative memory overhead in production. Two things make it this page's sibling rather than a separate topic. The paper's own hypothesis for the cause is "generalist LLMs lacking the highly specific context of internal enterprise monorepo structures," and its proposed fix is a knowledge base injecting that context at prompt time — the CLAUDE.md remedy reached independently from profiling data, and unlike the Khatri ablation it has a measured payoff (an 11.1% reduction in targeted findings). It also names the debt's maturity moment: this one never forces a rewrite, it just bills more every month
• Prototype Fidelity After Cheap Polish — Boehm's 1988 "spaghetti code difficulties" is this page's argument in its original form, and the reason evolutionary prototyping never worked; whether GenAI resolves it or automates the same mistake is the fork this page's evidence answers

Open Questions#

• How long does a CLAUDE.md remain accurate as a codebase evolves? The playbook gestures at session-by-session updates; no data on rot rate. (Partially answered — not answered — by Khatri 2026: rot rate is still unmeasured, but the question's stakes move. If a Good/Excellent-rated file buys no correctness over having none, then a stale file costs correspondingly little correctness too, and the rot that matters is in the environment-fact content (test cost, deployment invariants) that carried the one measured effect. The measurement still owed is a longitudinal one: does a file's accuracy decay track anything observable in agent behaviour?)
• The remedy assumes the founder is able to articulate architecture in plain language. Non-technical founders (the playbook's headline beneficiary group) may have neither the vocabulary nor the intuition to do this well — a recursion failure the playbook doesn't address. (Deflated, not resolved, by Khatri 2026 — if the file doesn't move correctness, the founder's inability to write a good one costs less than this bullet assumes; see Founder as Agent Orchestrator.)
• Anthropic's harness-shrinkage thesis suggests CLAUDE.md may eventually be inferred by the model itself. Until then, the discipline is load-bearing.

The complexity ratchet: models add, rarely delete (Ambrosino)#

The founder's-playbook account is about drift (each session re-derives intent differently). Andrew Ambrosino (OpenAI Codex) names a second, orthogonal mechanism from the frontier-lab side: models increase complexity by default and are bad at deleting code.

"One thing all models suffer with right now is they usually increase complexity. If research is listening at any company — please make the models better at deleting code."

This is a directional bias, not just inconsistency: left to run, an agent adds abstraction, guards, and code faster than it removes them, so complexity ratchets upward every session. It's the specific barrier Ambrosino cites to putting development "completely on autopilot" (unsupervised loops) — he floats "coming in overnight and doing garbage collection of the codebase to clean it up" as a wished-for capability precisely because the default drift is toward more code, not less. Where the playbook's remedy is persistent context (fight drift), the frontier problem is a missing capability (models can't reliably simplify). Both must be solved before autonomous development is trustworthy; a first-party frontier lab reports the deletion gap as unsolved.

The same ratchet runs in the context layer, and it is measured. From Registry to Repository: How AI Agent Skills Are Written, Adapted, and Maintained (empirical) hand-codes 444 SKILL.md diffs across 5,876 GitHub repos: excluding in-place edits, additions outnumber removals 2.7:1 overall and 6.1:1 for skills evolving in place after local authorship (adoption-time customisation is near-balanced at 1.1:1, since adopters prune what doesn't apply). Developers keep appending verification steps, prohibitions, and best-practice recommendations; the only content routinely deleted is the upstream registry's licence and authorship metadata. So the artefact meant to prevent re-derivation debt (skills) accrues the same monotonic growth as the code — while simultaneously going stale: 53% of reused skills are never modified after adoption, and the largest single evolution activity is chasing renames and tooling substitutions (24.3% of diffs) as the surrounding project restructures underneath the skill. The debt is sharper than stale documentation because an agent doesn't read around an inconsistency — it executes it.

Sources#

• The Founder's Playbook: Building an AI-Native Startup — MVP Stage and Launch Stage chapters
• OpenAI Codex lead on the new shape of product work — Ambrosino: "models usually increase complexity… please make the models better at deleting code"
• From Registry to Repository: How AI Agent Skills Are Written, Adapted, and Maintained — Gao et al., arXiv 2607.00911 (empirical): §VII-A additive-maintenance asymmetry (2.7:1 overall, 6.1:1 in evolution); §VI-A 53% of reused skills never modified after adoption
• Do Context Files Help Coding Agents? A Two-Agent Ablation Study on Real Repositories — Prakhar Khatri, arXiv 2607.27250, 2026-07-28 (empirical, sole author, not peer reviewed): the first controlled ablation of the CLAUDE.md/AGENTS.md remedy — Table 1 flat pass-rates across NONE/ALWAYS ON/SELECTIVE on both agents, §5.1 the implementation-skill-not-knowledge failure triage, §5.2 the manipulation probe (the real file never flips a near-miss), Table 2 the full-suite-test-run dose effect. Bounded null, not a powered equivalence claim (MDE >30pp at n=17); scoped to single-session task correctness, so it does not test this page's cross-session drift mechanism. Two of the paper's five tables are cell-collapsed in the raw — figures here are quoted from prose