7.5 The "diff-only changes" pattern
Overview and links for this section of the guide.
On this page
The core idea
Diff-only changes means the model outputs only what changed, not entire rewritten files. This keeps changes reviewable and prevents accidental rewrites.
This is one of the highest-leverage habits in vibe coding because it aligns the model’s output with how engineers actually ship code: small diffs, reviewed, tested, merged.
The deeper rule is: “make the smallest change that satisfies the acceptance criteria.” Diff output is how you enforce that rule.
Why diff-only is the default for real codebases
Full-file rewrites are dangerous because they:
- hide unintended changes (hard to review),
- create merge conflicts,
- delete comments/formatting that mattered,
- accidentally change behavior in unrelated areas,
- break implicit contracts you didn’t paste into the prompt.
Diff-only changes make it hard for the model to “improve everything” and easy for you to keep control.
Vibe coding without reviewability becomes luck. Diff-only is how you keep speed without gambling.
Diff formats that work well
You can use any format that makes changes obvious. Two practical choices:
Option A: unified diff (git-style)
Works best when you are applying changes with tooling. Example prompt instruction:
Output a unified diff (git patch) only. No additional prose.Option B: “diff-only per file”
Works well in chat interfaces where unified diff formatting is unreliable. Example:
- list the file path,
- then show only changed lines with minimal context,
- clearly separate files.
Consistency makes your review loop faster. If your team uses git patches, prefer unified diff everywhere.
Hard rules that keep diffs safe
These rules prevent the most common “model went wild” failures:
- Plan first for non-trivial changes: you approve direction before code.
- File scope: “Only touch these files.”
- Line budget: “Keep diff under ~N lines unless necessary.”
- No dependency changes unless explicitly requested.
- Tests must pass (and add tests for new behavior).
- No behavior changes outside acceptance criteria.
When something breaks, small diffs make it obvious where the break came from. Large diffs create uncertainty.
Copy-paste diff-only prompt templates
Template A: plan first, then diff
We are using the “diff-only changes” pattern.
Task:
[Describe change.]
Constraints:
- Only touch these files: [...]
- No new dependencies
- Preserve behavior except as specified
Acceptance criteria:
- [...]
Process:
1) Propose a plan with 3–6 steps.
2) Stop and wait for confirmation.
3) Then implement step 1 only as a minimal unified diff.Template B: smallest possible fix
Fix the failing test below with the smallest change possible.
Constraints:
- Diff-only changes
- Do not refactor unrelated code
- Do not change tests unless the test is wrong (explain if so)
Failing output:
(paste)Template C: line cap + scope cap
Make this change, but keep the diff under ~80 lines total.
If you think it requires more, stop and explain why before writing a diff.
Only modify:
- src/foo.py
- tests/test_foo.pyHow to review diffs quickly
A fast review loop looks like:
- Scan file list: are the touched files expected?
- Scan dependencies: did it add new imports/packages?
- Scan behavior: did public outputs change unexpectedly?
- Run tests: do they pass?
- Run 1–3 manual checks: especially for CLI/HTTP behavior.
You can accept diffs quickly when they’re small and scoped. You should distrust diffs that are large, cross-cutting, or “too clever.”
When the model ignores diff-only (recovery)
This will happen. The recovery is procedural:
- Stop it: “Do not rewrite files. Output diff-only changes.”
- Shrink scope: “Only change this function in this file.”
- Add a line cap: “Under 50 lines.”
- Ask for step 1 only.
That debt compounds. Diff-only is how you keep the loop fast long-term.