Overview
Generating a single function is easy. Generating a coherent change that spans twelve files, respects existing architectural invariants, passes the test suite, and does not break three downstream services: that is the actual problem. This chapter treats multi-file code generation not as a parlor trick but as an engineering discipline with formal structure. We define what it means for a change to be consistent across a repository, build tools to analyze the impact of a proposed edit before committing it, and study the failure modes that turn promising patches into production incidents.
Section 16.1 tackles multi-file code generation: how to decompose a high-level task into a coordinated set of edits across multiple files, using dependency graphs and abstract syntax trees to maintain consistency. Section 16.2 introduces impact analysis and patch review, building a system that traces how a change in one file propagates through the dependency graph and flags potential breakage before a human ever reads the diff. Section 16.3 ties everything together in a complete recipe: executing a repository-scale change against a real open-source project, from task decomposition through impact analysis to validated patch submission.
This chapter connects backward to the context engineering techniques of Chapter 11 (which determine what the model sees) and the algorithm discovery methods of Chapter 15 (which generate candidate solutions). It connects forward to Chapter 17: Multi-Agent Software Teams, where multiple agents collaborate on changes too large for a single agent, and to Chapter 18: AI-Assisted Testing and QA, where the patches generated here are subjected to automated verification. The Discovery Workbench, introduced in Chapter 6, gains a change orchestration module that coordinates multi-file edits with impact-aware validation.
Prerequisites
This chapter assumes you have read Chapter 11: Context Engineering at Repository Scale (for understanding how agents gather repository context), Chapter 9: Vibe Coding as Specification, Steering, Verification (for the human-AI collaboration model), and Chapter 14: Discovery of Architectures (for dependency graph fundamentals). You should be comfortable with Python, basic graph algorithms (topological sort, reachability), and the git version control model (commits, diffs, branches). Familiarity with tree-sitter from Chapter 11 is helpful but not strictly required; we reintroduce the relevant APIs here.
Learning Outcomes
- Decompose a high-level implementation task into a dependency-ordered sequence of file-level edits using abstract syntax tree analysis and import graph traversal.
- Build a multi-file code generation pipeline that maintains type consistency, import coherence, and API contract stability across edits.
- Construct an impact analysis engine that computes the transitive closure of a change through the dependency graph and estimates breakage probability.
- Implement automated patch review using static analysis, test execution, and LLM-based semantic review.
- Identify and classify the common failure patterns of AI-generated multi-file changes, including hallucinated imports, signature drift, and orphaned references.
- Execute a complete repository-scale change workflow against a real open-source project, integrating the Claude Code SDK, GitHub API, pytest, and tree-sitter.
Sections
16.1 Multi-File Code Generation
Task decomposition into file-level edits. Dependency-ordered generation. Maintaining type consistency and import coherence across files. The edit graph abstraction. Failure modes: hallucinated imports, signature drift, circular dependencies. Claude Code SDK for orchestrated generation.
16.2 Impact Analysis and Patch Review
Change propagation through dependency graphs. Computing the blast radius of an edit. Static analysis with tree-sitter for reference tracking. Automated patch review: structural checks, test execution, LLM-based semantic review. Scoring patch quality and flagging regressions.
16.3 Building a Repository-Scale Change
Recipe: end-to-end multi-file change in a real open-source repository. Task specification, context gathering, edit plan generation, coordinated code generation, impact analysis, test validation, and pull request assembly. Integrating the Discovery Workbench change orchestration module.
Bibliography
Foundational Papers
The benchmark that established repository-scale code generation as a measurable problem, showing that resolving real GitHub issues requires multi-file reasoning and edit coordination.
Introduces the agent-computer interface design that enables LLM agents to navigate repositories, edit files, and run tests, achieving state-of-the-art SWE-bench performance.
Practical guidance on orchestrating multi-step coding workflows with the Claude Code SDK, including sub-agent patterns and tool integration for repository-scale changes.
Tools & Libraries
Incremental parsing library that builds concrete syntax trees for dozens of languages, used here for dependency extraction, reference tracking, and impact analysis.
The API for programmatic repository access, pull request creation, and CI status checking, used in Section 16.3 for end-to-end change automation.
Python's dominant testing framework, used here for automated test execution and selective test running as part of the patch validation pipeline.
The programmatic interface for invoking Claude Code as a subprocess, enabling orchestrated multi-file code generation within automated pipelines.
Tutorials & Surveys
Demonstrates iterative retrieval-and-generation for repository-level completion, a key pattern for multi-file consistency.
Shows that localization-then-repair pipelines without persistent agent state can match agent-based approaches, informing the decomposition strategies in Section 16.1.
A multi-agent framework for resolving GitHub issues that decomposes the problem into planning, coding, and reviewing stages.
Combines code search with spectrum-based fault localization and multi-file patching, achieving strong SWE-bench results through structured program analysis.
Datasets & Benchmarks
Extends the SWE-bench methodology to Java repositories, demonstrating that multi-file change challenges are language-agnostic.