Skip to content
Guided Review
Guides / Guided ReviewUpdated

How to review a large AI-generated PR

A large set of changed files organized into contract, callers, and tests review units.

A 40-file PR changes a request schema, updates its callers, and replaces several tests. You start at the top of the file list. By the time you reach the implementation, you're holding half the patch in your head.

I'd start with one behavior instead. Write down what's supposed to change, then follow a value through the contract, callers, and tests. File order can wait.

Before you read every hunk:

  • Establish the intended behavior.
  • Trace it through the contract, callers, and tests.
  • Record unresolved questions with a path and a consequence.
  • Verify failure cases before choosing an outcome.
On this page

Decide what belongs in the PR

Read the description for the intended outcome, compatibility constraints, and evidence. Separate generated files, dependency updates, and mechanical moves from behavior changes. They still need checking, but they answer different questions.

If the author can't explain which behavior belongs in this PR, ask for a smaller change. Ordering 40 files won't produce a missing requirement.

Trace a contract across the diff

Suppose the request field timeout becomes timeoutMs. Find the definition, default, caller that sends it, and code that uses it.

Is this a rename or a conversion? Does an old client still work? A test that copies the new field name doesn't answer either question. The AI-generated PR guide walks through this example in detail.

Guided Review groups related hunks into review units with short commentary. I want that reading order to reduce the file-hopping. I still need to check the real diff.

If a caller seems absent, search the repository. Unchanged code can depend on a contract you've just changed.

Know what the model saw

Large diffs are chunked by file for AI structuring. A file is never split, so one large file can exceed the usual chunk target. A provider can still reject the request for exceeding its limits.

Separate requests also mean separate context. Don't assume the model connected a caller in one chunk with a schema in another.

The chunking documentation covers the details. If structuring fails, use the file-by-file walkthrough or reduce the scope. Requesting another plan adds provider usage. It doesn't make the PR smaller.

Make a behavior map before reading every hunk

Take the timeout migration as a concrete example. Suppose the current API accepts seconds and defaults to five seconds. The proposed API accepts milliseconds and should default to 5,000. That is a hypothetical contract for this review, not a Guided Review setting.

Write a short map: request parser, defaulting logic, internal representation, outbound call, and observable failure. Put the relevant paths beside those steps. The map gives you somewhere to return when a helper or generated file interrupts the reading. It also exposes missing evidence: if nobody can identify where the conversion occurs, a renamed field is insufficient.

Keep unrelated behaviors on separate lines. A PR that also changes retry policy needs another map because timeout and retries can fail independently. You can review the two paths in sequence without assuming a single summary explains both. If they cannot ship independently, ask the author to explain the dependency in the description.

Trace timeoutMs through the contract, old and new callers, and tests that distinguish five seconds from five milliseconds.

Review compatibility in deployment order

An internally consistent patch can still break a mixed deployment. Imagine the server ships before every client. Does it continue accepting the old field? If a client sends both names during the transition, does the parser reject the request, prefer one value, or silently choose whichever assignment runs last?

Read the code that makes those choices and compare it with the intended rollout. Check whether responses, stored configuration, queued jobs, or cached values also contain the old representation. A repository search for the old name helps, but serialized values may cross a boundary that a type rename cannot update.

Ask for compatibility evidence at that boundary. An old-format request reaching the new parser is more informative than another test of a newly constructed internal object. For a deliberate breaking change, verify that the migration instructions identify who must act and when. The author should be able to explain how the system behaves while versions overlap.

Give generated and mechanical changes a separate pass

Group lockfile updates, generated clients, snapshots, and formatting changes so they do not hide behavioral edits. For generated output, identify the source and the generation command. Read the source change first, then check that the output corresponds to it. A generated label does not establish that a file is reproducible or safe to ignore.

For a mechanical move, compare the old and new location closely enough to establish that behavior stayed the same. Check imports and exports around the move; a moved function can gain a different caller even if its body is unchanged. Watch for changed defaults tucked inside broad formatting edits.

If generated output dominates the patch, ask the author to explain how they verified it. A reproducible generation step and a focused contract test can give stronger evidence than reading thousands of repetitive lines with equal attention. Record any part you could not verify instead of letting the file count imply completeness.

Keep an uncertainty list as you read

Maintain a small list of unresolved questions with a path and a consequence. For example: “The legacy caller still sends seconds; new parser may interpret the value as milliseconds.” That note tells you where to return and why it matters. “Check compatibility” is too broad to preserve the investigation.

Resolve each question with code, an explicit requirement, or a result you can reproduce. A model explanation can suggest where to look, but does not close the question. If you pause the review, leave the list in a place you can recover, rather than relying on memory of which units you visited.

After an author update, revisit the changed path and the assumptions that depended on it. A fix to the parser may change what the caller test should expect. Recheck the relevant evidence against the latest diff; progress through an earlier plan describes earlier reading, not the new patch.

Test a failure you can name

For each behavior change, pick an input that should now behave differently. Read the assertion beside the production condition. Run the focused tests using the repository's commands; the walkthrough doesn't execute them.

For timeoutMs, I'd want a value that exposes a unit error. Five seconds and five milliseconds are different enough to be useful.

Leave the question beside the relevant lines. Make it clear whether you're asking about intent or blocking on compatibility. On GitHub, drafts stay local until you choose to submit them through the extension. The CLI workflow covers work that hasn't become a PR.

Ask for a split when you can't review the change

A PR can be coherent and still take more time than you have to understand it. Ask for a split along behavior boundaries.

Make the request concrete. “Land the compatible parser first, migrate callers next, then remove the old field after the supported transition” gives the author a reviewable sequence. Verify that each intermediate state can run and that the tests describe that state. Splitting only by directory can leave every PR depending on code that has not landed.

At the end of the review, state which behavior you traced, which checks you ran, and what remains unresolved. A useful review record might say that the default and new client are verified, but the legacy request path still needs an answer. The author can act on that without reconstructing your reading session.

Marking every review unit read means you've visited every unit.

It doesn't mean the timeout is correct.