16.1 Multi-File Code Generation

1. Why Single-File Generation Is Not Enough

Consider a seemingly simple task: "Add a created_at timestamp field to the Experiment model." In a well-structured repository, this single requirement touches at minimum five files:

1. The model definition (models/experiment.py): add the field.
2. The database migration (migrations/add_created_at.py): generate the ALTER TABLE statement.
3. The serializer (api/serializers.py): include the new field in API responses.
4. The test fixtures (tests/conftest.py): update factory functions to supply the field.
5. The API documentation (docs/api.md or an OpenAPI spec): reflect the new response shape.

A coding agent that edits only the model file produces a change that fails on the next database query, returns incomplete API responses, and breaks the test suite. The SWE-bench benchmark (Jimenez et al., 2024, ICLR) found that approximately 67% of real GitHub issues require edits to two or more files, and roughly 31% require edits to four or more (circa 2024). Multi-file consistency is not an edge case; it is the common case.

When a coding agent misses even one file in a coordinated change, the result is not a minor inconvenience; it is a broken build, a failed deployment, or a silent data corruption that surfaces weeks later in production. Understanding the structure of multi-file edits is what separates a useful assistant from a liability.

Multi-file code generation produces a coordinated set of source code changes across multiple files in a repository. All cross-file references (imports, function calls, type annotations, configuration keys) must remain valid after every edit. Real software changes almost never live in a single file: a field added to a data model ripples into serializers, migrations, tests, and documentation. Any mismatch between these files produces runtime errors or silent data corruption. The approach builds a dependency graph of the planned edits and topologically sorts it so that each file is generated only after the files it references are finalized. Each generation step receives the actual content of its dependencies as prompt context. Use this approach whenever a change touches two or more files with cross-references; for isolated, single-file edits (a local bug fix, a docstring update), standard single-file generation is sufficient.

Formalizing Consistency

We can quantify the coordination challenge. Let \(F = \{f_1, f_2, \ldots, f_n\}\) be the set of files affected by a change, and let \(E = \{e_1, e_2, \ldots, e_n\}\) be the corresponding edits. A change is consistent if every symbol referenced in \(e_i\) is either defined in \(f_i\) itself or defined (with a compatible signature) in some \(f_j\) where \(e_j\) has already been applied. Formally, let \(\text{refs}(e_i)\) be the set of external symbols referenced by edit \(e_i\), and let \(\text{defs}(e_j)\) be the symbols defined by edit \(e_j\). The consistency condition is:

where \(\text{sig}(s, e_j)\) is the signature of symbol \(s\) as defined in edit \(e_j\), and \(\text{usage}(s, e_i)\) is how edit \(e_i\) calls or references \(s\). This condition holds automatically in single-file edits (where all references resolve internally) but becomes a genuine constraint when edits span the module boundary.

2. The Edit Graph Abstraction

To reason about multi-file changes, we introduce the edit graph: a directed acyclic graph (DAG) where nodes represent file-level edits and edges represent dependencies between them. An edge from \(e_i\) to \(e_j\) means "edit \(e_j\) references symbols that \(e_i\) defines or modifies." The topological order of this DAG gives us a safe generation sequence.

Building the edit graph requires two pieces of information: the existing dependency structure of the repository (which files import from which other files) and the planned change (which files will be affected and what symbols each edit will introduce or modify). We extract the first from the codebase using tree-sitter (an incremental parsing library that builds concrete syntax trees from source code without requiring a full compiler toolchain); the second comes from the task decomposition step. In short: define before you reference, and generate in that same order. Figure 16.1 illustrates this structure for the "add created_at" example.

from dataclasses import dataclass, field
from collections import defaultdict

@dataclass
class FileEdit:
    """A planned edit to a single file."""
    path: str
    description: str
    symbols_defined: set[str] = field(default_factory=set)
    symbols_referenced: set[str] = field(default_factory=set)
    depends_on: list[str] = field(default_factory=list)

