As AI coding agents begin generating multiple files at once, reviewers must change how they work. If you start reading a large PR review containing dozens of files from the top, you may see the implementation before encountering the contracts and schemas that support it. After spending considerable time, you finally understand what the change is really centered on.
This is especially true when Git presents files by path and name order, because that order does not explain the system’s division of responsibility or execution flow. In a 20-file change produced by an agent, you may encounter utility helpers or UI components before reaching the database schema or core interface that determines actual behavior. Instead of reading more lines, reviewers should first understand which contracts and call paths those lines connect to.
Why Alphabetical Diffs Do Not Show Structure
A file list reflects the result of the repository directory, not the architecture. If the UI calls a service function, the service depends on an interface, and the interface requires a data model, sorting file names alone cannot reveal that direction. The moment you begin reconstructing the call graph in your head, restoring the structure takes on greater importance than the code review itself.
This problem cannot be solved by attaching one more automation tool. Treating an agent’s description of a change as the premise of the review, or approving the final diff solely because tests pass, can allow missing dependencies to slip through. The review of a large change should focus not on the amount of implementation, but on how contracts are changing and how far their consumers and callers are affected.
A discussion has begun on reviewing large changes produced by agents and how those changes should be reviewed. The central question is simple: In what order should a team read a 20-file diff?.
Rearrange the File List by Contract and Call Flow
The first step is to classify changed files by responsibility instead of arranging them in an arbitrary line-by-line sequence. Start with contracts, interfaces, and schemas, then review domain services and orchestration. Next, examine callers of changed interfaces, tests, and finally the presentation layer. This order lets you focus on high-risk dependency paths instead of reading every line at the same depth when many files are involved.
Git’s diff commands can be used in stages to gather this information. The key is to separate the size of the change from its file list.
git diff --stat
git diff --name-only
git diff --find-renames
git diff --word-diff
--stat shows the size of the change, --name-only lists the files under review, and --find-renames distinguishes file moves from file changes. For changes where a single line matters, such as contracts or configuration, --word-diff makes it easier to avoid missing implementation details. The results of these commands should then be rearranged into lists of contracts, schemas, callers, tests, and presentation-layer files.
Find the Impact Range of Schemas and Interfaces
When reading a core contract, do not judge only the implementation details. Also find the code that directly calls the interface, the code that produces messages or API responses, and the migration paths that read stored data. If an interface changes, verify whether backward compatibility could break. If the response structure changes, identify the affected consumers. If a schema changes, confirm that the migration and rollback sequence remains valid.
In the review document, first record the entry point of the change, the changed contract, unexpected call paths, and the state involved in rollback. Group callers, consumers, and schema changes as one logical unit, but, where possible, separate contract changes, caller updates, data migrations, and behavior changes into smaller units. If the environment supports a feature flag, limit the actual reach of the change and deploy it in stages so you can narrow the cause when a regression occurs.
Tests Are Verification Gates, Not Just a Pass/Fail Check
In a large PR review, tests are not a ritual to run once at the end. When the change reaches a contract, add contract tests. When multiple layers are connected, add integration tests. When a schema changes, include migration and rollback validation. Tests that do not cover failure paths only demonstrate the happy path and cannot validate the branches where the real risks lie.
Before requesting approval, record the change summary, impact range, validations performed, remaining risks, and rollback procedure. Even when tests pass, separately assess whether the contract’s intent is correct, whether all callers have been updated, and whether reverting the change leaves the data in a safe state. This allows you to treat AI-generated output as an independent target for verification rather than automatically trusting its design.
Common Limits and Pitfalls in Practice
Introducing dependency-focused reviews adds cost. It takes time to organize the call graph and explain relationships between files, and classification can be difficult in repositories where architectural boundaries are unclear. Automated classifications may differ from the actual call flow, so do not use a tool-generated list as the premise of the review; verify the relationships yourself.
The most common antipatterns are judging the implementation immediately after reading files in name order, accepting the agent’s stated purpose for the change without question, and merging the final diff simply because tests pass. Dividing a large change into smaller logical units reduces the scope that can be merged at once, but contracts and callers may still be scattered across different groups. The basis for separation should be compatibility responsibility and rollback feasibility, not the number of files.
Try This Now
- Run
git diff --statandgit diff --name-onlyon the current branch, recording the size of the change and the file list separately. - Classify the file list into contracts, schemas, services, callers, tests, and presentation-layer files.
- Search for changed interfaces and schemas, and mark their callers, consumers, and migration paths.
- Use
git diff --find-renamesto distinguish actual moves from changes, and reread contract changes withgit diff --word-diff. - Before merging, record contract, integration, schema, failure-path tests, and the rollback procedure in the review request.
Source
This article was prepared after reviewing the following source: r/devops — Why are we still reviewing massive PRs in alphabetical file order?

Leave a Reply