Give Claude the Map Before a Multi-File Edit

Before asking Claude to change something that spans files, giving it a short map — which files are involved, how they relate, and where the edit should and shouldn't reach.

Without the map, Claude changes the file in front of it and misses the three callers, the type definition, and the test. Naming the affected surface up front is the difference between a coherent change and a half-applied one.

Renames, signature changes, moving a concept, or any edit whose blast radius crosses more than one file.

Truly local edits inside a single file, where a map is just overhead.

I want to <change>. It touches multiple files. Here's the map:

- <file A>: <role>
- <file B>: <role, how it depends on A>
- Tests: <where>

Propose the full set of edits across all of them as one coherent change, and call out anything I forgot to list. Don't start until the plan looks complete.

Renaming User.email to User.contactEmail, Claude — handed the map — updates the model, three call sites, the migration, and the tests in one pass, and flags a serializer you hadn't mentioned.

Ask Claude to produce the change as an ordered sequence (types first, then callers, then tests) so you can apply and verify it in a safe order rather than all at once. Pairs naturally with Claude Code for real repos.

• Pasting one file and being surprised the callers still break.
• Letting Claude guess the repository structure instead of telling it.
• Applying a sprawling multi-file diff without an order, so a half-applied state won't compile.