Skip to content
AI Engineer Guide.

concept · coding · intermediate · concept 11 of 30

Patch editing

0 of 30 complete

Why it matters

Asking a model to return a full file is the simplest edit protocol and the worst one at scale. The model re-emits every line, including the ones it did not intend to touch, so comments vanish, formatting drifts, and the diff becomes unreviewable. It also costs output tokens proportional to file size, which is the expensive direction.

A patch inverts that: the output is proportional to the change. Reviewers see exactly what moved. Unrelated code is structurally protected, because it never appears in the model's output at all. The cost is that the patch must be located precisely in a file the model only partly knows, which is why patch protocols are mostly about anchoring and conflict handling.

Mental model

A stonemason replacing one brick in a wall. They mark the brick, cut it out, and set the new one. They do not rebuild the wall, and if the wall has shifted since they measured, the marked position is wrong.

The analogy breaks on tolerance. A mason can see the wall and adjust. A patch applies to text by exact match of context lines (with limited whitespace tolerance), so "close enough" is a rejected patch, not a slightly off repair. The harness must turn that rejection into a useful instruction rather than a generic failure.

How it works

Three lines inside twenty-fourInteractive

The interactive figure loads with JavaScript. The text version below describes the same frame.

Figure. A synthetic 24-line file as a class map, with two hunks drawn as rectangles over the lines they anchor on. The patched file writes 3 of 24 lines; a second version has five lines inserted above the first hunk, so the same rectangle covers different text. Rows stand for lines and no repository was read.

What to notice. A hunk is a rectangle over lines, and everything outside it is never re-emitted. The change is proportional to the diff, which is why a patch protects formatting it never saw. The anchor is the rectangle's content: insert five lines above it and the rectangle no longer lands on the code the model meant, which is a rejection or a silent offset.

Text version

A schematic file with a gutter and 24 lines of code and comments. Steps show the file, two hunk rectangles over lines 4 to 9 and 12 to 16, the patched file with three written lines, the file after five lines were inserted above the hunk, the inserted rows marked in blue, with the rectangles unchanged, and a whole-file rewrite where all 24 lines are written. Legend distinguishes unchanged, inserted, written, removed and comment lines.

  1. Read the target region. The model needs the exact text it will anchor on, including indentation, or it is inventing context.
  2. Emit a patch in a constrained format. Unified diff with three lines of context is the interoperable choice; a search/replace block with a unique old string is easier for models to produce correctly.
  3. Check the anchor. The old text must match exactly once. Zero matches means stale or wrong context; more than one means the anchor is ambiguous and must be extended.
  4. Validate the whole patch. A dry run (git apply --check) catches malformed hunks, wrong paths and missing context before anything is written.
  5. Apply atomically. All hunks or none. A half-applied patch leaves the working tree in a state neither the model nor the reviewer expects.
  6. Verify the result. Compile, type check or run the targeted test. Application success and semantic correctness are different properties.
  7. Report precisely on failure. Which hunk, which line, what the file actually contains there. The model can usually repair in one turn given that.
import subprocess
 
def apply_patch(root: str, diff: str) -> dict:
    check = subprocess.run(
        ["git", "apply", "--check", "--whitespace=nowarn", "-"],
        input=diff, cwd=root, text=True, capture_output=True, timeout=30,
    )
    if check.returncode != 0:
        return {
            "ok": False,
            "code": "does_not_apply",
            "stderr": check.stderr[-2000:],
            "remedy": "re-read the file and re-anchor the hunk",
        }
 
    applied = subprocess.run(
        ["git", "apply", "--whitespace=nowarn", "-"],
        input=diff, cwd=root, text=True, capture_output=True, timeout=30,
    )
    return {
        "ok": applied.returncode == 0,
        "code": "applied" if applied.returncode == 0 else "apply_failed",
        "stderr": applied.stderr[-2000:],
    }

git apply is atomic by default: it writes all hunks or none, and --reject is the opt-out that allows partial application. A dry run is still worth it, because it catches context mismatch and path errors before you touch the worktree, and gives you a clean signal to attach to the review. If you do use --reject, inspect the .rej files deliberately; a partial apply is now your responsibility.

