Skip to main content

Multi-File Operations

Real projects consist of dozens to thousands of files. Unlike single-file work, multi-file work requires you to manage inter-file dependencies, context efficiency, and order of operations.

How Claude Code understands filesโ€‹

When Claude Code receives a task, it first explores the relevant files:

  1. Map the directory structure โ€” understand the overall layout with ls, find, etc.
  2. Identify relevant files โ€” find the files related to the request
  3. Trace dependencies โ€” follow import/require relationships to discover connected files
  4. Plan the changes โ€” decide which files to modify and in what order

This happens automatically, so you don't need to point out every relevant file yourself.

How to request multi-file workโ€‹

Request by featureโ€‹

> Add user authentication.
  Include login, sign-up, and logout.
  Use the existing User model.

Claude Code figures out on its own:

  • Which files to create
  • Which files need modification (routers, middleware, etc.)
  • What order to work in

Specify the scope explicitlyโ€‹

> Implement JWT authentication centered on the src/auth/ directory.
  Don't touch the existing src/users/ code โ€”
  only add middleware to src/middleware/.

Making the "do not touch" list explicit reduces mistakes.

Proceed step by stepโ€‹

Changing too many files at once makes review difficult:

> Step 1: define the types only for now (types/auth.ts)
  [review]
> Step 2: implement the service layer (services/auth.ts)
  [review]
> Step 3: wire up the API routes (routes/auth.ts)

File reference patternsโ€‹

Reference specific files explicitlyโ€‹

> Based on src/services/payment.ts and src/types/payment.ts,
  add a refund service

Reference by directoryโ€‹

> Add dark mode support to every component
  in src/components/ui/
> Find every file related to UserService
  and refactor the name to AccountService

Large-scale refactoringโ€‹

Refactoring across many files is one of Claude Code's strengths.

Renamingโ€‹

> Rename "userId" to "accountId" across the whole project.
  Include the DB schema, types, and API responses.
  But don't touch files that talk to external APIs.

Applying pattern consistencyโ€‹

> Unify every route handler in the src/api/ directory
  to match the current auth.ts style.
  (try-catch, error format, response structure)

Swapping dependenciesโ€‹

> Replace axios with the fetch API.
  Update every affected file,
  and remove the axios package.

Snapshot before you start: an essential habitโ€‹

Before any multi-file work, always make a git commit first:

git add . && git commit -m "chore: snapshot before refactoring"
claude
--dangerously-skip-permissions

The --dangerously-skip-permissions flag skips all permission checks, so use it only in isolated environments (Docker/VM). On a regular local machine, the default mode or Auto-accept mode via Shift+Tab is the safe choice.

If something goes wrong, you can recover immediately:

git checkout .          # discard all changes
git reset HEAD~1        # undo the last commit

Real-world pattern: feature addition workflowโ€‹

Example: adding a new resource to a REST APIโ€‹

> Add a Product CRUD API.
  Follow the existing User API pattern (src/api/users/)
  and use the same structure.

Claude: I will create/modify the following files:
  Create:
  - src/types/product.ts
  - src/models/Product.ts
  - src/services/product.service.ts
  - src/api/products/index.ts
  - tests/product.test.ts

  Modify:
  - src/api/index.ts (register the router)
  - prisma/schema.prisma (add the Product model)

  Shall I proceed?

When Claude Code shows its plan up front, always review it. If it includes files you don't want changed, ask for a revision.

Example: adding a field to an existing featureโ€‹

> Add a phoneNumber field to the User model.
  Update the DB, types, API, and tests.

Claude: Affected files:
  - prisma/schema.prisma (add the field)
  - src/types/user.ts (update the type)
  - src/api/users/register.ts (handle the request)
  - src/api/users/profile.ts (include in the response)
  - tests/user.test.ts (add test cases)
  - generate a migration file

Preventing cross-file conflictsโ€‹

Declare files "read-only"โ€‹

> Implement src/auth/.
  Never touch the files in src/config/ โ€”
  those settings must not change.

Check the impact scope firstโ€‹

> Before actually making changes,
  first tell me which files this change would affect.

When Claude Code shows the change plan first, you can check whether any unexpected files are included.

Multi-file work with testsโ€‹

Good multi-file work always includes tests:

> Implement the Product service.
  Create the implementation file and the test file together.
  TDD style: tests first, implementation after.
> Run the tests for all the files you just created.
  If any tests fail, fix them right away.

Together with documentationโ€‹

> For the Payment module you just implemented:
  1. Add JSDoc comments to each function
  2. Write src/docs/payment-api.md (API spec)
  3. Add a payments section to README.md

Multi-file work checklistโ€‹

Before starting a large task:

  • Secure a snapshot with a git commit
  • List forbidden files/directories in CLAUDE.md
  • Break the work into small, planned steps
  • Run the build/tests after the first change
  • Commit to git at each step as you go
Last updated on