Code Generation Agents: Patterns and Architectures

"Writing code is easy. Writing code that passes its own tests on the first try is a miracle I perform daily."

Agent X, Suspiciously Confident AI Agent

29.1.1 The Anatomy of a Code Agent

A code-generation agent is a ReAct loop with file-system and terminal access. The agent reads source files to understand the codebase, generates code changes, runs tests or linters to verify the changes, and iterates until the tests pass or a maximum number of attempts is reached. This self-debugging capability is what distinguishes a code agent from a code-completion tool: a completion tool suggests the next line and walks away; an agent takes responsibility for the entire change and verifies its own work.

The architectural ingredients are small and well-defined. The agent needs (1) a working set of files it can read and write, (2) a sandboxed shell for executing tests and linters, (3) a search or grep tool for navigating large codebases without reading every file, and (4) a loop driver that feeds tool results back to the model on each iteration. Everything else (vendor-specific prompts, IDE integrations, MCP connectors) is product polish on top of these four ingredients. The architectural decisions that matter most are how the loop terminates, which patterns it uses to refine on failure, and how it manages context across iterations.

SWE-bench has become the standard benchmark for evaluating code agents against this architectural target. The benchmark presents real GitHub issues from popular open-source projects and measures whether the agent can produce a correct patch. Top-performing agents on SWE-bench Verified solve 50 to 60% of issues as of early 2026, with the best results coming from agents that combine strong reasoning models with effective codebase navigation and test execution tools. Comparable agents on the same benchmark differ more in their architectural patterns (covered in this section) than in their underlying models or in the brand on the box (covered in Section 29.4).

Self-Debugging Loop

This snippet implements a self-debugging loop where the agent runs code, catches errors, and iteratively fixes them.

import subprocess
from typing import Optional
class CodeAgent:
    def __init__(self, llm, max_attempts: int = 3):
        self.llm = llm
        self.max_attempts = max_attempts
    def solve_issue(self, issue_description: str, repo_path: str) -> Optional[str]:
        # Step 1: Understand the codebase
        context = self.explore_codebase(repo_path, issue_description)
        for attempt in range(self.max_attempts):
            # Step 2: Generate a patch
            patch = self.llm.invoke(
                f"Fix this issue in the codebase:\n\n"
                f"Issue: {issue_description}\n\n"
                f"Relevant code:\n{context}\n\n"
                f"{'Previous attempt failed: ' + error if attempt > 0 else ''}\n"
                f"Generate a unified diff patch."
                )
            # Step 3: Apply the patch
            self.apply_patch(repo_path, patch.content)
            # Step 4: Run tests
            result = subprocess.run(
                ["python", "-m", "pytest", "--tb=short"],
                cwd=repo_path,
                capture_output=True,
                text=True,
                timeout=120,
                )
            if result.returncode == 0:
                return patch.content # Success
                # Step 5: Analyze failure for next attempt
                error = result.stdout + result.stderr
                context = self.analyze_failure(error, context)
                return None # Exhausted attempts
            def explore_codebase(self, repo_path: str, issue: str) -> str:
                """Use file search and grep to find relevant code."""
                # Search for files mentioned in the issue
                # Read test files to understand expected behavior
                # Map the project structure
                ...
            def analyze_failure(self, error: str, context: str) -> str:
                """Use the LLM to understand why the test failed."""
                analysis = self.llm.invoke(
                    f"This test failed. Analyze the error and suggest what to fix:\n"
                    f"Error:\n{error}\n\n"
                    f"Current context:\n{context}"
                    )
                return context + f"\n\nFailure analysis:\n{analysis.content}"

The self-debugging loop is what makes code agents qualitatively different from code completion tools. A completion tool suggests code and moves on; a code agent takes responsibility for correctness by running its own output, observing failures, and iterating. This is the ReAct pattern (see Section 26.1) specialized for software engineering: the "observation" comes from the test runner rather than a web search, and the "action" is editing code rather than calling an API. The feedback loop from real test execution grounds the agent's reasoning in reality, which is why code agents outperform pure generation approaches even when using the same underlying model.

