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/

Let it discover related files

> 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