Common Agent Failures

Overview

AI coding agents fail. They fail in ways that are sometimes obvious and sometimes subtle, sometimes harmless and sometimes destructive. The good news is that most agent failures follow predictable patterns, and once you know those patterns, you can design your codebase to prevent them.

This lesson catalogs the most common failure modes, explains why they happen (connecting back to the agent loop, context window, and decision-making concepts from earlier lessons), and provides concrete codebase-level strategies to prevent each one.

Failure Mode 1: Path Hallucination

Path hallucination is when an agent references a file or directory that does not exist. The agent invents a plausible path based on common conventions and its understanding of the project -- but the path is wrong.

Why it happens: The LLM predicts likely file paths based on patterns in its training data. If your project uses an unconventional structure, the model's predictions will be wrong.

How to prevent it:

• Document your project structure in CLAUDE.md
• Use conventional directory names where possible
• Include a brief file map in your project documentation
• Encourage agents to search before assuming paths

Two strategies for finding a file: the bad strategy guesses the path (Read /src/utils/validators.ts), gets a 'file not found' error, and wastes a loop plus tokens. The good strategy searches first for 'validation', finds the correct path (src/lib/validation/index.ts), and reads the right file directly.

Failure Mode 2: Editing the Wrong File

This failure is more dangerous than path hallucination because it succeeds -- the agent makes changes, but to the wrong file. This often happens when:

• Multiple files have similar names (e.g., user.ts in three different directories)
• The agent loses track of which file it was working on after context truncation
• The agent confuses a test file with the source file

Why it happens: The agent's decision about which file to edit is based on its current context. If the context is ambiguous (multiple files match), the agent may pick the wrong one.

How to prevent it:

• Use unique, descriptive file names that clearly indicate purpose
• Avoid having identically named files in different directories
• Keep related files in the same directory so the agent encounters them together
• Document the canonical location for important logic in CLAUDE.md

Failure Mode 3: Context Overflow Amnesia

When the context window fills up and older messages are truncated, the agent can forget critical information it learned earlier. This manifests as:

• Re-reading files it already read
• Reversing decisions it made earlier in the session
• Forgetting constraints ("do not change the public API") it acknowledged earlier
• Losing track of a multi-step plan

Why it happens: Context overflow is a fundamental limitation of the architecture. The agent literally cannot see information that has been truncated.

How to prevent it:

• Keep critical constraints in CLAUDE.md (which is re-injected at every turn in some frameworks)
• Break large tasks into smaller sessions to avoid hitting context limits
• Use linters and type systems that enforce constraints automatically -- if the constraint is checked by tooling, the agent does not need to remember it
• Keep files small to reduce per-turn token consumption

Failure Mode 4: The Infinite Fix Loop

The infinite fix loop occurs when an agent's fix for one problem creates a new problem, and the fix for that creates another, cycling endlessly.

Infinite fix loop: agent edits function A, which breaks test for function B. Agent fixes B, which breaks test for C. Agent fixes C, which breaks test for A — cycling back to the start. Root cause: the agent does not understand the dependency chain A → B → C → A.

Why it happens: The agent does not have a holistic understanding of the dependencies between components. It fixes problems locally without seeing the global impact.

How to prevent it:

• Make dependencies explicit through imports and type definitions
• Document circular or complex dependencies in CLAUDE.md
• Write tests that fail with clear error messages indicating the root cause, not just the symptom
• Keep module coupling low -- loosely coupled code has fewer cascading failures

Failure Mode 5: Style and Convention Drift

Convention drift is when the agent produces code that works correctly but does not match your project's style, patterns, or conventions. Examples include:

• Using a different error handling pattern than the rest of the codebase
• Naming variables in camelCase when the project uses snake_case
• Creating a new utility function when an equivalent one already exists
• Using a different library for the same purpose (e.g., adding axios when the project uses fetch)

Why it happens: The agent draws on its general training data, which contains millions of valid but different ways to write the same code. Without explicit guidance, it may pick a pattern from its training rather than matching your project's conventions.

How to prevent it:

• Document your conventions in CLAUDE.md: error handling, naming, patterns, preferred libraries
• Use linters (eslint, ruff, rubocop) that enforce conventions automatically
• Use type checking that catches type mismatches (TypeScript strict mode, mypy)
• Include example code in your documentation that demonstrates the correct pattern

Key insight: Linters and type checkers are not just for humans. They serve as automated reviewers of agent output, catching convention drift before it reaches your codebase.

Failure Mode 6: Incomplete Changes

An agent may make a change to one file but miss the other files that need corresponding updates. Common examples:

• Changing a function signature without updating all call sites
• Adding a new field to a data model without updating serialization, validation, and tests
• Renaming a module without updating imports across the codebase

Why it happens: The agent works with the files it has read. If related files are scattered across the project and the agent does not search for them, it will miss them.

How to prevent it:

• Use TypeScript, mypy, or other type systems that catch mismatches at compile time
• Colocate related files (put the test next to the source, the types next to the implementation)
• Run the build after changes -- build failures catch incomplete changes
• Document cross-cutting concerns in CLAUDE.md ("When modifying the User type, also update the migration, the API schema, and the test fixtures")

Failure Mode 7: Hallucinated APIs and Syntax

Agents sometimes use APIs that do not exist in the version of a library your project uses, or invent syntax that looks plausible but is incorrect.

Why it happens: The LLM's training data includes many versions of many libraries. It may mix up APIs from different versions or even different libraries.

How to prevent it:

• Pin dependency versions and document them
• Include a brief note about key library versions in CLAUDE.md
• Use TypeScript or type-checking tools that catch invalid method calls
• Keep lock files (package-lock.json, yarn.lock) committed so the agent can check actual versions

The Defense-in-Depth Strategy

No single technique prevents all agent failures. The most resilient codebases use a layered defense:

Defense-in-depth strategy with four layers: Layer 1 Documentation (CLAUDE.md, architecture docs, code comments) feeds into Layer 2 Code Structure (small files, consistent naming, explicit dependencies), then Layer 3 Automated Checks (type checking, linting, formatting), then Layer 4 Tests (unit, integration, clear error messages). An agent's change passes through all layers; if all pass, the change is likely correct; if any fail, the error is caught before merging.

Each layer catches different types of failures:

• Documentation prevents the agent from making wrong assumptions
• Code structure makes the right path obvious and the wrong path difficult
• Automated checks catch syntax, type, and style errors immediately
• Tests verify behavior is correct and catch regressions

When all four layers are in place, agent failures are caught early and cheaply. When layers are missing, failures slip through and reach production.

Summary

Agent failures are predictable and preventable. The seven common failure modes and their primary defenses are:

• Path hallucination -- document project structure, use conventional paths
• Wrong file edits -- use unique descriptive names, avoid duplicate filenames
• Context amnesia -- keep constraints in always-loaded docs, break large tasks into sessions
• Infinite fix loops -- reduce coupling, write clear error messages, document dependencies
• Convention drift -- document patterns, enforce with linters and type checkers
• Incomplete changes -- use type systems, colocate related files, run the build
• API hallucination -- pin versions, use type checking, document key library versions

The overarching principle: make the right thing easy and the wrong thing detectable. The next module will show you how to implement these defenses systematically, starting with the documentation layer.