Keep the Diff Small
Bounds a change to what you can actually read before approving it.
When to reach for it
Before asking for a change in a codebase you care about — particularly when the agent has a history of returning forty files for a two-file job.
What changes
- The change opens with a stated budget — files touched, lines added, new files allowed or not — that the final diff is checked against.
- Every touched file gets a one-line reason; files without one are reverted rather than explained.
- Refactors arrive as a separate no-behavior-change step, so review can read the move and the meaning one at a time.
- Reformatting, import reordering, and drive-by fixes stay out of the diff entirely.
Pairs with
- Copy the NeighboursMakes new code look like the code already around it, instead of like whatever the agent prefers.
- One File FirstGets the thing running in a single file before anyone decides where its pieces should live.
- Borrow the ShapeStarts new code from the closest existing file in your repo instead of from a blank page.
Keep the Diff Small
A diff nobody reads is a diff nobody reviewed. Bound it before writing it, then check it before reporting it.
1. State the budget first
Before editing: how many files, roughly how many added lines, and whether new files are allowed. Say it out loud. A budget set after the fact is a description, not a limit.
2. Sort the work into four piles
- The change — the behavior actually being asked for
- Enabling moves — renames, extractions, and file moves needed first
- Formatting — whitespace, import order, lint fixes
- Unrelated — everything noticed along the way
Only the first pile belongs in this diff.
3. Sequence a required refactor separately
When the change genuinely needs restructuring, do the restructuring on its own, with no behavior change, and say which step is which. Two diffs that each do one thing are faster to review than one that does both, even though the total is identical.
4. Check the diff before reporting
Read the whole diff. For each file, write the one-line reason it was touched. A file with no reason gets reverted — not annotated.
5. Report the shape
Give the file count, added and removed lines, and the per-file reasons. If the budget was exceeded, say by how much and propose the split rather than defending the size.
Rules
- No reformatting, import reordering, or lint-fixing in files that were not otherwise being edited. A formatter run that touches the whole repository hides the real change inside it.
- Do not rename in the same diff as a behavior change. The rename makes every line look modified and buries the four that matter.
- Do not delete code that merely looks unused. Unless removal is the task, note it and move on.
- Do not upgrade a dependency, adjust config, or fix an unrelated type error while in the area.
- Do not add tests for pre-existing untested code in this diff. Worth doing, separately.
- If the change genuinely cannot be small, say so before starting and propose the sequence of steps instead of returning a large diff and an apology.