@dataclass
class EditGraph:
    """DAG of file edits with dependency edges."""
    edits: dict[str, FileEdit] = field(default_factory=dict)

    def add_edit(self, edit: FileEdit) -> None:
        self.edits[edit.path] = edit

    def resolve_dependencies(self) -> None:
        """Compute dependency edges from symbol references."""
        # Build a map: symbol -> file that defines it
        symbol_sources: dict[str, str] = {}
        for path, edit in self.edits.items():
            for sym in edit.symbols_defined:
                symbol_sources[sym] = path

        # Resolve each edit's references to dependencies
        for path, edit in self.edits.items():
            for sym in edit.symbols_referenced:
                source = symbol_sources.get(sym)
                if source and source != path:
                    if source not in edit.depends_on:
                        edit.depends_on.append(source)

    def topological_order(self) -> list[str]:
        """Return file paths in dependency-safe generation order."""
        in_degree: dict[str, int] = {p: 0 for p in self.edits}
        for edit in self.edits.values():
            for dep in edit.depends_on:
                if dep in in_degree:
                    in_degree[edit.path] = in_degree.get(edit.path, 0)
                    # dep must come before edit.path
                    pass

        # Kahn's algorithm (a BFS-based method that repeatedly
        # removes nodes with zero in-degree to produce a
        # topological ordering)
        adj: dict[str, list[str]] = defaultdict(list)
        in_deg: dict[str, int] = {p: 0 for p in self.edits}
        for path, edit in self.edits.items():
            for dep in edit.depends_on:
                if dep in self.edits:
                    adj[dep].append(path)
                    in_deg[path] += 1

        queue = [p for p, d in in_deg.items() if d == 0]
        order = []
        while queue:
            node = queue.pop(0)
            order.append(node)
            for neighbor in adj[node]:
                in_deg[neighbor] -= 1
                if in_deg[neighbor] == 0:
                    queue.append(neighbor)

        if len(order) != len(self.edits):
            cycle_nodes = set(self.edits) - set(order)
            raise ValueError(f"Circular dependency among: {cycle_nodes}")

        return order

The EditGraph captures the essential structure of a multi-file change. Each FileEdit declares what symbols it will define and what symbols it needs from other files. The resolve_dependencies method computes the edges, and topological_order produces a safe generation sequence. If the graph contains a cycle (file A depends on file B which depends on file A), the method raises an error, signaling that the change plan needs restructuring; see Section 16.1.5 for strategies to break such cycles.

3. Extracting Dependencies with Tree-Sitter

The edit graph needs to know which symbols each file imports and exports. We extract this information using tree-sitter, the same incremental parser we used for chunking in Chapter 11. Tree-sitter parses source code into a concrete syntax tree (CST, a parse tree that preserves every token including whitespace and punctuation, unlike an abstract syntax tree which discards syntactic details), making it possible to extract import statements, function signatures, and class definitions with byte-level precision.

import tree_sitter_python as tspython
from tree_sitter import Language, Parser

PY_LANGUAGE = Language(tspython.language())
parser = Parser(PY_LANGUAGE)

def extract_imports(source: str) -> list[dict]:
    """Extract all import statements from Python source code."""
    tree = parser.parse(source.encode("utf-8"))
    imports = []

    # Query for import statements
    import_query = PY_LANGUAGE.query("""
        (import_statement
            name: (dotted_name) @module)
        (import_from_statement
            module_name: (dotted_name) @module
            name: (dotted_name) @name)
    """)

    captures = import_query.captures(tree.root_node)
    for node, name in captures:
        imports.append({
            "type": name,
            "text": node.text.decode("utf-8"),
            "line": node.start_point[0] + 1,
        })
    return imports

def extract_definitions(source: str) -> list[dict]:
    """Extract top-level function and class definitions."""
    tree = parser.parse(source.encode("utf-8"))
    defs = []

    def_query = PY_LANGUAGE.query("""
        (function_definition
            name: (identifier) @func_name
            parameters: (parameters) @params)
        (class_definition
            name: (identifier) @class_name)
    """)

    captures = def_query.captures(tree.root_node)
    for node, name in captures:
        # Only top-level definitions (depth 1 from module)
        if node.parent and node.parent.parent == tree.root_node:
            defs.append({
                "type": "function" if name == "func_name" else "class",
                "name": node.text.decode("utf-8"),
                "line": node.start_point[0] + 1,
            })
    return defs

