- In short
- The Edit tool performs an exact, unique-match string replacement on a file you have already read, making it the fast, low-risk way to change code. When the target text is not unique and cannot be pinned down with surrounding context, you fall back to reading the file and rewriting it with Write.
What the Claude Code Edit tool actually does
The Claude Code Edit tool is the instrument for changing existing code with surgical precision. You give it a file path, an old_string, and a new_string, and it swaps the first for the second, leaving every other byte of the file untouched. There is no regex and no fuzzy matching here: the match is literal, character for character, including whitespace and indentation. That strictness is a feature, because it means an edit either lands exactly where you intended or refuses to land at all.
This is the tool you apply to the overwhelming majority of code changes, renaming a variable in one place, flipping a config value, fixing a single function body. Because the change is expressed as a difference rather than a whole new file, the result is a clean diff that a human or a review subagent can read at a glance, and it is far less likely to introduce a regression than rewriting the entire file from memory.
- Edit tool
- A Claude Code built-in that performs exact string replacement on a file: it finds a unique old_string and replaces it with new_string, applying only after read-before-edit, exact-match, and uniqueness checks pass.
The three checks every edit must pass
Edit guards itself with three checks, evaluated in a fixed order, and understanding them explains every success and every failure you will see.
- Read-before-edit. Claude must have read the file in the current conversation, and the file must not have changed on disk since that read. This runs first, before any matching. It is why an agent cannot blindly edit a file it has never opened.
- Match. The
old_stringmust appear in the file exactly as written. A single differing space, tab, or line ending is enough to miss, which is why copied-but-slightly-wrong anchors fail. - Uniqueness. The
old_stringmust appear exactly once. If it appears more than once, Edit will not guess which one you meant.
When uniqueness fails, there are two clean ways forward without abandoning Edit: supply a longer old_string that includes enough surrounding lines to identify a single occurrence, or set replace_all to change every occurrence deliberately. Only when neither fits do you drop to the fallback.
The Read plus Write fallback
Sometimes the change is too sprawling or too ambiguous for a targeted edit, the anchor text repeats throughout the file and you genuinely want to restructure rather than replace one line. That is when you fall back to Read plus Write. You Read the file to bring its current contents into context, construct the full new version, and Write it back. Write creates or overwrites a file with the complete content you provide; it does not append or merge.
Write carries its own guard that mirrors Edit's: if the target path already exists, Claude must have read it at least once in the current conversation before overwriting, so a Write to an unread existing file fails. New files are exempt, which is why Write is also the tool for creating files from scratch. The mental model is simple. Edit for a precise change to part of a file, Read plus Write when you are replacing the whole thing.
Why Edit beats Write for small changes
It is tempting to treat Write as the universal hammer, read the file, rebuild it with the one change baked in, write it back, but for a small change that is the wrong instinct and an explicit exam trap. A full Write re-emits the entire file, which means more tokens, more opportunity to accidentally alter an unrelated line, and a diff that shows the whole file as touched rather than the one line that actually changed. Edit does the opposite: minimal tokens, a tightly scoped diff, and no collateral risk to the rest of the file.
So the discipline is to default to Edit and escalate to Write only when the change genuinely spans most of the file or the anchor cannot be made unique. An architect who reaches for Write to flip a single boolean has chosen the slower, riskier tool for no benefit, and that is precisely the judgement Task Statement 2.5 is checking.
Putting it to work
The skill the exam measures is not reciting the rules but applying them to a concrete change request and picking the lightest tool that does the job correctly. The worked example below walks one such request from anchor selection through the fallback decision.
A reliable way to approach any change request is to walk the ladder out loud. First ask whether you have read the file, because nothing else matters until read-before-edit is satisfied. Then ask whether the text you want to change can be anchored uniquely as it stands; if so, a single Edit finishes the job. If the anchor repeats, ask whether you can widen it with surrounding context to isolate the one occurrence you mean. Only if every rung of that ladder fails do you decide between a deliberate replace_all and a full Read plus Write. Naming each rung in order keeps you from skipping straight to the heaviest tool, which is the mistake the scenario is usually built to catch.
Worked example
A teammate asks Claude Code to change the default retry count from 3 to 5 in a service config, where the literal value 3 appears many times across the file.
You start, as Edit demands, by reading the config file. Now you face the uniqueness check head on. The naive anchor, an old_string of just 3, would fail, because the digit appears in timeouts, version numbers, and array indices throughout the file. Edit refuses to guess among them, and that refusal is protecting you from silently corrupting an unrelated value.
The right move is to widen the anchor, not to abandon Edit. You select an old_string that carries enough surrounding context to be unique, such as the full line retryCount: 3 or even defaultRetries: 3, with its trailing punctuation, and replace it with the same line carrying 5. Because that longer string occurs exactly once, the uniqueness check passes and the edit lands on precisely the right value, leaving every other 3 in the file untouched.
Only if the value were truly impossible to isolate, say you needed to change every retry constant at once, would you either set replace_all deliberately or fall back to Read plus Write and rebuild the file. For a single targeted change, escalating that far would be using a heavier tool than the task needs, re-emitting the whole config and widening the diff for no reason. The lesson is the ladder: unique anchor first, then context-widened anchor or replace_all, and only then the full rewrite.
Common misreadings to avoid
Both traps below come from misunderstanding how Edit decides whether to apply a change.
Misconception
The Edit tool uses fuzzy or regex matching, so a close-enough old_string will still work.
What's actually true
Misconception
For any change to an existing file I should just read it and Write the whole thing back.
What's actually true
Why read-before-edit exists
The read-before-edit rule can feel like friction until you see what it prevents. By requiring that Claude has read the file in the current conversation, and that the file has not changed on disk since that read, Edit guarantees it is operating on the version it actually saw. Without that guarantee an edit could be written against a stale mental copy while the real file had moved on, and the exact-match check would either miss or, worse, land the change in a place that no longer means what it did. The rule converts a class of silent corruption into an upfront, recoverable error.
There is a useful nuance the exam can lean on. Viewing a file through certain Bash commands, such as a plain cat, head, tail, or grep on a single file with no pipes, also satisfies the read-before-edit requirement, because Claude has genuinely seen the contents. Piped or scripted reads do not count, since the contents never reach the model directly. So the requirement is really about whether the current model context has seen the file, not about which specific tool did the showing.
Widening the anchor versus replace_all
When the uniqueness check fails, the two recoveries are not interchangeable, and choosing between them is a judgement the exam can test. Widening the anchor, by adding surrounding lines until the old_string identifies exactly one occurrence, is the right move when you mean to change a single site and the repetition is incidental. It keeps the edit surgical and the diff minimal. Setting replace_all is the right move only when you genuinely intend to change every occurrence at once, such as a project-wide rename you have already decided on.
The danger is reaching for replace_all as a shortcut past a uniqueness error you did not actually want to resolve globally. That turns a one-line intention into a sweeping change, and on a value that appears in many unrelated contexts it can rewrite lines you never inspected. The disciplined ladder is to widen the anchor first, escalate to replace_all only when the intent is truly global, and drop to a full Read plus Write only when the change is too large or tangled for either. Each rung trades a little precision for a little reach, and picking the lowest rung that fits the intent is what a careful architect does.
The text editor tool behind Edit
At the API level, the same surgical replacement Claude Code performs is exposed as the text editor tool, whose core command is str_replace: it replaces an exact old string with a new string and, just like Edit, refuses the change when the target text is not unique. The behaviour you see in the CLI, literal matching and a uniqueness requirement, is not a quirk of Claude Code but the documented contract of the underlying tool. An architect who understands the API tool understands why Edit fails the way it does.
The other half worth knowing is the execution model. Claude Code's file tools are client tools, which means Anthropic does not run them for you. When Claude decides to edit, the response returns with stop_reason: "tool_use" and a tool_use block describing the operation; your application performs the read, the replacement, or the write, then sends the outcome back as a tool_result. If your integration provides only an edit handler and no read or create path, Claude can be left unable to finish a task, which is the practical reason read-before-edit and the Read plus Write fallback exist as first-class capabilities rather than afterthoughts.
This is also why the tool definition matters. A well-formed text editor tool declares a clear description and input_schema, and Anthropic recommends setting strict: true so the arguments Claude generates match the schema exactly. A vague schema produces malformed edit calls; a precise one makes the unique-match contract reliable. For the exam, hold the chain in mind: the Claude Code Edit tool is a client-side surfacing of the API text editor tool, your application executes it, and the same exact-and-unique rule governs both.
How this shows up on the exam
Within Domain 2 and its Scenario 4 developer-productivity framing, Edit and the Read plus Write fallback appear as judgement calls about which modification tool fits a described change. A question might present a one-line fix and offer Write as a tempting option, or describe an Edit that failed and ask why, the answer being a non-unique anchor, an unread file, or a whitespace mismatch. The official Anthropic Academy lesson on the text edit tool, embedded below, demonstrates the same unique-match behaviour on the API side, and the exam expects you to translate that behaviour into the right tool choice under time pressure.
Claude Code attempts to rename a helper using Edit, but the call returns an error saying the old_string is not unique because the helper name appears in eight places. The intent is to rename only the definition. What is the best next step?
People also ask
Why does the Claude Code Edit tool fail?
Does the Edit tool require reading the file first?
When should I use Write instead of Edit?
Watch and learn
Official Anthropic Academy lessons first, then hand-picked walkthroughs. Videos load only when you press play.
The text edit tool
Why watch: The built-in text editor performs targeted, unique-match edits, the same precise modification behaviour this Edit KP describes.
More videos for this concept
References & primary sources
Master this concept with Archie
Practice it inside an adaptive study session. Archie, your Socratic AI tutor, tracks your mastery with Bayesian Knowledge Tracing and schedules the perfect next review.