Always read a file before editing it

The Edit tool (and similar find-and-replace based code editing tools) fails or produces wrong results when you attempt to modify a file without first reading its contents. Common failure modes: (1) The old_string doesn't match because whitespace (tabs vs spaces, trailing spaces) differs from what you assumed. (2) The old_string matches multiple locations in the file, causing an ambiguity error. (3) The surrounding context has changed since you last saw it (another edit modified nearby lines). (4) Line endings differ (CRLF vs LF). (5) The indentation level is wrong because you guessed the nesting depth. (6) Unicode characters or special characters in the file don't match your assumed content. This wastes time with failed edit attempts and can corrupt code if a partial match succeeds at the wrong location.

ALWAYS read the file before using Edit. This is non-negotiable. Follow this workflow:

1. READ first: Use the Read tool to see the actual file content. Pay attention to:

- Exact indentation (count the spaces/tabs)
- Surrounding code context
- Whether your target string is actually unique in the file
- File encoding and line endings

1. COPY exactly: When constructing old_string, copy the exact characters from the Read output. The line number prefix format in Read output is: [spaces][line number][tab][content]. Everything AFTER that tab is the actual file content.

1. INCLUDE CONTEXT: If your target string isn't unique, include more surrounding lines to make it unique. A 3-line match is almost always unique; a 1-line match often isn't.

1. VERIFY after: Read the file again after editing to confirm the change landed correctly, especially for critical modifications.

1. BATCH EDITS: When making multiple edits to the same file, read once, then apply edits from bottom to top (so line numbers don't shift between edits).

EXAMPLE of what goes wrong:
You think the line is: ' return result' (2 spaces)
The file actually has: ' return result' (4 spaces)
Edit fails with 'old_string not found'

PATTERN for safe editing:
Read file -> Identify exact content -> Edit with precise match -> Read again to verify

The Edit tool uses exact string matching on old_string. It searches the file for a literal byte-for-byte match. Unlike a human editor where you can see the file and click to position your cursor, programmatic editing is blind without reading first. One wrong character — a tab instead of spaces, a curly quote instead of straight quote, or a different indentation level — and the entire edit fails. Even worse, if old_string accidentally matches at the wrong location (e.g., a common pattern like 'return null;'), the edit succeeds but modifies the wrong code. Reading first eliminates these risks entirely.

Using AI code editing tools (Claude Code, Cursor, Copilot)