# Example: analyze a source file
source = '''
from models.base import BaseModel
from utils.timestamps import now

class Experiment(BaseModel):
    def __init__(self, name: str):
        self.name = name
        self.created_at = now()
'''

print("Imports:", extract_imports(source))
print("Definitions:", extract_definitions(source))

With these extraction functions, we can scan every file in the repository and build a complete dependency graph. The graph tells us, for any proposed edit, which files might be affected: if we change the signature of BaseModel.__init__, every file that imports from models.base is a candidate for a cascading edit. This is the foundation of the impact analysis we build in Section 16.2.

4. The Multi-File Generation Pipeline

With the edit graph in place, we can define a generation pipeline that produces consistent multi-file changes. The pipeline has four stages. (1) Task decomposition breaks a high-level request into file-level edit descriptions. (2) Dependency resolution constructs the edit graph and topologically sorts it. (3) Sequential generation produces each edit in dependency order, including preceding edits in the context. (4) Consistency validation checks the combined patch for import coherence and type compatibility. Figure 16.1.1 illustrates the edit graph and multi-file generation pipeline.

import subprocess
import json
from pathlib import Path

class MultiFileGenerator:
    """Orchestrates multi-file code generation in dependency order."""

    def __init__(self, repo_root: str, model: str = "claude-sonnet-4-20250514"):
        self.repo_root = Path(repo_root)
        self.model = model
        self.generated_edits: dict[str, str] = {}  # path -> new content

    def decompose_task(self, task: str) -> EditGraph:
        """Use an LLM to decompose a task into file-level edits."""
        prompt = f"""Analyze this repository and decompose the following task
into file-level edits. For each file, specify:
- path: the file to edit
- description: what changes to make
- symbols_defined: new symbols this edit introduces
- symbols_referenced: symbols from other edited files this edit needs

Task: {task}

Respond in JSON: [{{"path": "...", "description": "...",
"symbols_defined": [...], "symbols_referenced": [...]}}]"""

        result = subprocess.run(
            ["claude", "--print", "--model", self.model,
             "--max-tokens", "4096", "-p", prompt],
            capture_output=True, text=True, cwd=self.repo_root
        )
        edits_data = json.loads(result.stdout)

        graph = EditGraph()
        for ed in edits_data:
            graph.add_edit(FileEdit(
                path=ed["path"],
                description=ed["description"],
                symbols_defined=set(ed.get("symbols_defined", [])),
                symbols_referenced=set(ed.get("symbols_referenced", [])),
            ))
        graph.resolve_dependencies()
        return graph

    def generate_edit(self, edit: FileEdit) -> str:
        """Generate code for a single file edit with context from prior edits."""
        # Build context from already-generated edits this one depends on
        context_parts = []
        for dep_path in edit.depends_on:
            if dep_path in self.generated_edits:
                context_parts.append(
                    f"--- {dep_path} (already modified) ---\n"
                    f"{self.generated_edits[dep_path]}"
                )

        # Read the current file content if it exists
        file_path = self.repo_root / edit.path
        current_content = ""
        if file_path.exists():
            current_content = file_path.read_text(encoding="utf-8")

        prompt = f"""Apply this edit to the file.

File: {edit.path}
Current content:
{current_content}

Edit description: {edit.description}

Context from related files already modified:
{chr(10).join(context_parts) if context_parts else "(none)"}

Output ONLY the complete new file content, no explanation."""

        result = subprocess.run(
            ["claude", "--print", "--model", self.model,
             "--max-tokens", "8192", "-p", prompt],
            capture_output=True, text=True, cwd=self.repo_root
        )
        return result.stdout.strip()

    def execute(self, task: str) -> dict[str, str]:
        """Run the full multi-file generation pipeline."""
        # Stage 1: Decompose
        graph = self.decompose_task(task)

        # Stage 2: Topological order
        order = graph.topological_order()
        print(f"Generation order ({len(order)} files):")
        for i, path in enumerate(order, 1):
            deps = graph.edits[path].depends_on
            dep_str = f" (depends on: {', '.join(deps)})" if deps else ""
            print(f"  {i}. {path}{dep_str}")

        # Stage 3: Sequential generation
        for path in order:
            edit = graph.edits[path]
            print(f"\nGenerating: {path}...")
            content = self.generate_edit(edit)
            self.generated_edits[path] = content

        # Stage 4: Consistency check (see Section 16.2 for full version)
        issues = self._check_import_consistency()
        if issues:
            print(f"\nWarning: {len(issues)} consistency issues found")
            for issue in issues:
                print(f"  - {issue}")

        return self.generated_edits

    def _check_import_consistency(self) -> list[str]:
        """Basic check: do all imports resolve to defined symbols?"""
        issues = []
        all_defs: dict[str, set[str]] = {}

        for path, content in self.generated_edits.items():
            defs = extract_definitions(content)
            all_defs[path] = {d["name"] for d in defs}

        for path, content in self.generated_edits.items():
            imports = extract_imports(content)
            for imp in imports:
                # Check if imported module is one of our edited files
                module_path = imp["text"].replace(".", "/") + ".py"
                if module_path in all_defs:
                    # Imported name should exist in that module's definitions
                    if imp.get("type") == "name":
                        if imp["text"] not in all_defs[module_path]:
                            issues.append(
                                f"{path} imports '{imp['text']}' from "
                                f"{module_path}, but it is not defined there"
                            )
        return issues

