Reviewing cross-file changes made by AI agents

Reviewing cross-file changes made by AI agents works best in a fixed order: compare the changed paths with the scope the task declared, read the shared modules first, check every interface and behavior change against its callers, and handle generated files separately from hand-written ones. Reading from the top of the diff, the default in most review tools, puts the riskiest change wherever the alphabet happens to put it. A single changed line in a shared helper can matter more than two hundred lines in the feature the task was about. This workflow is about the shape of a multi-file change, not the general habits of reviewing agent output, which human review of agent output already covers. It needs nothing beyond git, your editor and the task description, and it works the same whether the change came from Claude Code, Codex CLI or a person.

Step 1: Compare changed paths with the declared scope

Before reading any code, list the files. git diff --stat against the base commit gives paths and sizes; git diff --name-status adds whether each file was added, modified, renamed or deleted.

Put that list next to the task's declared scope: the files or directories the task said it would touch. Sort every path into one of three groups. In scope and expected. Outside scope but explained, such as a test file next to the code or an import in a module the task obviously needed. Outside scope and unexplained.

The third group is where review starts. Each unexplained path needs a reason before anything else, and "the agent needed it" is not a reason until you know what for. If the agent touched a shared module the task never mentioned, that is probably the most important file in the change. When an agent changes files you did not ask for covers the case where the answer is that it should not have.

Also note deletions and renames. Both can break consumers silently, and both are easy to miss in a diff view that shows them as a single line.

Step 2: Read shared modules first

Order the files by how many other parts of the system depend on them, not by name. Helpers, utility modules, base classes, schemas, configuration defaults and anything under a shared or common directory go first. Feature files go last.

For each shared file, answer two questions before reading the rest. What did this file do before, and what does it do now? Who else uses it? The second question needs a search: find references to every changed function, constant or class, and write down the callers outside this task.

The reason for this order is that the cost of a mistake grows with fan-out. A wrong line in a feature file breaks that feature, which the task's own checks are likely to notice. A wrong line in a shared helper breaks features the task never tested. The blast radius probe is a one-line example: changing round(value * 100) to int(value * 100) satisfied checkout and broke an export nobody had linked to the helper.

If the shared change was not needed for the task, ask for it to be split out or reverted before reviewing further.

Step 3: Check interface and behavior changes against callers

With the callers listed, look for four kinds of change.

Signature changes: added, removed or reordered parameters, changed defaults, new required arguments. These usually break loudly, but changed defaults break quietly.

Return and error changes: a function that used to return None and now raises, returned a list and now returns a generator, or changed its units. Check how each caller handles the new result.

Behavior changes with the same signature: rounding, sorting, time zones, encoding, trimming, case sensitivity. Nothing in the toolchain flags these, so each needs a sentence in the review describing old and new behavior, and a check for every caller that depends on the old one.

Contract changes outside code: output formats, file names, environment variables, database columns, API fields. Consumers of these may live in other repositories or teams and will not show up in a reference search.

For every caller that depends on changed behavior, confirm a check covers it or run one. If none exists, the review result is not approved but needs a test. This is the split described in declared vs inferred dependencies: the code shows some consumers, records show others.

Step 4: Handle generated files and lockfiles separately

Agents often regenerate files as a side effect: lockfiles, compiled assets, API clients, migration files, test snapshots, reformatted code. These inflate the diff and hide real changes in noise.

Separate them first. For each generated file, find its source and its generator. Regenerate it yourself from the reviewed source and compare. If your output matches the agent's, you can skip reading it. If it differs, the agent either edited a generated file by hand or used a different generator version, and both need fixing.

Lockfiles deserve their own look. A lockfile change can mean a dependency upgrade the task never asked for. Check which packages changed versions and why.

Snapshots and golden files are the subtle case. An agent that updates a snapshot to match new output has changed what the test expects, which can turn a real regression into a passing test. Treat snapshot updates as behavior changes and confirm each one was intended; test tampering by agents covers the wider pattern.

End the review with a short written summary: scope deviations, shared changes, callers checked and anything left unverified.

QUESTIONS

In what order should I review a multi-file pull request?

Start with the list of changed paths and compare it with the intended scope. Then read shared modules, such as helpers, schemas and configuration, before feature code, because their changes reach the most callers. Check interface and behavior changes against each caller, and handle generated files and lockfiles separately by regenerating them yourself.

How do I spot a behavior change that keeps the same function signature?

Read every changed line in shared functions and write one sentence describing old and new behavior. Watch for rounding, sorting, time zones, encoding, trimming and default values. Then search for callers and ask which ones depended on the old behavior. Type checkers and compilers will not flag these changes, so the sentence and the search are the check.

Should I review generated files in an AI agent's diff?

Not line by line. Regenerate them yourself from the reviewed source with the project's own generator and compare. If they match, skip them. If they differ, find out why before approving. Give lockfiles and test snapshots a closer look, since they can hide unrequested upgrades or changed test expectations.

RELATED GUIDES

• How to read BRAIN FLUID reports and provenance

RELATED HARNESS PAGES

• human review of agent output Human review of agent output: what to inspect before accepting AI changes, and how recorded outcomes make the review honest.
• Why does my AI coding agent change files I didn't ask about? Unrequested edits come from missing scope, vague tasks, formatters and refactor drift. How to tell them apart, revert them and catch them next time.
• The blast radius of AI code changes The blast radius of AI code changes: what one agent edit can break elsewhere, a worked rounding example, and how a reviewer finds affected features.
• When an AI agent edits the tests to make them pass When an AI agent edits the tests to make them pass: the signs, why it happens, and how to keep test files out of an implementation task's scope.
• Keeping AI coding agents within scope Keeping AI coding agents within scope: declare paths, approve them separately with an expiry, check writes during the run and compare the diff after.
• Breaking a large refactor into agent-sized tasks Breaking a large refactor into agent-sized tasks: expand, migrate and contract in ordered steps that each keep the build green and have a check.