Reading & Editing Files

Reading and editing files is the most-used capability in Claude Code by far, and the mechanics behind it are simpler than they might seem: a small set of distinct operations, used differently depending on the situation.

Reading

Reading a file pulls its content into context, line-numbered, so Claude can refer to specific lines precisely. For large files, reading can be scoped to a range — useful when you already know roughly where the relevant code lives and don't need the other 2,000 lines of an unrelated module loaded alongside it.

Editing: targeted replacement, not regeneration

The default way to change an existing file is a targeted string replacement: find an exact block of existing text and replace it with new text, leaving everything else in the file completely untouched. This matters for a few concrete reasons:

• Precision. A large language model regenerating an entire file from scratch can introduce subtle, unrequested changes elsewhere in the file — a different code path could be a single character off and easy to miss. A targeted replacement physically can't touch anything outside the block being changed.
• Reviewability. A diff against a one-line change is one line. A diff against a full-file rewrite of a 400-line file is 400 lines, even if 395 of them are identical — which defeats the point of reviewing the diff at all.
• Conflict safety. If a file changed since it was last read (someone else edited it, or an earlier step in the same session already touched it), an edit tool can detect that the expected "before" text no longer matches and refuse rather than silently overwriting unrelated work.

When a full rewrite is the right call

Targeted replacement assumes the file mostly stays the same and a piece of it changes. For a brand-new file, or a file getting restructured so thoroughly that almost nothing survives unchanged, a full write is the more honest operation — there's no meaningful "before" to diff against piece by piece.

Multi-file changes

A single logical change — renaming a function and updating every call site, say — usually touches several files in one pass. Each file gets its own precise edit; the change is coherent across the whole set, but no file is touched more than the change actually requires.

What you should be checking

Given that edits are shown as diffs (depending on your permission mode), the most useful thing to look at before approving is why a change was made where it was made, not just whether the resulting code looks plausible — a plausible-looking change can still be solving the wrong problem.

Next: the bash tool, for everything that isn't a file operation.