The key insight in this pipeline is stage 3: each file is generated with the actual content of its dependencies in the prompt context. When the agent generates the serializer, it sees the exact field definition from the model file, not a predicted version. This eliminates the most common source of multi-file inconsistency: signature mismatch between the definition site and the usage site.

5. Failure Modes of Multi-File Generation

The generation pipeline above produces consistent patches when the edit graph is correct and complete, but in practice several systematic errors can corrupt the graph or slip past it.

Analysis of SWE-bench submissions and production coding agent logs reveals five recurring failure patterns. Each has a structural signature detectable before the code runs.

5.1 Hallucinated Imports

The agent imports a symbol that does not exist in the target module. This happens when the model "remembers" an API from its training data that differs from the actual codebase. For example, importing from utils import retry_with_backoff when the repository's utils module only exports retry. Detection: parse all import statements with tree-sitter and verify that each imported name exists in the target module's definition list.

5.2 Signature Drift

The agent calls a function with arguments that do not match its definition. This occurs when edits to the definition site and the call site are generated independently (without dependency ordering). For example, the model edit adds created_at: datetime as a required parameter, but the test fixture calls Experiment(name="test") without supplying it. Detection: extract function signatures and call sites with tree-sitter, then verify argument compatibility.

5.3 Orphaned References

The agent removes or renames a symbol in one file but fails to update all references in other files. This is the inverse of the hallucinated import: the symbol existed before the change but no longer does after. Renaming process_data to transform_data in the utility module while leaving 15 call sites unchanged produces 15 NameErrors. Detection: compute the set difference between pre-change and post-change definitions, then search for references to removed symbols.

5.4 Circular Dependencies

The planned edits create a circular import chain that did not exist before. File A imports from file B, and the new edit to file B adds an import from file A. Python handles some circular imports gracefully (if the imported name is accessed only at call time, not at import time), but many cases produce ImportError at module load. Detection: build the post-change import graph and check for cycles. The standard strategy for breaking such cycles is to extract the mutually depended-upon symbols into a new shared module that both files import from, eliminating the circular edge; alternatively, one side can defer its import to function scope (a lazy import) so the dependency is resolved at call time rather than at module load time.

5.5 Missing Transitive Edits

The agent edits the direct dependents of a changed file but misses the transitive dependents, where a transitive dependent is a file that depends on the changed file indirectly through one or more intermediate imports. Changing a base class method signature requires updating not just the immediate subclasses but also any code that calls the method through a reference to the subclass. The impact analysis of Section 16.2 addresses this by computing the transitive closure of the dependency graph (the complete set of all files reachable by following chains of import edges, not just the immediate neighbors).

