Diffs vs Whole Files: What Code Editing Agents Should Rewrite

Andrej Andrejev posted a useful code-editing paper on September 5, 2026: Diffs vs. Whole Files. The setup is simple enough to matter outside the benchmark: should a code model edit by emitting a sequence of localized search/replace steps, or should it generate the entire modified file in one shot?

Last updated: September 10, 2026

The surprising result is that whole-file generation wins across the paper's measured tasks. The author trained both a 100M-parameter model from scratch and a fine-tuned Qwen2.5-Coder-0.5B variant on a shared Flutter/Dart dataset, then evaluated four resulting models on about 1,790 held-out tasks per model. Direct generation outperformed iterative diff-based generation on compilation/static-analysis pass rate, bits-per-byte, character-level similarity, and blinded LLM-judge ratings.

The practical takeaway is not "never use diffs." Developers still need diffs for review, trust, rollback, and collaboration. The useful takeaway is sharper: agent systems should route editing strategy by task locality. A tiny refactor wants surgical edits. A broad UI rewrite may be better treated as regeneration plus review.

That distinction connects directly to how we have been thinking about code cleanliness and AI coding agents, benchmark failure modes, and long-running agent harnesses. The output format is not just a model-training detail. It shapes whether the user can supervise the work.

What The Paper Tested#

The paper compares two output regimes:

• Direct generation: the model emits the entire modified file.
• Iterative diff-based generation: the model emits localized search/replace edits one step at a time until it stops or runs out of budget.

The diff-based regime is attractive for obvious product reasons. It mirrors how developers think about editing, can use fewer generated tokens, and produces a natural review artifact. If you have used a terminal coding agent or an IDE assistant, this probably feels like the responsible default.

But the paper's result cuts against that intuition. On the evaluated Flutter/Dart tasks, direct generation substantially outperformed diff-based generation on every metric the author measured. The gap also persisted after controlling for task difficulty through a matched-ID comparison and when restricting the comparison to code that compiled on both sides.

That matters because it makes the result harder to dismiss as "the diff model just got harder tasks" or "the file model only won by producing compilable but lower-quality code." The finding is narrower than a universal law, but it is not hand-wavy.

The Key Idea Is Task Locality#

The most useful phrase in the paper is "task locality."

Diff-based editing does better when the desired change is short and spatially localized. The paper says the category-level wins for diff-based generation concentrate in refactoring and error-handling/edge-case fixes, which had the lowest mean edit-step count in the dataset.

That matches how human review works. A small null-check change, a renamed parameter, or a focused error-boundary fix is easier to understand as a patch. The surrounding file provides context; the change itself is the object under review.

The moment the change spreads across the file, the patch stops being the right unit of thought. A set of search/replace edits can become a brittle script for reconstructing intent. If the model has to move imports, restructure state, change widget boundaries, and update multiple call sites, direct file generation can be a better interface for the model even if the final artifact still needs a diff for the human.

That gives agent builders a useful routing rule:

The model can prefer one representation while the product still shows the developer another. That separation is important.

Why Whole Files Can Beat Patch Steps#

The paper does not prove a single universal cause, but the result is easy to reason about.

Patch-style generation forces the model to solve an extra procedural problem: identify the exact old text, choose replacement text, apply it in the right order, and keep the intermediate file valid enough for the next edit. Every step is another chance to miss the search anchor, duplicate a block, or repair an earlier repair.

Whole-file generation removes that procedural layer. The model can produce the target state directly. That is especially helpful when the change requires rebalancing structure across the file.

The tradeoff is reviewability. A full-file rewrite can be semantically cleaner while producing a noisy diff. That is a real cost. Code review is not just a correctness check; it is how teams transfer context and enforce taste. This is why the answer cannot be "always regenerate the file."

The better design is a two-stage system:

1. Pick the generation format that best fits the task.
2. Convert the output into the review format that best fits the human.

For agents, those are different decisions.

What This Means For Coding Agents#

Most agent products already mix modes, even if they do not explain it. Autocomplete is direct token continuation. Apply-patch flows are diff-based. IDE refactors often use structured operations. Terminal agents may rewrite a file and then ask you to inspect the git diff.

The paper suggests that agent harnesses should make this choice explicit. Before editing, the agent can classify the task:

