atomic-code-edits

Atomic Code Edits (Targeted Differential Patching)

Overview

When modifying existing source files, naive agents rewrite the entire file from line 1 to line 800 using tools like write_to_file.

Full-file overwrites suffer from three catastrophic failure modes:

1. The Truncation Disaster: The model outputs // ... rest of existing code remains unchanged ..., permanently deleting critical business logic.
2. Extreme Token Waste: Modifying a 1-line boolean flag in an 800-line file generates 3,000+ output tokens instead of 30 tokens.
3. Severe Generation Latency: Streaming an entire file takes 15 to 25 seconds per edit turn, slowing down developer feedback loops.

The Atomic Code Edit Protocol enforces targeted differential patching using character-exact substring replacement tools (replace_file_content, multi_replace_file_content).

---

Full-File Overwrite vs. Atomic Differential Patch

┌─────────────────────────────────────────────────────────────┐
│                 Code Mutation Token Economics               │
│                                                             │
│  Full File Overwrite (`write_to_file`):                     │
│  • Agent regenerates all 650 lines                          │
│  • 2,800 Output Tokens streamed                             │
│  • 18.2 Seconds Latency                                     │
│  • High risk of comment/type erasure                        │
│                                                             │
│  Atomic Patch (`replace_file_content`):                     │
│  • Agent targets lines 142-146 only                         │
│  • 35 Output Tokens streamed                                │
│  • 0.4 Seconds Latency (45x Faster!)                        │
│  • 100% Codebase Integrity Guaranteed                       │
└─────────────────────────────────────────────────────────────┘

---

The 4 Rules of Precision Atomic Editing

1. Tight Line Bounding (StartLine / EndLine)

Specify the smallest possible line range containing the target code (e.g., StartLine: 140, EndLine: 148). This confines the search window, preventing accidental replacement of duplicate variable names elsewhere in the file.