File tools: Read, Write, Edit

Read

Read is the always-safe verb. It pulls a file into the conversation so the model has the current contents in context. Two facts about it:

• Reads are cheap. If you doubt Claude has the right version of a file, ask it to Read again — you can never over-Read.
• Reads are chunked when needed. For large files you can pass offset and limit to grab a specific slice. Useful for a 5,000-line generated file where you only care about lines 800–900.

If Claude proposes to Read a file, you can approve almost without thinking. Nothing changes.

Write

Write creates a new file, or replaces an existing one wholesale. It is the correct tool when:

• The file does not yet exist.
• You have decided the file needs to be completely rewritten from scratch (e.g. a config file, a JSON manifest).

It is the wrong tool when you want a small change inside a file with existing content. In that case Write will overwrite everything, and if Claude’s model of the current file is stale by even one line, the “small change” will silently revert two other unrelated edits you made ten minutes ago.

Edit

Edit is the surgical tool. It takes an old string and a new string, finds the old string in the file, and replaces it. Three properties make it safe:

• Exact match required. The old string has to appear character-for-character. Whitespace matters. Line endings matter.
• Uniqueness required. If the old string appears more than once, Edit fails rather than guessing which one you meant. (There is a replace_all flag when you actually do want to replace every occurrence — for a rename, say.)
• Read-first enforcement. The tool refuses to Edit a file that has not been Read in the current session. This is the check that prevents editing a stale version.

Edit is what you want for 90% of changes. It composes well: two small edits are easier to review than one big Write.

Common mistakes

• Rewriting instead of editing. “I’ll just Write the whole file with the new function added” — resist. Do an Edit that adds only the new function.
• Editing without Reading first. Claude will usually Read for you, but if you paste a file into the prompt yourself and immediately ask for an Edit, the tool may refuse. Read first, edit second.
• Trying to Edit a file that does not exist yet. Use Write for creation.

Check your understanding

Quick check

—

You want Claude to change the `MAX_RETRIES` constant in `src/config.ts` from 3 to 5, and nothing else in that file. Which tool is right?

1. AWrite — replace the whole file to be safe.
2. BRead, then Edit — the Edit finds the exact string "MAX_RETRIES = 3" and replaces it with "MAX_RETRIES = 5".
3. CBash — sed does it in one line.
4. DWebFetch — for good measure.

Check answer→