What is the actual number?

Time, not lines — ten minutes of genuine reading. For most repositories that lands somewhere near 400 changed lines, which is also where the published review research stops finding defects.

What about a mechanical rename across 200 files?

That is one reviewable decision plus a script. Keep it in its own commit and say so; the rule is about decisions per diff, not lines per diff.

Cap what one agent run may change

Bound each agent run to a diff you could review by hand in ten minutes.

EngineersVibe codersgithubgitlab

The cost of producing code has collapsed. The cost of reading it has not moved at all — a human still reviews at roughly the same rate they did in 2005. That asymmetry is the defining hazard of this era, and the only lever you control is the size of the unit you accept. A bounded run also gives you a bisectable history instead of one commit called 'implement feature'.

What goes wrong: A 900-line commit that passes review because reviewing it properly would have taken longer than writing it did.

What agents change: Generation got a hundred times cheaper and review got no cheaper at all; a cap on diff size is how you keep the two in the same economy.

You are violating it when

A single commit changes more files than you can name from memory.
You approve agent output without opening every file it touched.
Your history has commits nobody could bisect.

The usual objection: That a large diff is fine if the tests pass. Tests encode the failures you already thought of; the reason to read a diff is the failures you did not.

A useful agent run ends as a change a person can actually understand, not merely as code that compiles. The unit of work is the reviewable slice: one intent, a contained surface area, and enough context that the reviewer can keep the whole change in mind while checking it.

This works because review is still a human bottleneck. Smaller changes reduce queue time, reduce context switching, and make defects easier to spot. They also leave a history that can be searched, reverted, or bisected when something later fails. Once a change becomes too broad, reviewers stop reasoning about it line by line and start sampling, trusting tests, or trusting the author.

The misconception is that passing tests make a large diff acceptable. Tests are valuable, but they mostly cover expected behavior and previously imagined risks. Review exists for the unknowns: surprising coupling, missing migration steps, unclear ownership, accidental API changes, security edge cases, and maintainability problems that no test asserted.

Agents make this discipline more important, not less. They can produce a day’s worth of edits in minutes, including edits spread across files the human did not intend to touch. A run that grows too large needs to be split or restarted around a narrower task, so the cheap generation step does not create an expensive, low-quality review step.

Install it

npx klay practices add agent-diffs-stay-small

AGENTS.mdappend-block

## Keep changes reviewable

- One concern per change. If you find a second thing worth fixing, list it; do not fix it here.
- Prefer several small commits over one large one, and make each message say why.
- Keep mechanical changes (renames, formatting, generated files) in their own commit.
- If a change is about to exceed roughly 400 lines, stop and propose how to split it.

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:

small-diffs
agent-commits-reviewed

Where this comes from

Best practices for using GitHub Copilot to work on tasks - GitHub DocsGitHub Docs · Official docsAdds first-party agent guidance that narrow task scope improves both output quality and reviewability.
Small CLsGoogle Engineering Practices · Official docsDefines the review-economics argument for keeping each change within a reviewer’s attention budget.
Turn one giant AI-generated pull request to a reviewable stackGitHub Engineering · Engineering blogShows the practical remedy for oversized AI output: split it into reviewable, focused units.
Agent pull requests are everywhere. Here's how to review them.GitHub Engineering · Engineering blogTreats an oversized agent PR as a process failure to reject, not heroically review.
Humans and Agents in Software Engineering LoopsMartin Fowler · Named authorityFrames the new asymmetry: agents can generate faster than humans can understand and validate.

Questions

What is the actual number?: Time, not lines — ten minutes of genuine reading. For most repositories that lands somewhere near 400 changed lines, which is also where the published review research stops finding defects.
What about a mechanical rename across 200 files?: That is one reviewable decision plus a script. Keep it in its own commit and say so; the rule is about decisions per diff, not lines per diff.