Troubleshooting Agent Issues

Overview

Agents will fail. Not occasionally -- routinely, especially in the early days of adoption. The difference between teams that succeed with agents and teams that abandon them is not the failure rate. It is whether the team has a systematic approach to diagnosing and fixing failures. This lesson gives you that system: a repeatable process for identifying why an agent went wrong, the most common failure categories, and the diagnostic tools that make troubleshooting efficient rather than frustrating.

The Troubleshooting Mindset

When an agent produces wrong output, the instinct is to blame the agent: "It is not smart enough" or "AI just cannot do this." But in the vast majority of cases, agent failures are input failures -- the agent received ambiguous instructions, insufficient context, or conflicting signals. Troubleshooting an agent is closer to debugging a misconfigured build system than debugging a logic error. The system is doing exactly what it was told; it was just told the wrong thing.

Treat every agent failure as a feedback signal about your codebase's readiness, not as evidence that agents do not work. The agent is a mirror -- it reflects the clarity (or confusion) in your project's documentation and structure.

The Diagnostic Flowchart

When an agent session produces unexpected results, follow this systematic process.

Diagnostic flowchart: starting from 'Agent produced unexpected output,' Step 1 is to review the transcript. Then check: Did the agent read the right files? If no, update CLAUDE.md with file pointers. If yes, did it follow instructions? If no, check if CLAUDE.md is clear — if not, rewrite vague instructions; if yes, check for conflicting rules. If the agent followed instructions, check if it had enough context — if no, reduce context or split the task. If yes, check if the task is well-scoped — if no, break into smaller tasks; if yes, it may be a model limitation requiring a different approach.

Step 1: Review the Transcript

The agent's transcript is your primary diagnostic tool. Every agent session produces a log of what the agent did: which files it read, which tools it called, what it wrote, and in what order. Before hypothesizing about the cause, read the transcript.

Look for these signals:

• What files did the agent read first? If it started with irrelevant files, the CLAUDE.md is not guiding it effectively
• Where did the output diverge from expectations? Identify the exact tool call where things went wrong
• Did the agent explain its reasoning? Many agents produce chain-of-thought that reveals misunderstandings
• Did the agent encounter errors? Failed tool calls, permission denials, or compilation errors often redirect the agent down the wrong path

Step 2: Check the Instructions

If the transcript shows the agent read the CLAUDE.md but still went wrong, the instructions themselves are the problem. Common instruction failures include:

• Vague language -- "write clean code" means nothing actionable. "Use early returns, avoid nesting beyond three levels, prefer named exports" is actionable
• Contradictory rules -- "keep functions short" and "avoid creating too many helper functions" work against each other
• Missing context -- the CLAUDE.md describes conventions but not where they apply. "Use the repository pattern" without specifying which modules use it
• Buried critical rules -- an important constraint on line 200 of a 250-line CLAUDE.md may be lost when context is tight

Step 3: Evaluate Task Scope

Even with perfect instructions, some tasks are too broad for a single agent session. If the agent produced partially correct output -- got some things right but missed others -- the task may have exceeded what a single context window can hold.

The Five Most Common Failures

Understanding the most frequent failure patterns lets you diagnose issues faster. Each pattern has a distinct symptom, root cause, and fix.

1. Agent Ignores Instructions

Symptom: The agent's output violates rules clearly stated in CLAUDE.md -- wrong naming conventions, forbidden imports, incorrect patterns.

Root cause: Almost always one of three things:

• The CLAUDE.md is too long, and critical instructions are pushed out of the model's effective attention window
• The instructions are present but ambiguous -- the agent interpreted them differently than you intended
• Conflicting instructions elsewhere (inline comments, other config files) override the CLAUDE.md

Fix: Prioritize your CLAUDE.md. Put the most critical rules in the first 50 lines. Be concrete -- include examples of both correct and incorrect patterns.

2. Agent Edits Wrong Files

Symptom: The agent modifies files it should not touch, or makes changes in the wrong part of the codebase.

Root cause: The codebase structure is ambiguous from the agent's perspective. Multiple directories with similar names, no clear ownership boundaries, or missing pointers in the CLAUDE.md.

Fix: Add explicit file-location guidance and off-limits declarations.

3. Agent Loops Without Progress

Symptom: The agent repeats the same action, makes a change then reverts it, or enters a cycle of attempting and failing the same approach.

