How Agents Make Changes

Topics We’ll Cover

• How Agents Make Changes
• Search-Replace, Unified Diff, Patch Files — Wire Formats
• Multi-File Edits — Atomicity, Rollback
• Context Window Management — Load, Summarise, Forget
• Tool Design for Editing — The Read/Edit/Write Trio
• Aider vs Cursor vs Claude Code — Three Architectures
• Test-Driven Agentic Edits
• Failure Recovery — When the Model Produces Bad Diffs
• What to Take Away

How Agents Make Changes

A coding agent ultimately has to write bytes to files. The mechanism through which it does so is more varied than it appears: there are at least five distinct edit formats in use across production agents, each with a different precision/robustness trade-off.

Search-Replace, Unified Diff, Patch Files — Wire Formats

Search-replace block

Aider popularised this format for its EDITOR mode. The agent emits a fenced block containing the text to find and the text to substitute. Claude Code’s Edit tool is a structured variant of the same idea.

src/db/pool.py
<<<<<<< SEARCH
    def acquire(self):
        conn = self._pool.pop()
        return conn
=======
    async def acquire(self) -> Connection:
        if not self._pool:
            raise PoolExhausted(
                f"pool exhausted after {self._max_size} conns"
            )
        return self._pool.pop()
>>>>>>> REPLACE

Unified diff — wire format

--- a/src/db/pool.py   2025-04-24 10:12:00.000000000 +0000
+++ b/src/db/pool.py   2025-04-24 11:00:00.000000000 +0000
@@ -47,7 +47,11 @@
     def _evict_idle(self, max_idle_secs):
         now = time.monotonic()

-    def acquire(self):
-        conn = self._pool.pop()
-        return conn
+    async def acquire(self) -> Connection:
+        if not self._pool:
+            raise PoolExhausted(
+                f"pool exhausted after {self._max_size} conns"
+            )
+        return self._pool.pop()

     def release(self, conn):

Applying patches programmatically

import subprocess, tempfile, pathlib

def apply_diff(diff_text: str, cwd: str, fuzz: int = 3) -> bool:
    with tempfile.NamedTemporaryFile(suffix='.patch', mode='w', delete=False) as f:
        f.write(diff_text)
        patch_path = f.name
    result = subprocess.run(
        ['patch', '--unified', '--forward',
         f'--fuzz={fuzz}', '-p1', '-i', patch_path],
        cwd=cwd, capture_output=True, text=True
    )
    pathlib.Path(patch_path).unlink(missing_ok=True)
    return result.returncode == 0

Multi-File Edits — Atomicity, Rollback

Many real edits touch multiple files simultaneously: rename a function and update all its callers, change an API contract and update both the implementation and its tests. Applying these changes partially — some files updated, some not — leaves the repo in a broken state. Agents need a transactional strategy.

Conflict detection for concurrent edits

In multi-agent or long-session scenarios, a file may have been modified externally since it was read. Agents should compare the SHA-256 of the file at read time with the file at write time. If they differ, the agent must re-read and re-apply its edit rather than clobber an intervening change.

Context Window Management — Load, Summarise, Forget

Even a 200 k-token context window fills quickly during a multi-step edit session: conversation turns, file reads, test output, error messages, and the agent’s own reasoning all compete for the same budget. Managing what stays in context is as important as retrieval.

Concrete techniques

Tool Design for Editing — The Read/Edit/Write Trio

Claude Code exposes three core editing tools. Their design is not arbitrary: each enforces a constraint that prevents a class of common failure.

Why the “must read first” constraint matters

// Turn 1: agent reads the file
Read({ file_path: "src/db/pool.py", offset: 40, limit: 20 })
// → returns lines 40–60 with line numbers

// Turn 2: agent issues the precise edit
Edit({
  file_path: "src/db/pool.py",
  old_string: "    def acquire(self):\n        conn = self._pool.pop()\n        return conn",
  new_string: "    async def acquire(self) -> Connection:\n        if not self._pool:\n            raise PoolExhausted(f\"pool exhausted\")\n        return self._pool.pop()"
})
// → success: { bytes_written: 412 }

// Turn 3: agent verifies by running the tests
Bash({ command: "pytest tests/test_pool.py -x -q 2>&1 | tail -20" })

Aider vs Cursor vs Claude Code — Three Architectures

The three most widely used coding agents have chosen fundamentally different edit architectures. Understanding these choices explains their respective strengths and failure modes.

Test-Driven Agentic Edits

A failing test is the highest-signal feedback signal an agent can receive. The TDD agentic loop is simple in principle but requires careful engineering to avoid infinite retry loops and token runaway.

Practical engineering details

Failure Recovery — When the Model Produces Bad Diffs

Even the best models produce malformed or semantically incorrect diffs on a non-trivial fraction of requests. Production agents need a layered recovery strategy.

Taxonomy of edit failures

Fuzzy-matching as a first-line recovery

from difflib import SequenceMatcher

def find_best_match(source: str, pattern: str,
                    threshold: float = 0.85) -> tuple[int, int] | None:
    """Return (start, end) char offsets of best fuzzy match, or None."""
    lines = source.splitlines(True)
    pat_lines = pattern.splitlines(True)
    best_ratio, best_start, best_end = 0.0, 0, 0
    for i in range(len(lines) - len(pat_lines) + 1):
        window = lines[i : i + len(pat_lines)]
        ratio = SequenceMatcher(None, window, pat_lines).ratio()
        if ratio > best_ratio:
            best_ratio, best_start = ratio, i
            best_end = i + len(pat_lines)
    if best_ratio >= threshold:
        start_char = sum(len(l) for l in lines[:best_start])
        end_char   = sum(len(l) for l in lines[:best_end])
        return start_char, end_char
    return None

What to Take Away

• Edit format choice is consequential. Whole-file rewrites are unambiguous but token-expensive. Unified diffs are compact but model-error-prone on line numbers. Search-replace blocks are the practical sweet spot: compact, unambiguous, and fuzzy-matchable.
• Uniqueness enforcement prevents silent clobbers. The Claude Code Edit tool’s requirement that old_string appear exactly once is not a limitation — it is a safety invariant. Never relax it silently; use replace_all only when that is genuinely the intent.
• Multi-file edits need a transaction model. Stage in memory, validate syntax, then write atomically. Use git checkout -- . or os.replace() semantics for rollback. Never leave the repo in a partial state.
• Context window is a finite resource. Put stable content (repo map, system prompt) first for prompt-cache hits. Truncate test output. Summarise old conversation turns. The “forget” step is as important as the “load” step.
• Know the three agents’ edit architectures. Aider stages in memory before writing; Cursor requires explicit user acceptance; Claude Code issues sequential tool calls with no formal transaction. Design your own agent with these trade-offs in mind.
• TDD loops are the highest-signal feedback. Run tests after every edit. Cap retries at 3–5. Truncate test output. Escalate to the user on repeated failure.
• Failure taxonomy drives recovery. Parse failures → re-prompt format. No-match → force re-read. Syntax error → rollback. Semantic error → test-driven retry. Wrong file → human checkpoint.