For search/replace protocols, the equivalent is a uniqueness assertion:

def replace_once(text: str, old: str, new: str) -> str:
    count = text.count(old)
    if count != 1:
        raise AnchorError(f"expected 1 match, found {count}")
    return text.replace(old, new, 1)

That single check prevents the classic incident where a model replaces the first occurrence of a common line such as return None and silently changes the wrong function.

Trade-offs

Edit formatGood forCostFails when
Unified diffInteroperable, reviewable changesModels miscount context linesFiles have long unchanged regions or CRLF drift
Search/replace blockModel reliability, small editsAnchor ambiguity on repeated textThe snippet appears many times
Line-range replacementFast, cheapStale after any writeAnother tool formats the file
Whole-file rewriteNew files, generated codeTokens, collateral editsThe file is large or hand-maintained
AST-aware editStructural refactorsLanguage-specific toolingThe edit crosses syntax boundaries or the parse fails
Trade-off mapInteractive

Good for

Interoperable, reviewable changes

Cost

Models miscount context lines

Fails when

Files have long unchanged regions or CRLF drift

  1. Files have long unchanged regions or CRLF drift
  2. The snippet appears many times
  3. Another tool formats the file
  4. The file is large or hand-maintained
  5. The edit crosses syntax boundaries or the parse fails

Figure. Each choice with what it buys, what it costs, and the case where it loses.

What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.

Text version

Four trade-offs: Unified diff is good for Interoperable, reviewable changes, costs Models miscount context lines, and fails when Files have long unchanged regions or CRLF drift. Search/replace block is good for Model reliability, small edits, costs Anchor ambiguity on repeated text, and fails when The snippet appears many times. Line-range replacement is good for Fast, cheap, costs Stale after any write, and fails when Another tool formats the file. Whole-file rewrite is good for New files, generated code, costs Tokens, collateral edits, and fails when The file is large or hand-maintained. AST-aware edit is good for Structural refactors, costs Language-specific tooling, and fails when The edit crosses syntax boundaries or the parse fails

Failure modes

  • Ambiguous anchor. The context matches two functions and the patch lands in the wrong one. Debug: count matches at apply time and reject anything other than one; widen context automatically before asking the model again.
  • Whitespace and line-ending drift. The patch looks right but never applies because the file uses different indentation or CRLF. Debug: compare bytes of the anchor against the file, and normalise line endings at the reader boundary.
  • Fabricated context. The model invents surrounding lines it never read, so the hunk is well-formed and cannot apply. Debug: check anchors against the file before calling the applier and return the actual text at the nearest fuzzy match.
  • Semantic mismatch. The patch applies cleanly to a function with the same text but different intent. Debug: after applying, run the targeted test; a compile-only check will not catch this.

In production

Patch size is a useful guardrail. A task expected to touch two files that produces a twelve-file patch should pause for review rather than proceed; that is a scope signal, not a formatting one. Cap patch bytes per turn and reject patches that touch paths outside the task's allowlist.

Track apply success on the first attempt, anchor failures per hundred edits, and the share of applied patches that then fail verification. The third number is the one that matters: it measures whether the model understands the code, not whether it can format a diff. Keep the raw patch in the transcript so a reviewer can see intent separately from the final file.

Common misconceptions

People think: A patch that applies cleanly is a correct change.

Actually: Application only proves the anchor matched. Correctness needs a semantic check: a test, a type check, or a human read of the hunk.

People think: Full-file rewrites are safer because the model sees everything.

Actually: They are safer only for small files. At scale they invite collateral changes and make review expensive, which is where real defects hide.

Interview angle

A practical prompt: "the agent keeps editing the wrong function; what do you change?" The answer is in the protocol: unique anchors, fresh reads, version checks, and a precise rejection message. Then explain how you would measure it and why full-file rewrites are not the fix. See agentic coding interview questions, read/edit/execute and patch validation.

Sources