Root cause: The task is ambiguous, the agent cannot determine success criteria, or each attempted approach triggers a failure that sends it back to the starting state.

Agent loop pattern vs fix: the loop shows the agent attempting approach A, tests failing, reverting changes, and attempting approach A again in an endless cycle. The fix breaks the loop by clarifying success criteria, providing explicit approach guidance, and adding constraints that eliminate dead ends.

Fix: Define success criteria explicitly in the task description. If the agent should use approach B instead of A, say so. If there are known dead ends, mention them.

4. Context Overflow

Symptom: The agent starts well but degrades over the course of a long session. Late-session output ignores instructions that early-session output followed. The agent "forgets" conventions it was following minutes earlier.

Root cause: Context overflow occurs when the accumulated content of the session -- the CLAUDE.md, files read, previous tool calls, and generated output -- exceeds the model's effective context window. Even if the model technically supports 200K tokens, attention quality degrades well before that limit.

Fix: Keep sessions focused. One task per session. If a task requires reading many files, restructure it so the agent can work incrementally.

5. Agent Produces Syntactically Valid but Semantically Wrong Code

Symptom: The code compiles, the types check, but the behavior is wrong. The agent wrote a function that returns the wrong result, implements the wrong algorithm, or misunderstands the domain logic.

Root cause: The agent lacks domain context. It knows the language and framework but not the business rules. This is the hardest failure to catch because automated tools (linters, type checkers) cannot detect it.

Fix: Add domain context to the CLAUDE.md. Include business rule summaries, link to design documents, and provide example inputs and expected outputs.

Reading Agent Transcripts Effectively

The transcript is a gold mine of diagnostic information, but only if you know what to look for. Here is a structured approach to reading transcripts.

Scan the tool call sequence first. Before reading any content, look at just the sequence of actions: Read file X, Read file Y, Edit file Z, Run tests. Does this sequence make sense for the task? If the agent read files in an unexpected order, that tells you something about how it navigated the codebase.

Find the pivot point. Identify the exact moment the agent's output went from reasonable to wrong. The tool call immediately before the pivot is usually the most diagnostic -- it reveals what information (or lack of information) triggered the wrong path.

Compare successful vs. failed sessions. If you have a session where the agent did the same type of task correctly, compare the two transcripts side by side. The differences reveal what contextual factor changed.

Check for error recovery. When the agent encounters an error (failed test, compilation error), how does it respond? Good error recovery means the feedback loops are working. Poor recovery -- ignoring the error or making random changes -- means the error messages are not informative enough.

Building a Failure Library

Over time, your team will encounter the same failure patterns repeatedly. Create a failure library -- a shared document that records each significant failure, its root cause, and the fix applied.

Each entry in the failure library is a permanent improvement. Over months, the library becomes a diagnostic reference that new team members use to solve known problems in minutes instead of hours.

When the Problem Is Not the Agent

Sometimes the issue is not the agent, the CLAUDE.md, or the task description. It is the codebase itself.

• Flaky tests -- if tests pass and fail randomly, the agent cannot use them as feedback. Fix the tests before blaming the agent
• Implicit dependencies -- if the code requires environment variables, running services, or undocumented setup steps, the agent will fail on tasks that depend on them
• Circular dependencies -- if modifying file A requires understanding file B, which requires understanding file C, which imports from file A, the agent faces the same confusion a human developer would
• Missing type information -- in dynamically typed languages, the agent guesses types. Adding type hints (Python type annotations, JSDoc in JavaScript) dramatically reduces semantic errors

The best way to find what is unclear in your codebase is to watch an agent try to work in it. Agents are the ultimate "new developer" test -- they expose every implicit assumption.

Summary

Troubleshooting agent issues is a systematic process, not guesswork. Start by reviewing the transcript to find the pivot point where things went wrong. Check whether the instructions were clear, specific, and non-contradictory. Evaluate whether the task scope fit within a single context window. Learn the five most common failure patterns -- ignored instructions, wrong files, loops, context overflow, and semantic errors -- and their corresponding fixes. Build a failure library that turns each diagnosis into a permanent improvement. Most importantly, treat failures as signals about your codebase's readiness rather than the agent's capability. In the next lesson, we will shift from diagnosing issues to preventing them, with a security audit checklist for repositories where agents have write access.