PR Review Workflow

What this lesson covers

The Git Operations lesson noted what Claude can't see on its own: PR comments, CI results, and review status. This lesson closes that gap. You'll learn to feed a pull request's real context into Claude Code, run a disciplined review that finds regressions instead of nitpicks, and handle review feedback on your own PRs without blindly "fixing everything."

What Claude can't see about a PR — and how to feed it

Claude reads your working tree with git. It does not automatically know a PR exists, what reviewers said, or whether CI passed. You bring that context in. The standard tool is the GitHub CLI (gh), which turns PR state into text Claude can read.

Reviewing a PR inside Claude Code

The single biggest mistake is asking Claude to "review the PR" while it has the whole repo in context. It drifts into unrelated files and general refactoring. Scope the review to the diff.

Here is the diff for PR #128 (output of 'gh pr diff 128'):
[paste diff, or: "read it from the checked-out branch vs origin/master"]

Review ONLY these changes. For each issue, give me:
- file:line
- severity: bug | regression-risk | security | style
- what's wrong and the specific fix

Do not review files outside this diff. Do not suggest unrelated refactors.
Prioritize correctness and anything that could break existing behavior.

If the change is subtle, have Claude check it out and compare against the base branch so it reads the real surrounding code, not just diff hunks:

Now Claude can read lib/rate-limit.ts in full and reason about how the 48 new lines interact with what was already there — the thing a raw diff hides.

Separating signal from noise

Claude will surface everything it notices. Your job is triage. Not every comment deserves a change, and acting on all of them is how a two-file PR turns into a twelve-file mess.

# Claude's review returns 11 items on a 2-file PR:
#   3 real (a regression + 2 missing error paths)
#   8 style/preference nits

# Operator tells Claude: "apply all of these"
# Result:
#   - The PR grows to 6 files
#   - 2 "fixes" introduce new behavior nobody reviewed
#   - The original regression is now buried in noise
#   - The reviewer has to re-review everything from scratch

# Operator triages first:
#   "Apply items 2, 5, 7 (the regression + two error paths).
#    Ignore the style items — the linter owns those.
#    For item 9, explain the tradeoff but don't change it."

# Result:
#   - 3 scoped commits, same 2 files
#   - The regression is fixed and visible in isolation
#   - Reviewer re-reviews 3 small diffs, approves

Responding to feedback on your own PR

When you're the author, each reviewer comment maps to exactly one of three decisions. Make the decision first, then let Claude execute only the "agree" ones.

Give Claude the comments and your decisions together, so it never silently "fixes" something you meant to push back on:

Reviewer comments on PR #128 (from 'gh pr view 128 --comments'):
1. "This will throw if items is empty." → AGREE, fix it
2. "Use a Set here instead of includes()." → PARTIAL: the array is
 length ~3, a Set is premature; keep the array but add a comment
3. "Move this to a shared util." → PUSHBACK: it's used once; don't move it

Apply only #1 and #2 as separate commits. For #3, draft a short reply
explaining the single-use reasoning. Do not change code for #3.

The safe-change loop for review fixes

Every round of review fixes runs the same loop. It keeps each reviewer concern isolated and re-reviewable.

# 1. Make ONE reviewer concern's change (scoped, not "everything")
# 2. Verify it in isolation
node node_modules/typescript/bin/tsc --noEmit
git diff --staged

# 3. Commit with a message that references the concern
git commit -m "fix(rate-limit): guard empty items array (review #1)"

# 4. Push to the SAME branch — never force-push a PR under review
git push

# 5. Reply to that comment thread pointing at the commit

Two rules keep follow-up review cheap:

• One concern per commit. A reviewer can look at "guard empty array" in isolation instead of re-reading a squashed pile of unrelated edits. Squash at merge if you want a clean history — not before the re-review.
• Never force-push a branch under active review. It rewrites the history the reviewer already read and destroys their in-progress comment anchors. Add commits; don't rewrite.

Writing the PR description Claude actually helps with

A PR with a good description gets reviewed faster because the reviewer knows what to look for. Claude can draft it from the diff — the one time "read the whole diff" is exactly what you want.

Read the diff for this branch (git diff origin/master...HEAD) and draft a
PR description with these sections:
- What changed (2-3 bullets, plain language)
- Why (the problem this solves)
- Risk / blast radius (what could this break? what did NOT change?)
- How I verified it (tsc, build, the exact flow I exercised)

Keep it tight. A reviewer should know where to focus in 20 seconds.

The Risk section is the one most authors skip and the one reviewers value most. Naming the blast radius — "touches the scan rate-limiter only; no change to auth or billing paths" — tells the reviewer exactly where to concentrate and where they can trust the change.