29.1.2 Three Named Architectural Patterns

On top of the self-debug loop, three architectural patterns recur in code agents that beat the baseline. Each is a different way to spend extra compute or extra LLM calls to compensate for the model's first-attempt errors.

Plan-Then-Execute

A pure ReAct loop conflates planning and acting; the model decides what to do next on every step, with little long-horizon structure. The plan-then-execute pattern (formalized in the LLMCompiler and ProgramAgent papers, ubiquitous in 2026 production systems) splits this into two phases. A planning pass uses a strong model to produce a step-by-step plan ("step 1: read auth.py to understand session validation; step 2: add a new claims field to the JWT; step 3: update verify_token; step 4: run the auth test suite"). An execution pass then runs each step with a smaller, cheaper model, falling back to the planner only when a step fails. The architectural benefit is that the model only needs to think strategically once per task, instead of re-planning on every iteration.

Tree-of-Code

The self-debug loop is a linear search: try, fail, try again with the error. A tree-of-code agent (analogous to tree-of-thoughts reasoning) generates multiple candidate patches in parallel, runs the test suite on each, and keeps the branch that produces the most passing tests. Failed branches contribute their error traces to the prompt for the next round, so the agent learns from multiple failure modes simultaneously. On SWE-bench, tree-of-code with a beam width of three typically outperforms linear self-debug at the same total token budget because rare bug classes that linear search misses (off-by-one errors, edge-case handling) are more likely to be tried by at least one branch.

Multi-Agent Code Review

The third pattern adds a second model in a critique role. An implementer agent produces a patch; a separate reviewer agent reads the diff and the failing test output and proposes corrections or red-flags. Multi-agent code-review patterns work because the implementer is biased toward defending its own code, while a fresh reviewer can identify "this fix passes the test but introduces a subtle race condition" or "this change breaks the public API in a way the tests do not cover". Production systems typically gate critical commits (auth, payments, deployment scripts) behind a reviewer pass even when the implementer's tests are green. The pattern composes naturally with plan-then-execute (the planner becomes the reviewer for completed steps) and tree-of-code (the reviewer picks the best branch).

29.1.3 Production Considerations

Production code agents combine the architectural patterns above with three operational practices that are independent of which pattern you use. Test-driven prompting writes or identifies the relevant tests first, then generates code that passes them; this is what the self-debug loop actually needs to be a tight feedback cycle. Incremental changes keep each agent action small and testable rather than asking for whole-feature rewrites in one shot, which lets the test runner provide useful signals between steps. Context management strategically selects which files to include in the prompt based on the change being made, exploiting the search-before-read pattern from 29.1.1.

The production concern that overrides all architectural choices is safety. A code agent with file-system access can overwrite important files, delete directories, or introduce security vulnerabilities. Production deployments use sandboxed environments (Docker, E2B), restrict file-system access to the project directory, run with limited permissions, and require human review for changes to critical files (configuration, authentication, deployment scripts). See Section 49.2 for details on sandboxed execution environments, and Section 29.4 for how individual vendor tools implement these guardrails.

# TODO: Define tool schemas for read_file, write_file, run_command
# and implement the agent loop that calls the LLM with tool results

# TODO: Implement retry logic with max_attempts=3
# On each failure, include the error traceback in the next prompt

# TODO: Define 5 challenges with test cases and run the agent on each

# TODO: Track metrics in a DataFrame and implement the give-up path

# Complete solution outline for the self-debugging code agent
# Key components:
# 1. Tool definitions: read_file, write_file, run_command
# 2. Agent loop: call LLM, execute tools, feed results back
# 3. Retry logic with attempt counter and error context
# 4. Metrics collection in a pandas DataFrame
# See section content for the full implementation pattern.

Exercises