from dataclasses import dataclass
from enum import Enum

class FailureType(Enum):
    HALLUCINATED_IMPORT = "hallucinated_import"
    SIGNATURE_DRIFT = "signature_drift"
    ORPHANED_REFERENCE = "orphaned_reference"
    CIRCULAR_DEPENDENCY = "circular_dependency"
    MISSING_TRANSITIVE = "missing_transitive_edit"

@dataclass
class PatchFailure:
    failure_type: FailureType
    file_path: str
    line: int
    message: str
    severity: str  # "error" or "warning"

def detect_hallucinated_imports(
    edits: dict[str, str],
    repo_definitions: dict[str, set[str]]
) -> list[PatchFailure]:
    """Detect imports that reference non-existent symbols."""
    failures = []

    for path, content in edits.items():
        imports = extract_imports(content)
        for imp in imports:
            module = imp["text"]
            # Check against both edited files and existing repo
            target_path = module.replace(".", "/") + ".py"
            available_defs = set()

            if target_path in edits:
                available_defs = {
                    d["name"] for d in extract_definitions(edits[target_path])
                }
            elif target_path in repo_definitions:
                available_defs = repo_definitions[target_path]

            if imp.get("type") == "name" and available_defs:
                if imp["text"] not in available_defs:
                    failures.append(PatchFailure(
                        failure_type=FailureType.HALLUCINATED_IMPORT,
                        file_path=path,
                        line=imp["line"],
                        message=(
                            f"Imports '{imp['text']}' from {module}, "
                            f"but available symbols are: "
                            f"{', '.join(sorted(available_defs))}"
                        ),
                        severity="error",
                    ))
    return failures

6. Orchestrating Generation with the Claude Code SDK

Detecting failure modes is only useful if the generation tooling can act on those detections, retrying or adjusting edits before the patch is finalized.

The Claude Code Software Development Kit (SDK) provides a programmatic interface for invoking Claude Code as a subprocess, enabling integration into automated pipelines. For multi-file generation, the SDK's key advantage is that each invocation can carry a different context window, allowing us to feed dependency-specific context to each generation step. The SDK supports both one-shot mode (--print, used above) and interactive conversation mode, where the agent maintains state across multiple tool calls.

import subprocess
import json

def claude_code_generate(
    prompt: str,
    repo_root: str,
    model: str = "claude-sonnet-4-20250514",
    max_tokens: int = 8192,
    allowed_tools: list[str] | None = None,
) -> dict:
    """Invoke Claude Code SDK for a single generation step.

    Returns the parsed JSON output with conversation and result fields.
    """
    cmd = [
        "claude",
        "--print",           # one-shot mode: no interactive session
        "--model", model,
        "--max-tokens", str(max_tokens),
        "--output-format", "json",
    ]

    if allowed_tools:
        for tool in allowed_tools:
            cmd.extend(["--allowedTools", tool])

    cmd.extend(["-p", prompt])

    result = subprocess.run(
        cmd,
        capture_output=True,
        text=True,
        cwd=repo_root,
        timeout=120,
    )

    if result.returncode != 0:
        raise RuntimeError(
            f"Claude Code failed (exit {result.returncode}): "
            f"{result.stderr[:500]}"
        )

    return json.loads(result.stdout)


def generate_with_retry(
    prompt: str,
    repo_root: str,
    validation_fn: callable,
    max_attempts: int = 3,
) -> str:
    """Generate code with validation and retry on failure."""
    for attempt in range(max_attempts):
        response = claude_code_generate(prompt, repo_root)
        content = response.get("result", "")

        issues = validation_fn(content)
        if not issues:
            return content

        # Augment prompt with failure feedback for retry
        feedback = "\n".join(f"- {issue}" for issue in issues)
        prompt = (
            f"{prompt}\n\n"
            f"Previous attempt had these issues:\n{feedback}\n"
            f"Please fix these issues in your response."
        )

    raise RuntimeError(
        f"Failed to generate valid code after {max_attempts} attempts"
    )

