headroom.walls.sh · multifile

Claude Code Multi-File Editing

Claude Code reads and edits files one at a time internally, but it works across your whole project in a single session — reading context from dozens of files before editing, then updating each one. This is what makes it useful for real codebases rather than isolated snippets. Here is how to use it well.

How multi-file editing works

When you ask Claude Code to work across multiple files, it:

1. Reads all relevant files to understand context (imports, types, function signatures, call sites)
2. Plans the change — which files need edits and in what order
3. Edits each file sequentially, with each edit informed by everything it read
4. Verifies the result (runs tests, type checker, or build) if you ask it to

The key constraint: Claude Code works within a context window. It can hold many files at once, but on very large projects (hundreds of files), it may need to read in batches or work across sub-directories. For most projects, it handles the full scope in one pass.

Directory-scope tasks

The simplest multi-file pattern: scope the task to a directory.

claude "add JSDoc comments to every exported function in src/utils/ — read all files first, then update them"

claude "find all console.log() calls in src/ and replace them with a logger.debug() call using the project's logger from src/lib/logger.ts"

claude "add input validation to every POST endpoint in src/routes/ — read the route files first to see the existing patterns, then add validation using the same style"

The "read all files first" instruction helps when context from one file affects how another should be written. Without it, Claude Code may start editing before reading everything it needs.

Cross-file refactors

Renaming a function, type, or variable that's used across many files:

claude "rename the function processPayment to handleTransaction everywhere it appears — update the definition in src/payments.ts and all call sites. Run the tests after."

claude "the User type is defined in src/types/user.ts. Move it to src/models/User.ts, update the import path in every file that imports it."

claude "we renamed the API endpoint from /api/v1/users to /api/v2/users. Find every place in the codebase that calls this endpoint and update the path."

Claude Code reads the definition file first, then finds and updates all callers. It handles relative imports correctly — a file in src/routes/ and one in src/services/ get different relative paths to the same module.

Moving code between files

Extracting a function or module to a new file:

claude "the auth logic in src/server.ts has grown too large. Extract the authentication middleware into src/middleware/auth.ts, update the import in server.ts, and verify the app still builds."

claude "split src/utils.ts into separate files by category: src/utils/string.ts, src/utils/date.ts, and src/utils/api.ts. Update all imports across the project."

Moving code is more error-prone than renaming because import paths change and barrel files may need updating. Claude Code handles this well when you include "update all imports" and "verify the build" — the verification step catches any import it missed.

Coordinated changes across layers

The most powerful multi-file use: changes that span multiple layers of a codebase.

claude "add a 'lastModifiedBy' field to the User model. Update: the database migration, the TypeScript type, the API serializer, the admin panel display, and the tests. Do them in dependency order."

claude "the getUsers API now returns a pagination cursor instead of a page number. Update the backend endpoint, the TypeScript response type, the frontend fetch function, and the UI component that renders the result."

The "dependency order" and "do them in order" instruction helps Claude Code update the schema before the type that depends on it, and the type before the code that uses it — avoiding intermediate states where the project doesn't compile.

Using @file references

You can explicitly tell Claude Code which files to read before starting:

claude "@src/types/api.ts @src/services/userService.ts add error handling to every function in userService.ts that calls the API — use the error types defined in api.ts"

@ references load those files immediately into context at the start of the task. This is useful when you know exactly which files are relevant and want to avoid Claude Code spending reads discovering them.

Large projects: scoping strategies

For very large codebases (hundreds of files), scope the task deliberately:

• By directory — src/api/ not src/
• By module — "just the auth module" not "the whole app"
• By type of change — "only files that import from lib/db" not "all files"
• Incrementally — do one module per session, commit between sessions

Claude Code will tell you if it can't hold all the relevant files in context — it won't silently skip files it hasn't read.

Verify the result explicitly

Always end multi-file tasks with a verification step:

claude "rename calculateTax to computeTax everywhere — update definition and all callers. Run npm test after to verify nothing broke."

Without the verification step, a missed call site or wrong import path stays hidden until you push or someone else runs the tests. The explicit "run tests" instruction makes Claude Code responsible for confirming the change is consistent — not just complete.

→ Refactoring with Claude Code
→ Claude Code for TypeScript
→ Writing tests with Claude Code
→ 5-hour session limit explained