When a model proposes a change to a file, the hard part is not generating the change. It is applying it. Teams that build coding assistants, migration tools, or config editors quickly discover that "the model returned a diff" and "the diff did the right thing" are separated by a lot of failure modes. This article lays out a small set of patterns that make applying model-proposed edits boring and safe.

Pick an edit format that fails loudly

There are three common formats, and they fail differently:

  • Whole-file rewrite. Simple to apply, but the model must reproduce every unchanged line. On large files it silently drops, reorders, or "improves" code you never asked about. The diff you see afterward is the only evidence, and it is noisy.
  • Unified diff. Compact, but models are unreliable at line numbers and hunk headers. A patch that is off by three lines either fails to apply or, worse, applies in the wrong place with fuzz.
  • Anchored search-and-replace. The model returns an exact snippet to find and its replacement. There are no line numbers to get wrong, and the failure is easy to detect: the snippet either matches or it does not.

For most tools, anchored replacement is the best default. Add one rule: the anchor must match exactly once. Zero matches means the model hallucinated or the file changed; multiple matches means the edit is ambiguous. Both should be rejected, not resolved by picking the first hit.

Apply atomically, then verify

Treat a set of edits as one transaction. Validate every anchor against the current file contents before writing anything, apply all edits in memory, and only then write. If edit three of five fails, you want the file untouched, not half-modified.

After applying, run the cheapest checks that can catch a broken result, in order of cost:

  1. Does the file still parse (syntax check, JSON or YAML load)?
  2. Does the formatter or linter produce a clean result, ideally with no changes beyond the edited region?
  3. Do the relevant fast tests pass?

A formatter pass is underrated here. If running it changes lines far from the edit, that is a strong sign the model rewrote more than it claimed.

Feed failures back precisely

When an anchor fails to match, do not just report "edit failed." Return the specific problem: which edit, whether it matched zero or multiple times, and a few lines of the file near the closest match. The model can usually fix a precise error in one retry; a vague one produces a second wrong guess. Cap retries at two or three, then hand the change to a human along with the proposed edit, rather than looping.

Keep a record

Store the original file hash, the proposed edits, and the applied result together. When someone asks why a file changed, you can answer from the record instead of guessing, and you can replay the edit against a newer version of the file to see whether it still applies.

The core idea: never let "the model said so" be the thing that decides where a change lands. Make the location verifiable, make the application all-or-nothing, and make every rejection specific enough to act on.

Agentic AIDeveloper Tools