Lesson 468 of 2116
Reading vs Editing: When To Use Read+Edit vs Write
Claude Code has Read, Edit, and Write tools. The choice between them shapes performance, safety, and how recoverable a mistake is.
Lesson map
What this lesson covers
Learning path
The main moves in order
- 1Three tools, three different jobs
- 2Read tool
- 3Edit tool
- 4Write tool
Concept cluster
Terms to connect while reading
Section 1
Three tools, three different jobs
Read pulls a file into context. Edit makes a surgical replacement (old string to new string). Write replaces a file entirely. They look interchangeable in a chat trace; they aren't. Edit preserves the parts you didn't touch — Write trusts the model to remember everything that was in the file.
The cost of getting it wrong
Compare the options
| Tool | Risk | When to prefer |
|---|---|---|
| Read | Wastes context if file is huge | Always before any edit |
| Edit | Fails if old string isn't unique enough | Existing files, surgical changes |
| Write | Overwrites — loses anything not in the new content | Brand new files, full rewrites |
Read before any non-trivial edit
If the model is editing a file it hasn't read in this session, expect a high error rate. The Edit tool needs to match exact text. Without a Read, the model is guessing — and guessing produces failed edits or, worse, silently wrong ones. CLAUDE.md should reinforce 'always read before editing.'
When Write is genuinely the right tool
- 1Brand new files — there's no old content to preserve
- 2Full rewrites where you're explicitly throwing the old version away
- 3Generated files where the source of truth is elsewhere
- 4Tiny files (a few lines) where reading-then-editing is no cheaper
- 5Files where keeping line numbers stable matters less than getting the new shape right
Apply: a self-audit
- 1Watch your next 5 sessions; note every Write call
- 2For each, check: was there an existing file? Did the agent read it first?
- 3If not, was content lost? Compare git diff to what you expected
- 4Tighten CLAUDE.md to require Read+Edit on existing files
Key terms in this lesson
The big idea: Edit existing files surgically. Write only when you're starting fresh or rewriting completely. Read before you edit, every time.
End-of-lesson quiz
Check what stuck
15 questions · Score saves to your progress.
Tutor
Curious about “Reading vs Editing: When To Use Read+Edit vs Write”?
Ask anything about this lesson. I’ll answer using just what you’re reading — short, friendly, grounded.
Progress saved locally in this browser. Sign in to sync across devices.
Related lessons
Keep going
Creators · 45 min
Structured Outputs: Make the Model Return Data You Can Trust
For production apps, pretty prose is often the wrong output. Learn when to use structured outputs, function calling, and schema validation.
Creators · 9 min
Pro Search vs Default: When To Spend The Compute
Pro Search runs more queries, reads more pages, and routes to a stronger model. It is not always worth the wait — knowing when it is is the skill.
Creators · 10 min
Perplexity API: Building RAG Without Owning The Pipeline
The Perplexity API gives you cited search answers with one call. It is the cheapest way to add grounded retrieval to a product — and the limits are worth understanding.