Anthropic gave the failure mode I kept hitting with Claude Code a name: agentic technical debt

Eduardo Mendes — Tue, 02 Jun 2026 20:38:59 +0000

If you've built anything non-trivial with Claude Code (or Cursor, or Cline), you know the shape of this. Session 1 is magic. Code just flows. By session 3 the agent proposes an architecture different from the one you chose. By session 7 there are two implementations of the same feature and nobody remembers which one is right.

For a long time I blamed myself, or half-blamed the model. Then I hit the term in Anthropic's founder playbook: agentic technical debt. The distinction they draw is what stuck. Ordinary tech debt sits still, and you can clear it in a focused sprint. Agentic debt compounds. Without your specs and decisions written down where the agent reads them first, every session re-derives the foundational choices from scratch, and they drift. After enough sessions the codebase has no mental model behind it. Every piece works on its own. They were just never meant to sit together.

For a while I figured I wasn't good enough at this. Wrong read. The agent is strong enough to rebuild your architecture on its own, and nothing holds it to the one you picked. It reads the repo, writes the feature, runs the tests, all unsupervised. It moves at full speed, so it drifts at full speed. By session 3 you've got a Frankenstein, shipped faster than ever. I tried better prompts. I tried bolting memory onto it. What held was a method that keeps the agent on the architecture I picked, every session.

Before anyone says it: yes, there are memory tools now (memory MCPs, session memory). They help. But they fix recall, not direction. An agent can remember every past session and still drift right off the plan. Remembering a decision and being held to it are two different problems, and only the first one really has tools yet.

Here's the boring version that worked for me, after months of breaking it and fixing it:

Document before you code. Before the first session I write the decisions down: business model, PRD with explicit in/out of scope, the DB schema in plain language, the system architecture, and a CLAUDE.md with the hard rules the agent reads every session. The out-of-scope list does more work than it looks like. It's what stops the agent from "helpfully" rebuilding something next week.
Run each session in three phases. Phase 0, the agent reads the docs. Phase 1, it validates scope and flags anything that conflicts with what's already decided. Phase 2, it implements the declared scope, and I review at the end through the branch's commits. Skip the order and it wanders off again.
Record each real decision as an ADR: context, decision, rationale, rejected alternatives. Next session the agent reads the ADR instead of relitigating a choice you already made. This one habit did the most for me.

I'd like to hear how everyone else handles this. Do you keep an ADR log? Does your CLAUDE.md survive past a week, or does it rot by Friday? What's the session ritual that actually holds for you?

Full disclosure: I packaged the templates, the session ritual, and a production codebase I built solo this way into a kit. Link's in my profile if you want it. The three steps up there are the whole idea, though, and they cost nothing to try tonight.

DEV Community: Eduardo Mendes

Anthropic gave the failure mode I kept hitting with Claude Code a name: agentic technical debt