• How many regions of the file are likely to change?
• Is the change mostly local, or does it alter the file's structure?
• Will the model need to preserve exact surrounding text?
• Is there a deterministic formatter or compiler to normalize the output?
• What review artifact will the developer trust?

That is the same supervision pattern behind what an AI coding agent actually is: the agent is not just a model writing code. It is a loop of planning, editing, checking, and presenting evidence. The edit representation is part of that loop.

This also explains why Codex CLI worktrees matter. If a larger rewrite is better generated as a whole file, isolating the work in a separate checkout becomes more valuable. The developer can inspect the resulting state without polluting the main working tree.

The Benchmark Caveat#

This is a Flutter/Dart study with relatively small models. It is not proof that every frontier coding model should stop emitting diffs. It also does not settle multi-file changes, repository-level constraints, or product-specific UX questions like merge conflicts and review ergonomics.

That limitation is not a flaw. It is exactly what makes the paper useful. The result is concrete enough to sharpen product decisions without pretending to be a final answer for all code editing.

The demand signal is also not a launch spike. Google Trends was usable for this run, and the broader query cluster has more durable interest than the exact paper title: over the last few days in the US sample, "coding agents" sat around 10-13 relative interest, "code diff" around 5-9, and exact "AI code editing" was near zero. Hacker News had no exact-match story for the paper when checked on September 10. This is a search-intent and workflow-design topic, not a viral-news topic.

That is fine. The best agent-design posts often come from papers that name a problem developers have already felt.

A Practical Routing Heuristic#

If you are building or configuring a coding-agent workflow, use this rule:

Use diff-first editing when the change is local, review needs to be tiny, or the surrounding code must remain exactly stable.

Use whole-file generation when the change is structural, the file is small enough to review, a formatter can normalize output, and tests or screenshots can validate the result.

Use mixed mode for multi-file work: plan the change, regenerate the files that need structural reshaping, use surgical patches for glue code, and always show a final git diff.

The final diff remains non-negotiable. Developers do not need to see every intermediate token the model produced, but they do need a reviewable artifact that shows what changed, why it changed, and what checked it.

FAQ#

Are whole-file rewrites better than diffs for coding agents?#

Not always. The Diffs vs. Whole Files paper found direct whole-file generation outperforming iterative diff edits on its Flutter/Dart benchmark, but diff-based editing remained competitive on short, localized changes. Treat it as a routing signal, not a universal rule.

When should an AI coding agent use diff-based editing?#

Diff-based editing is strongest for small, spatially localized changes: bug fixes, small refactors, error-handling updates, and patches where preserving surrounding code exactly matters.

When should an AI coding agent regenerate a whole file?#

Whole-file generation is more attractive for structural edits: UI rewrites, file-level cleanup, state-management changes, and cases where a formatter, compiler, or test suite can quickly validate the full target state.

Does this mean developers should stop reviewing diffs?#

No. The model's generation format and the human's review format are separate. An agent can generate a whole file and still present a clean git diff, screenshots, tests, and a concise change summary for review.

Continue Reading#

• Does Code Cleanliness Affect AI Coding Agents? - why structure and locality matter before the model ever starts editing.
• Your Benchmark Is Lying To You - how to read benchmark claims without turning them into product myths.
• Long-Running Agents Need Harnesses, Not Hope - why edit strategy needs checks, isolation, and resumability.
• What Is an AI Coding Agent? - the practical loop behind modern coding agents.
• Codex CLI Worktrees Turn Agent Runs Into Durable Sessions - why isolated workspaces make larger rewrites easier to trust.

Sources#

• arXiv paper page for Andrej Andrejev, "Diffs vs. Whole Files: An Empirical Comparison of Iterative Edit-Based and Direct Generation for Flutter/Dart Code Models," fetched September 10, 2026: https://arxiv.org/abs/2609.05779
• Hugging Face paper page for arXiv 2609.05779 and linked demo space, fetched September 10, 2026: https://huggingface.co/papers/2609.05779
• Hacker News Algolia exact-title search, fetched September 10, 2026: https://hn.algolia.com/api/v1/search?query=%22Diffs%20vs.%20Whole%20Files%22&tags=story
• Google Trends query cluster check for "AI code editing," "code diff," "coding agents," and "Flutter AI," fetched September 10, 2026.