Edit vs Write in Claude Code: Unique Anchors, the Read + Write Fallback, and Call-Site Tracing

1.Edit replaces exact text; Write replaces the whole file

The three file tools in Claude Code differ in how much of a file they touch. Read takes a file_path and, optionally, an offset and limit, and returns the file's contents. Write takes a file_path and content, and the tools reference says it "Creates or overwrites files". Whatever you pass as content becomes the whole file. Edit takes a file_path, an old_string, a new_string and an optional replace_all flag. It finds the old text and swaps in the new text, which is why the reference describes it as making "targeted edits to specific files".

So Edit works by matching text, not by line number. The Claude API's text editor tool is a separate, API-level tool, not Claude Code's Edit, but it uses the same idea in its str_replace command. Its documentation states the rule plainly: old_str is "The text to replace (must match exactly, including whitespace and indentation)". An anchor that is off by one space of indentation matches nothing.

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "str_replace_based_edit_tool",
  "input": {
    "command": " ? ",
    "path": "primes.py",
    "old_str": "for num in range(2, limit + 1)",
    "new_str": "for num in range(2, limit + 1):"
  }
}

Sources123

2.The uniqueness rule for old_string

Matching text has an obvious risk: the same text can appear in more than one place. The tools reference handles this directly. "Uniqueness: old_string must appear exactly once." Edit does not guess which occurrence you meant. When the string appears more than once, the reference describes two remedies. Claude "either supplies a longer string with enough surrounding context to pin down one occurrence, or sets replace_all: true to replace them all."

The two remedies fit different goals. A longer anchor is right when exactly one occurrence should change. Include the function signature above the line, or a nearby comment, so that the combined string appears only once. replace_all is right when every occurrence really should change, as in a rename within one file. Using replace_all to dodge a uniqueness problem when only one site should change would edit lines you never meant to touch.

Sources1

3.When Edit can't anchor: Read, then Write

Sometimes neither remedy fits. The repeated text may have no surrounding context that makes it unique. Or the change may not be a single replacement at all. Gathering several scattered export statements into one block near the top of a file, for example, means deleting text in many places and adding it in another.

The exam expects a third approach for these cases: Read the full file, build the corrected version, and Write it back. The documentation doesn't name this as a fallback for Edit. It follows from how the tools work. Edit needs an exact, unique match. Write needs no anchor, because it "Creates or overwrites files" with whatever content you give it.

That same property is the danger. Write replaces the whole file, so the new content has to be built from a fresh Read of the current file. Anything left out of content is gone. Edit stays the default for targeted changes. Read + Write is for changes that can't be expressed as a unique find-and-replace.

Sources13

4.Tracing a function through wrapper modules

Before changing a function's signature, you need every call site. The obvious step is to Grep for the function's name. That works until the function is re-exported under another name. A wrapper module might export formatDate as fmt, and code that imports the alias will never contain the string formatDate.

The sources don't describe this technique directly. It follows from how Grep works: its pattern is a "Regular expression pattern to search for", so it finds only the text you ask for. A reliable trace therefore has two stages. First, Read the wrapper module and list every name it exports for the function, the original and each alias. Then Grep the codebase for each of those names. Because the pattern is a regex, one search can cover several names, and setting output_mode to content shows the matching lines instead of just file names. Each hit then becomes an Edit at a known location.

This is the same search-before-reading habit the common-workflows guide encourages with prompts like "find deprecated API usage in our codebase". Search tells you where to look, and Read and Edit act only on those places.

Sources34

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.If old_string appears several times, Edit just replaces the first occurrence.Why is that wrong?

   old_string must appear exactly once. Otherwise the anchor needs more surrounding context, or replace_all has to be set deliberately.

   Covered in The uniqueness rule for old_string

2. 2.When Edit can't anchor a change, Write just the changed section to the file.Why is that wrong?

   Write overwrites the whole file, so the content must be the complete new file, built from a fresh Read.

   Covered in When Edit can't anchor: Read, then Write

3. 3.Grepping for a function's original name finds all of its call sites.Why is that wrong?

   Grep matches only the pattern you give it, so callers that use a re-exported alias are missed unless each exported name is searched.

   Covered in Tracing a function through wrapper modules