Multi-File Workflows

You need to rename a field that’s threaded through a dozen files — the model, the service, three controllers, the migration, the API contract, and a wall of tests. Do it by hand and you’ll miss two callers and ship a 500. This is exactly the kind of change Claude Code is built for: it traces the dependency graph, edits every file consistently, and updates the tests in the same pass. The trick is knowing how to drive it so it stays accurate across the whole blast radius.

What You’ll Walk Away With

• A plan-first prompt that forces Claude to map the blast radius before it touches a single file
• A repeatable pattern for safe, backward-compatible field and API renames
• Copy-paste prompts for cross-cutting refactors (extract shared logic, type propagation, dependency tracing)
• The real way to run independent multi-file tasks in parallel using git worktrees
• A recovery playbook for when a multi-file edit goes wrong mid-flight

Plan Before You Touch Code

The single biggest accuracy win on multi-file changes is to separate planning from editing. Run Claude in plan mode first (claude --permission-mode plan, or press Shift+Tab to toggle into it), let it explore and propose, then approve before any file is written.

1. Ask for the change plan, not the change. Claude explores the codebase and reports what it intends to touch — without editing.

2. Review the blast radius. You’ll catch missing files or wrong assumptions here, where they’re free to fix, instead of in a diff of 40 files.

3. Refine, then approve. Add anything it missed, then let it execute the approved plan one layer at a time.

Tip

Copy-paste prompt for a plan-first multi-file change:

We need to add user roles to the app. Before changing anything, produce a plan:
- list every file you'll modify, grouped by layer (DB migration, models, middleware, API routes, UI, tests)
- name the new tables/columns and the role-check seam
- call out anything that could break existing callers
Do NOT edit any files yet. Wait for my approval.

Plan mode is read-only by design, so this is safe to run even on main. When the plan looks right, approve it and Claude switches to execution.

Trace the Dependency Graph First

Before a rename or schema change, make Claude surface everything that depends on the thing you’re about to move. This is faster and more reliable than grep because it follows imports and types, not just text.

Tip

Copy-paste prompt for mapping impact before a schema change:

What files will break if I change the `User` model schema to add a `roles: string[]`
field? Trace importers, type usages, serializers, and tests. Return a grouped checklist
of files with a one-line reason each. Don't edit anything yet.

Use the returned checklist as the contract for the edit pass. If Claude later edits a file that wasn’t on the list, that’s your signal to pause and re-check the plan.

Safe Renames Across the Codebase

A rename looks trivial until it’s a public field that external clients depend on. The pattern that survives production is additive-then-deprecate, not rip-and-replace.

1. Add the new name alongside the old. Keep both working so nothing breaks on deploy.

2. Migrate internal callers to the new name while the API still accepts the old one.

3. Deprecate the old name with a warning so you can see remaining usage.

4. Remove the old name once telemetry confirms no active callers.

Tip

Copy-paste prompt for a backward-compatible rename:

Rename `customerId` to `clientId` across the codebase, but keep backward compatibility:
- add `clientId` everywhere the value is produced
- have the API still ACCEPT `customerId` on input and map it to `clientId`
- update models, serializers, and tests to use `clientId`
- add a deprecation log line wherever inbound `customerId` is still received
Show me the file list you'll change before editing.

For typed languages, lean on Claude’s ability to propagate types instead of chasing compiler errors by hand:

Tip

Copy-paste prompt for TypeScript type propagation:

Add a `roles: Role[]` field to the `User` interface. Then find every file that imports
`User`, update function signatures and call sites, and fix the resulting type errors.
Run the type-checker when you're done and fix anything that's still red.

Cross-Cutting Refactors

When logic is duplicated across controllers or services, ask Claude to consolidate it while preserving the existing public interfaces — the consolidation should be invisible to callers.

Extract shared logic

Extract the validation logic duplicated in UserController, OrderController, and
ProductController into a single ValidationService. Keep each controller's existing
method signatures unchanged. Add unit tests for the extracted service.

Standardize error handling

Standardize error handling across the API: introduce a small set of typed error
classes, route them through one error-handling middleware, and replace ad-hoc
try/catch + res.status(...) blocks with throws. Keep response shapes identical so
clients don't break. Update affected tests.

Thread a request ID

Add a request-id that's generated per request and included in every structured log
line for that request. Wire it through the logger and the error handler. Don't log
PII. Show me the middleware and one updated handler before doing the rest.

When a refactor touches an MCP-connected system — for example renaming a column that exists in your actual database — connecting the Postgres MCP server lets Claude read the live schema instead of guessing from migrations. See the refactoring patterns lesson for that workflow.

Work One Layer at a Time

For large changes, drive Claude through the stack in order rather than asking for everything at once. Narrow, sequential prompts keep context focused and make each diff reviewable.

