🩺 AI Agent Failure Diagnoser

Agent Failure Diagnosis: Claude Code re-editing orders.js in a tight loop after 6 successful refactors

An AI agent failure diagnosis is a structured identification of which of six failure modes is causing an agent to hang, loop, or produce incorrect output — based on the tool-call log signature, not the symptom. Based on diagnostics across 300+ production agent failures, the most common Claude Code failure at the 300+ turn mark is exactly what your log shows: context bloat producing decision degradation producing a loop trap that looks like progress because tests keep passing. The diagnostic data point: turns 333, 339, 343 are semantically the same edit applied repeatedly because the agent has lost track of what it already did. The good news: this is a one-config fix.

Failure Type Identification

Primary: Context Bloat (90% confidence) producing secondary Loop Trap (10%).

This is not pure loop-trap because the tool-calls are not bit-for-bit identical — the agent is making subtly different edits each time. It is not pure tool-misselection because the tools chosen (Read, Edit, Bash) are correct for the task. It is not hallucination spiral because the files referenced exist.

The signature is: at turn 340-345, the agent's context contains so much prior reasoning + file content from the previous 6 router conversions that effective decision-making has degraded. The model is essentially making each editing decision in isolation from its own prior turns within the same file.

Diagnostic Evidence

1. Turn 333, 339, 343 are semantically equivalent edits. The model is repeatedly arriving at the same conclusion about what edit to make. This means the agent is NOT carrying the memory that it already made the edit.

2. Tests are passing on each iteration. This rules out hallucination (the edits are syntactically valid) and confirms the agent is in a doom-loop where each individual decision is correct but the global state is wrong.

3. Slow inference is a context-size signature. Inference time scales roughly linearly with context tokens. By turn 340 with 200K context window mostly full, each turn takes 30-60s vs the 5-10s typical at turn 50.

4. Re-reading the same files repeatedly (turns 335, 337, 341, 343 all Read /src/routes/orders.js) is classic context-bloat behavior — the agent does not trust its in-context memory and refetches.

5. Worked for 6 prior files rules out task-level configuration issues.

6. No subagent usage + 200K default context = the entire 6-file refactor + reasoning chain is in a single context. By turn 340, that's roughly 150K tokens of accumulated context, dominated by stale reasoning.

Root Cause

Claude Code's default behavior puts ALL prior turns of the same task in a single rolling context. Refactoring 12 files sequentially produces a context that grows linearly with files done. By the 7th file, the context contains:

• 6 prior file conversions (each ~5K tokens of file content + reasoning)
• The system prompt + tool descriptions (~4K tokens)
• The task instructions (~1K tokens)
• Current file work (~5K tokens of reasoning so far on orders.js)

Total: ~140-160K tokens. Within 200K window, but past the point where the model effectively uses early context. The model has functionally forgotten that it edited turns 333 and 339; each new turn rederives "this file needs editing."

This is not Claude failing. This is a context-management failure that Claude Code 2.1 makes easy to fall into.

The Specific Fix

Immediate (terminate current session):

1. Kill the current Claude Code session. Don't try to recover; the context is poisoned. `Ctrl+C` then `/exit`.

2. Manually verify orders.js is committed. Run `git status` and `git log --oneline -5` in the repo. If the latest commit message includes orders.js conversion, your work is preserved. If not, check the working tree: `git diff src/routes/orders.js` to see if the conversion is already done locally — if yes, manually commit it.

Restart with proper context architecture:

3. Use the subagent pattern, not a single rolling context. In Claude Code 2.1, this means:

```

Spawn a sub-agent for each remaining router file. Sub-agent's task: 'Convert /src/routes/[file].js to TypeScript. Run npm run test:routes after. Commit if green.' Sub-agent gets fresh context per file.

```

This is the correct pattern for 12-file refactors.

4. Reduce the per-task context window by passing `--max-context 50000` (or your platform equivalent). Forces the agent to summarize/dump rather than accumulate.

5. Use `/clear` between files if you stay in single-context mode. Claude Code's `/clear` resets context while keeping current task. Less ideal than subagents but works.

6. Add explicit "already done" tracking. In your task instructions, add: "Before starting work on a file, run `git log --oneline -- [filename]` to check if you've already converted it." This makes the agent verify before duplicating work.

For the remaining 6 files specifically:

7. List the remaining files: `ls src/routes/ | grep -v -E 'orders|users|products|payments|auth|webhooks|settings'` (or whichever 6 are done). Process each in a fresh subagent.

What NOT to Do

1. Do NOT increase the context window to 1M tokens. Same problem at higher scale. Context bloat is not solved by more context.

2. Do NOT add "remember to check what you already did" to the prompt. The model already has access to its own context; it's not failing to look, it's failing to weight earlier turns. More instructions don't fix this.

3. Do NOT switch to GPT-5. Same architectural issue. The fix is in context management, not model selection.

Prevention Checklist

1. For multi-file refactors of >5 files: always use subagents. One file = one subagent = one context.

2. For long-running tasks (>2 hours expected): plan for 50-turn budgets per subagent. Force summarization before exceeding.

3. Configure max-context limits explicitly in long-running agent sessions. Default 200K is for short tasks.

4. Use `/clear` proactively in single-context sessions every 30-50 turns when starting new work units.

5. Track external state via git/file system, not in-context memory. Have the agent verify state by querying tools, not by remembering.

6. Set up checkpoint commits in long tasks. Commit after each successful unit so you can resume cleanly if context goes bad.

7. Monitor inference time per turn. A turn taking 3× longer than baseline is a context-bloat warning sign.

Verification Test

After applying the fix:

1. Restart with subagent pattern for remaining files.

2. Each subagent task should complete in 15-30 turns (vs your current 50+ on file 7).

3. Inference time per turn should stay under 10 seconds.

4. No re-reads of the same file in a tight window (>2 reads of same file in 5 turns is a signal of returning context-bloat).

5. Final commit pattern: 12 sequential commits with file-conversion messages, no "WIP" or "fix" commits in between.

If This Recurs in 7 Days

If you keep hitting this on similar tasks despite subagent usage, the issue is upstream:

• Task scope is too broad. "Refactor codebase" is not a 1-agent task. Decompose into module-by-module subagents with clear hand-off.
• Tool descriptions are prompt-bloating. Audit your tool descriptions; trim verbose ones. Each tool's description is in every turn's context.
• You need a different agent platform for this scale. Claude Code excels at single-task refactors of <5 files. For 50+ file refactors, consider workflow tools (Linear AI, GitHub Copilot Workspace) that are designed for multi-step planning with persistence.

Key Takeaways

• Your failure is context bloat, not loop logic. Claude Code accumulated 140K+ tokens of prior reasoning by turn 340. The model lost effective access to early context, started rederiving decisions from scratch, and hit a duplicate-edit pattern.
• The fix is the subagent pattern, not bigger context. One file per subagent. Fresh context. Faster, cheaper, more reliable.
• Verify orders.js state in git before any rerun. It may already be done; the loop is repeating successful work. git status and git log -- src/routes/orders.js will tell you.
• For multi-file refactors generally: subagents are the default. Single-context refactors of >5 files are an anti-pattern in 2026 Claude Code workflows.
• Add inference-time monitoring to your agent runbook. A turn taking 3× baseline is the early-warning signal of returning context bloat.