File Editing: Reading, Writing, and Navigating Code

Series: Claude Learning Journey · Core Workflows

The read and write tools are how Claude interacts with your project. They are simple primitives — open a file, close it, write some content — but they unlock everything that makes Claude useful for real engineering work. This is not about AI magic. It is about giving Claude access to your code so it can actually help you fix, refactor, or build things.

Reading files

The read tool takes a file path and returns the contents. You can specify line ranges to avoid loading a 5,000-line file when you only need a specific function.

read: path/filename.py, offset: 1, limit: 50

This returns the first 50 lines. If you already know the function is around line 230, use offset: 220, limit: 40 to get a window around it.

When you are exploring an unfamiliar codebase, a useful approach is to ask Claude to “find” or “show” rather than blindly reading entire files. “Show me the user authentication flow starting from the login endpoint” is better than “read all the files.”

Glob and recursive discovery

Many tools support glob patterns for finding files:

• **/*.test.js — all test files in the project
• **/components/* — everything in a components directory
• **/package.json — configuration files scattered across the project

This is useful when you know something exists but not exactly where.

Writing files

The write tool creates or overwrites a file with the content you specify. It is atomic — the file either has the new content or it does not. There is no partial write.

Writing is for:

• New files you want to create from scratch
• Replacing entire files you have already reviewed and confirmed
• Writing generated code like configs, test fixtures, or migration scripts

Do not use write to make small changes to existing files. Use edit instead.

Editing files

The edit tool replaces a specific block of text in an existing file. This is the surgical tool — you point at exactly what should change and provide the replacement.

An edit call needs two things:

1. oldText — the exact text currently in the file that you want to replace
2. newText — what you want to replace it with

Both must match exactly. If the file has changed since you last read it, the edit will fail. This is deliberate — it prevents accidental clobbering of concurrent changes.

Example edit:

oldText: "const port = process.env.PORT || 3000;"
newText: "const port = process.env.PORT || 8080;"

This changes the default port. The change is surgical and obvious, which means it is easy to review.

Common editing patterns

Inline a function call:

oldText: "const result = calculate(items);"
newText: "const result = calculate(items.filter(i => i.active));"

Change a configuration value:

oldText: "timeout: 5000,"
newText: "timeout: 30000,"

Wrap a block in a condition:

oldText: "sendNotification(user, message);"
newText: "if (user.notificationsEnabled) {\n  sendNotification(user, message);\n}"

Navigating a codebase

File editing in isolation is fragile. The most reliable approach follows a pattern:

1. Read the relevant files first. Understand the structure before making changes. 2. Plan the edit. Identify exactly what needs to change and where. 3. Make the edit. Use the edit tool with precise oldText. 4. Verify. Read the modified section to confirm it looks right.

Blind edits — changing something you have not read — is how bugs get introduced. Claude can only work with what it has seen. If you ask it to change a function it has not read, it will guess based on the name and docstring, which is unreliable.

Multi-file refactors

When a change spans multiple files, the pattern scales:

1. Read all the files involved in the change
2. Plan the changes for each file
3. Execute the edits, one file at a time
4. Verify each modified file

The read tool does not count against output tokens in the way that including file contents in your prompt does. Reading a file costs almost nothing compared to pasting its contents into a message.

Using git as a navigation aid

Pair Claude’s file tools with git to understand history and context:

• “Show me the last 10 commits to this file”
• “Who wrote the original implementation of this function?”
• “What changed in this file between commits X and Y?”

Claude can read git output, so git log, git diff, and git blame become research tools for understanding why code is the way it is.

Try it yourself

Pick a small file in a project you are working on — a utility module, a config file, a helper function. Use the read tool to examine it closely, then ask Claude to make one small improvement. Review the edit before accepting it. Notice how the read-edit-verify loop keeps you in control.

What’s Next

Claude can interact with more than just files on disk. The next post covers tools — how Claude calls out to bash, web search, and other external services to extend what it can do.

Part of the Claude Learning Journey series · Next: Using Tools — Bash, Web Search, and Everything Else