Single-file edits with Claude Code are straightforward. Multi-file changes — where you're updating an API, the types it depends on, the tests, and the client code that calls it — require more structure to get consistent results.
Start with a file map
Before asking for changes, give Claude a map of what's relevant:
I need to change [thing]. Here are the files involved:
- types/user.ts — User type definition
- api/users.ts — API handler
- hooks/useUser.ts — React hook that calls the API
- components/UserProfile.tsx — Component that uses the hook
Plan the changes across all four files before touching any of them.The "plan before touching" instruction is important. When Claude jumps straight to implementation, it sometimes makes incompatible changes across files because it doesn't hold the full picture in mind at once.
Sequence matters
For type-driven changes, work from the inside out: types first, then the code that implements them, then the code that calls them. Tell Claude the order explicitly:
Make these changes in this order:
1. Update the type in types/user.ts
2. Update the API handler to match
3. Update the hook
4. Update the component
Check types at each step before moving to the next.This catches type mismatches file by file instead of all at once at the end.
The consistency check
After multi-file changes, I run:
Check all the files we changed. Are the interfaces consistent?
Specifically:
- Does the API return what the hook expects?
- Does the hook return what the component expects?
- Are error cases handled the same way at each layer?Claude catches real inconsistencies with this prompt. The answer is sometimes "actually, the error handling is different in the hook vs the component" — something that would have caused a subtle bug in production.
Naming consistency
Naming drift is a common multi-file problem. An API returns userId, the hook calls it user_id, the component uses id. Works fine until someone changes one.
Review these files for naming consistency. Look for the same concept
referred to by different names across files. List any inconsistencies
you find without fixing them yet.List-then-fix prevents Claude from quietly renaming things in ways that break other files you haven't read yet.
When changes are larger than one session
For refactors that span more than one Claude session, keep a change log file:
## Refactor log
Goal: [what we're doing]
Completed:
- [x] types/user.ts — updated User type
- [x] api/users.ts — updated handler
In progress:
- [ ] hooks/useUser.ts
Not started:
- [ ] components/UserProfile.tsx
- [ ] tests/users.test.tsAt the start of each session: "Read refactor-log.md and continue from where we left off." Claude will pick up the correct state instead of starting over or duplicating work.
Test impact analysis
Before any multi-file change:
Which tests will this change affect? List them.
Don't run them yet — just identify which ones might fail
and why.This gives you a checklist for what to verify after the changes are done. If Claude predicts tests A, B, C will be affected and tests D and E also break, something unexpected happened and needs attention.
More prompts for managing complex, multi-file work are in the Agent Prompt Playbook. Includes templates for refactor tracking, consistency checks, and cross-file review. $29.