1. "List every file that needs to change for user roles, grouped by layer."
2. "Implement the database migration and model changes only."
3. "Now the role-check middleware and the protected routes."
4. "Now the role-management UI."
5. "Now update and run the tests."

Between unrelated phases, run /clear to drop stale context, or /compact Focus on the role-check seam and the files we've already changed to summarize while keeping what matters. Use /context to see what’s actually consuming the window, and /cost to watch spend. These are real interactive slash commands — run them inside the claude REPL, not as terminal flags.

Running Independent Tasks in Parallel

If you have several genuinely independent streams of work — a new auth system, a payments rewrite, an analytics pass — run each in its own git worktree so they get isolated working directories and branches. This is the documented way to parallelize, and it keeps each task’s context clean.

# One worktree (and branch) per stream of work
git worktree add ../feature-auth feature/authentication
git worktree add ../feature-payments feature/payments
git worktree add ../feature-analytics feature/analytics

# Launch Claude Code in each worktree (separate terminals or tmux panes)
tmux new-session -d -s auth     'cd ../feature-auth && claude'
tmux new-session -d -s payments 'cd ../feature-payments && claude'
tmux new-session -d -s analytics 'cd ../feature-analytics && claude'

Each session is its own conversation against its own checkout, so the edits never collide. When you’re done with a tree, git worktree remove ../feature-auth.

Choose the right parallelism mechanism:

Mechanism	Best for
Git worktrees + one claude per tree	Independent tasks on separate branches that must not touch each other’s files.
Subagents	Specialized helpers inside one session (clean sub-context, fast handoffs) — launch with the --agents flag or define them in .claude/agents/.
Agent teams	Multiple agents that coordinate and message each other; set --teammate-mode and enable with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.

If you instead need Claude to read across several directories in a single session (a monorepo app plus a shared lib), don’t use worktrees — add the directories with --add-dir:

claude --add-dir ../apps ../lib "Update the shared logger and every app that imports it"

Coordinating Changes Across Repositories

Claude works one repository at a time, so cross-repo changes are sequential. Drive the producer first, then each consumer, and pin the contract in each repo’s CLAUDE.md so future sessions know what changed.

API contract change

cd api-service
claude "Update the /users endpoint to return clientId instead of customerId,
but keep accepting customerId on input for one release."

cd ../frontend-app
claude "The /users API now returns clientId (customerId is deprecated).
Update all calls and data handling to read clientId."

cd ../mobile-app
claude "Update to read clientId from the /users API, keeping a fallback to
customerId so older app builds keep working."

Shared library bump

cd shared-utils
claude "Add validateEmail and validatePhone helpers, exported from the package root."

for service in user-service order-service notification-service; do
  cd "../$service"
  claude "Bump shared-utils to the version that adds validateEmail/validatePhone
  and replace local validation with those helpers."
done

Record the migration in each repo so the next session has the context:

<!-- in each repo's CLAUDE.md -->
## Recent migrations
- clientId replaces customerId in /users responses; customerId still accepted on input until v3.

When This Breaks

Multi-file edits fail in predictable ways. Here’s how to catch and recover from each.

Caution

• It edits a file that wasn’t in the plan. Stop and re-run the dependency trace — the plan was incomplete, and unplanned edits are where regressions hide.
• Missing imports or broken types after a rename. Run your linter and type-checker, then paste the errors back: “Fix these type errors from the rename, don’t change behavior.”
• Inconsistent naming because the change spanned several prompts. Ask: “Verify no references to customerId remain anywhere, including comments and tests.”
• Context drift on long sessions. If answers get vague or it forgets earlier decisions, /compact with focus instructions or /clear and re-anchor with the plan checklist.
• Forgotten edge cases. Before you commit, ask Claude to enumerate them: “List the edge cases this change might have missed and check each one.”

When an edit pass goes wrong, git is your undo:

git status                       # see everything that changed
git diff                         # review before trusting anything
git checkout -- path/to/file.ts  # revert a single file
git reset --hard HEAD            # nuke all uncommitted changes and start over

For a partial recovery — keep the good, drop the broken — describe it precisely:

Tip

Copy-paste prompt for surgical recovery:

The refactor broke the payment flow but the logging changes are fine. Revert only the
payment-related edits to match origin/main, keep everything else, then explain what
the payment change got wrong so we don't repeat it.

Commit in logical phases as you go (after the migration, after the middleware, after the UI). Small, frequent commits turn “the whole change is broken” into “the last commit is broken.”

What’s Next

• Refactoring Patterns — deeper rename, extract, and restructure recipes
• Debugging Workflows — when a multi-file change introduces a bug
• Custom Subagents — specialized helpers for large changes inside one session
• Cost Control — keep large multi-file sessions cheap