The generate_with_retry function implements a critical pattern for production-grade code generation: generate, validate, and retry. The validation function can check for any of the failure modes from Section 16.1.5, and the retry loop augments the prompt with specific failure feedback, giving the model a chance to correct its mistakes. In practice, hallucinated import errors are typically resolved on the first retry when the prompt explicitly lists the available symbols.

7. Building the Edit Plan from a Task Specification

The SDK and retry loop handle the mechanics of generation, but their output is only as good as the plan that feeds them.

The quality of multi-file generation depends critically on the quality of the initial decomposition. A vague task like "improve performance" produces a vague edit plan; a specific task like "replace the O(n^2) duplicate detection in pipeline/dedup.py with a hash-based approach and update the corresponding tests" produces a precise one. This connects directly to the requirements discovery techniques of Chapter 13: the better the specification, the better the implementation.

A well-structured edit plan has four components:

1. Scope: which files are in scope and which are explicitly out of scope.
2. Ordering: which edits must precede which others.
3. Contracts: what each edited file promises to its dependents (function signatures, class interfaces, configuration keys).
4. Verification: how to test that the change works (which test files to run, what behavior to check).

@dataclass
class EditPlan:
    """A structured plan for a multi-file change."""
    task_description: str
    scope: list[str]           # files to edit
    out_of_scope: list[str]    # files explicitly not edited
    contracts: dict[str, list[str]]  # file -> list of interface promises
    verification: list[str]    # test commands to run

    def to_prompt(self) -> str:
        """Convert the plan to a prompt for the generation pipeline."""
        lines = [
            f"Task: {self.task_description}",
            f"\nFiles to edit ({len(self.scope)}):",
        ]
        for f in self.scope:
            contracts = self.contracts.get(f, [])
            contract_str = "; ".join(contracts) if contracts else "no new interfaces"
            lines.append(f"  - {f} ({contract_str})")

        lines.append(f"\nFiles NOT to edit: {', '.join(self.out_of_scope)}")
        lines.append(f"\nVerification: {'; '.join(self.verification)}")
        return "\n".join(lines)

# Example: plan for adding a caching layer
plan = EditPlan(
    task_description="Add Redis caching to the experiment lookup endpoint",
    scope=[
        "cache/redis_client.py",
        "cache/__init__.py",
        "api/endpoints/experiments.py",
        "tests/test_experiments.py",
        "config/settings.py",
    ],
    out_of_scope=[
        "api/endpoints/users.py",   # different endpoint, not affected
        "models/experiment.py",      # model unchanged, only read path cached
    ],
    contracts={
        "cache/redis_client.py": [
            "def get_cached(key: str) -> dict | None",
            "def set_cached(key: str, value: dict, ttl: int = 300) -> None",
        ],
        "config/settings.py": [
            "REDIS_URL: str",
            "CACHE_TTL: int = 300",
        ],
    },
    verification=[
        "pytest tests/test_experiments.py -v",
        "pytest tests/test_cache.py -v",
    ],
)
print(plan.to_prompt())

The contract specification is particularly powerful. By declaring upfront that cache/redis_client.py will export get_cached and set_cached with specific signatures, we give the agent generating the endpoint file a concrete interface to code against, even before the cache module is generated. This is the software engineering principle of programming to interfaces, applied to AI-assisted code generation.

Exercises

1. (Conceptual) A repository has a module hierarchy where models/ depends on utils/, api/ depends on both models/ and utils/, and tests/ depends on all three. Draw the edit graph for a change that modifies a utility function signature, requiring updates to models, API endpoints, and tests. What is the topological order? How many files could be generated in parallel at each stage?
2. (Coding) Extend the EditGraph from Listing 16.1 to detect cycles and report the specific files involved. Test it by constructing a graph where auth/tokens.py imports from auth/users.py and vice versa. Then implement a cycle-breaking strategy that introduces a third file (auth/shared.py) to hold the shared definitions.
3. (Analysis) Run the extract_imports function from Listing 16.2 on a Python project you work with. Compute the import graph and find the module with the highest in-degree (most files import from it). Explain why changes to this module require the most careful edit planning and the largest blast radius analysis.