Why Anthropic Chose String Replacement Over Diff-Based File Editing
TRIGGER
Coding agents needed to make precise edits to existing files, but various edit specification formats (diffs, line numbers, full file rewrites) had reliability issues—models would specify edits incorrectly, target wrong locations, or corrupt files.
APPROACH
Anthropic tested several edit strategies and found string replacement most reliable: the model specifies `old_str` to replace with `new_str`. The tool only applies the edit if exactly one match exists. If zero or multiple matches occur, the model receives an error and retries. This forces the model to include enough surrounding context to uniquely identify the edit location, and provides clear feedback when the specification is ambiguous.
PATTERN
“Diffs and line numbers let the model specify edits it does not actually understand. Require old_str/new_str replacement with unique-match enforcement. Zero or multiple matches returns an error. The model must prove it found the right location before any edit applies.”
✓ WORKS WHEN
- Edits are localized changes rather than large-scale refactors
- Files have enough unique content that matches can be disambiguated with reasonable context
- The model can see the current file state to construct accurate old_str values
- You can afford retry loops when the model's first specification is non-unique
- Code style in the target repo is consistent enough for pattern matching
✗ FAILS WHEN
- Files contain many similar or duplicated code blocks (boilerplate-heavy code)
- Edits span multiple non-contiguous locations that would require separate operations
- Large-scale refactors require changing dozens of similar patterns
- The model cannot view the current file state before editing
- Performance requires single-shot edits without retry opportunities