Skip to content
Klay

Keep pull requests small enough to review

Keep a pull request to one decision and roughly 400 changed lines.

EngineersVibe codersgithubgitlabci-generic

Review effectiveness falls off a cliff as diffs grow — past a few hundred lines reviewers stop finding defects and start acknowledging receipt. A small pull request also gets reviewed sooner, because a reviewer will pick up a ten-minute read and postpone an hour-long one until a tomorrow that keeps moving.

What goes wrong: A rubber-stamped approval on a diff nobody read, and a bug everybody technically signed off on.

What agents change: The constraint that used to keep PRs small was how long they took to write. That constraint is gone, so the limit has to be stated explicitly now.

You are violating it when

  • An approval arrives within a minute of a large diff being opened.
  • Pull requests sit for days before anyone opens them.
  • Review comments are all about formatting.

The usual objection: That splitting work into several pull requests is more total work. It is the same work, reviewed properly, merged sooner.

A pull request is easiest to review when it asks for one decision: accept this focused behavior change, refactor, test addition, or interface adjustment. The line count is not a moral score, but it is a useful guardrail. Once a diff reaches several hundred changed lines, the reviewer is no longer checking a coherent argument; they are trying to hold a large working set in memory while guessing what matters.

Small reviews work because they preserve attention and scheduling. A reviewer can inspect a narrow change between meetings, understand the intent, run or reason about the relevant tests, and leave specific comments. A large diff creates delay first, then fatigue, then performative approval. The failure mode is not that nobody cared; it is that the review was shaped into a task that ordinary humans cannot do well.

The misconception is “splitting work into several pull requests is more total work.” It usually is the same design and implementation work, divided into reviewable decisions. Smaller pieces can be reviewed sooner, corrected earlier, and merged with less conflict. The alternative is batching decisions until the only practical reviewer response is trust, skim, and approve.

AI coding agents make this limit more important, not less. The old friction of typing and editing naturally slowed patch size; an agent can produce a thousand-line change before the reviewer has context. Review policy has to constrain the submitted unit of work, because generation speed is no longer evidence that the change is understandable, safe, or ready to merge.

Install it

npx klay practices add small-pull-requests
  • .github/workflows/klay-pr-size.ymlcreate
    # Klay practice: small-pull-requests
# https://klaylearn.com/practices/small-pull-requests
#
# Warns when a pull request grows past the size at which review stops finding
# defects. It does NOT fail the build: a hard block on diff size is trivially
# gamed by splitting one change across two PRs that must land together, and it
# punishes the legitimate mechanical rename. A visible warning on the PR is the
# behaviour you want.
name: PR size

on:
  pull_request:
    types: [opened, synchronize, reopened]

The previews are the first lines of each file; the command writes them in full. Existing files are never overwritten.

How you know it stuck

npx klay practices audit reports these checks for this practice:

  • pr-sized-merges
  • ci-on-pull-request

Where this comes from

  1. Small CLsGoogle Engineering Practices · Official docsGives first-party numeric guidance for reviewable change size and says oversized changes should be split.
  2. Helping others review your changes - GitHub DocsGitHub Docs · Official docsAdds platform guidance that each pull request should have one purpose and be split when large.
  3. Speed of Code ReviewsGoogle Engineering Practices · Official docsExplains why small reviews move through schedules faster than large ones.
  4. Your job is to deliver code you have proven to workSimon Willison · Named authorityCovers the AI-agent shift: large generated patches are easy and no longer signal value.
  5. Pull RequestMartin Fowler · Named authorityConnects pull request size to daily integration and delivery flow, not just reviewer comfort.

Questions

My change genuinely touches 30 files.
Then it is probably several changes. Land the mechanical part first, on its own, and the decision second — the second one is the only one needing careful eyes.