Coding Agents: How They Actually Edit Code

When a coding agent modifies your source code, it is not performing magic, nor is it typically regenerating entire files from a blank slate. It is executing a precise sequence of text manipulation operations governed by strict formatting rules. Understanding these mechanics—specifically unified diffs, search-and-replace logic, and repository context—is essential for debugging why an agent might break a build or introduce subtle bugs.

The Anatomy of a Unified Diff

The primary vehicle for code modification in most coding agents is the unified diff format. This format is not arbitrary; it is designed to convey minimal changes with maximal context. A unified diff consists of hunk headers and content lines. The hunk header, marked by @@, defines the line numbers and lengths of the old and new sections. This structured approach allows a coding agent to propose changes that are both precise and reversible.

Consider a Python function calculate_total. An agent might generate the following diff:

--- a/src/calc.py
+++ b/src/calc.py
@@ -10,4 +10,5 @@ def calculate_total(items):
     total = 0
     for item in items:
-        total += item.price
+        if item.is_valid:
+            total += item.price
     return total

The lines prefixed with - are removed, and + are added. Crucially, the lines with no prefix are context lines. These context lines serve two purposes: they help the human reader understand the change, and they provide anchors for the application logic. When the agent applies this diff, the system looks for the specific sequence of context lines to locate the exact insertion point. If the context lines have changed since the agent read the file, the patch fails. This is why agents often fail silently or produce errors when the file has been modified concurrently.

The agent’s challenge is to generate diffs that are small enough to be unambiguous but large enough to be unique within the file. Overly large hunks increase the risk of matching multiple locations; overly small hunks may lack sufficient context to distinguish the target code from similar patterns elsewhere.

Search-and-Replace Logic

While diffs are the standard for patching, many agents employ search-and-replace operations for targeted modifications. This is particularly common in refactoring tasks where a specific pattern needs to be replaced across multiple files. The search replace mechanism is critical for ensuring that changes are applied exactly where intended without altering unrelated code blocks.

Naive string matching is insufficient for modern codebases. A simple search for import json might match dozens of unrelated imports. Instead, agents use multi-line context windows to create unique search signatures. For example, to replace a specific function call, the agent might search for the three lines preceding and three lines following the target line.

# Search signature
old_text = """
    def process_data(raw):
        data = json.loads(raw)
        return data.get('key')
"""
 
new_text = """
    def process_data(raw):
        data = json.loads(raw)
        return data.get('key', None)
"""

The agent verifies that old_text appears exactly once in the target file. If it appears multiple times, the agent must either expand the context window to include more unique identifiers (such as variable names or class scopes) or fail and request user clarification. This uniqueness constraint is critical. If the agent applies a non-unique replacement, it introduces a bug by modifying unintended code blocks.

Some advanced agents use regular expressions for search-and-replace, allowing for pattern-based modifications. However, regex introduces complexity in escaping special characters and handling multiline matches. Most production agents stick to literal string matching with context to avoid regex injection vulnerabilities and parsing errors.

Repository Context as a Constraint

A coding agent does not operate in a vacuum. It relies on repo context to ensure that edits are syntactically and semantically valid. This context includes the file tree, import statements, type signatures, and sometimes the AST (Abstract Syntax Tree) of the codebase. By understanding the broader project structure, the agent can make informed decisions about dependencies and scope.

When an agent decides to modify a function, it first reads the surrounding context. This involves:

1. File Tree Navigation: Understanding where the target file resides relative to others.
2. Import Resolution: Checking if the symbols used in the edit are imported correctly.
3. Type Checking: Verifying that the new code adheres to type constraints defined in the project.

For instance, if an agent adds a new function validate_email, it must ensure that the function is exported if it’s intended for public use, and that any dependencies it uses are imported. Without this context, the agent might generate code that compiles locally but fails when integrated into the larger project.

The agent’s context window is limited. Modern models have large contexts, but they still face truncation issues. Agents often use heuristic strategies to select the most relevant context, such as prioritizing files that are recently modified or directly importing the target file. This selection process is a trade-off between completeness and relevance. Including too much context can confuse the model with irrelevant information, while including too little can lead to hallucinated dependencies.

Error Handling and Retry Loops

Coding agents are not perfect. They frequently encounter errors when applying edits. These errors typically fall into two categories: syntax errors and patch application errors. Effective code editing requires robust mechanisms to handle these failures gracefully and iteratively.

A syntax error occurs when the generated code is invalid. The agent receives feedback from the linter or compiler, which provides an error message. The agent then uses this feedback to refine its generation. For example, if the linter reports an undefined variable, the agent might add the necessary import or fix the variable name.

A patch application error occurs when the diff cannot be applied. This happens when the context lines in the diff no longer match the current state of the file. The agent receives an error message indicating the failure. It then attempts to re-read the file, update its context, and regenerate the diff. This retry loop is crucial for robustness. Without it, agents would fail on the first sign of file drift.

Some agents implement a "guess and check" strategy. They apply the diff tentatively, run tests, and roll back if the tests fail. This approach is slower but more reliable than pure generation. It leverages the test suite as a ground truth for correctness.

Conclusion

Coding agents manipulate code through a combination of precise diffing, context-aware search-and-replace, and rigorous validation against repository context. They are not rewriting code from scratch but rather making surgical adjustments to existing structures. Understanding these mechanisms helps developers anticipate failures and collaborate more effectively with AI tools. The key to successful agent-assisted development is recognizing that the coding agent is a text manipulation engine constrained by context, not an omnipotent coder. By providing clear context and validating outputs, developers can harness the power of these agents while mitigating their inherent risks.