Claude Code Working with Multiple Files

Real projects are never one file. They are collections of files that share data, call each other's functions, and depend on each other to work. Claude Code handles multi-file work naturally — you describe a task involving several files and Claude Code reads, edits, and links them all in a single conversation.

Why Multiple Files Matter

When developers split code across files, they do it to keep things organised. A shopping app might have one file for user accounts, one for products, one for the cart, and one for payments. These files are separate but connected.

Changes in one file often require matching changes in others. Claude Code tracks those connections so you do not have to.

How Claude Code Views Your Project Structure

Before diving into multi-file work, get a map of your project:

"List all files in this project and show how they relate to each other — which ones import from which."

Claude Code scans the directory and draws a dependency map in text form.

Example Project Map

app.py
  ├── imports from: database.py, auth.py, utils.py
database.py
  ├── imports from: config.py
auth.py
  ├── imports from: database.py, utils.py
utils.py
  └── imports from: (nothing — standalone)
config.py
  └── imports from: (nothing — standalone)

This map tells you which files are foundational (config.py, utils.py) and which ones depend on others (app.py). Changes to foundational files ripple outward — Claude Code flags this automatically.

Reading Multiple Files in One Prompt

"Read both models.py and views.py and explain how the User model is used in the views."
"Read the three files in the /services folder and tell me what each service does."
"Look at main.py, config.py, and helpers.py together and explain the overall application startup flow."

Claude Code reads all named files and synthesizes the answer across them — you do not need to read them separately and piece it together yourself.

Making Changes Across Multiple Files

Renaming a Function Used in Many Files

"Rename the function send_notification to push_alert in notifications.py and update every file that calls send_notification."

Claude Code finds all callers, shows you all planned changes across every file, and waits for your approval before touching anything.

Adding a Parameter to a Function

"Add an optional parameter called timeout (default 30) to the fetch_data function in api_client.py. Update all callers in the project to pass their current timeout values if they have them."

Moving Code Between Files

"Move the three validation functions from app.py into a new file called validators.py, and update app.py to import them from validators.py."

Claude Code creates the new file, moves the code, and fixes the imports — three changes handled as one coordinated action.

Diagram: A Multi-File Change in Action

Picture a web of offices. One office (database.py) stores all the customer records. Three other offices (orders.py, invoices.py, reports.py) all call database.py to get customer data. You decide to rename the function get_customer to fetch_customer in database.py.

database.py            orders.py
get_customer()  --->  calls get_customer()   (needs update)
                       
                       invoices.py
                  --->  calls get_customer()  (needs update)
                       
                       reports.py
                  --->  calls get_customer()  (needs update)

Without Claude Code, you update four files manually and risk missing one. With Claude Code, one prompt handles all four files simultaneously.

Finding Where Something Is Used Across Files

"Which files use the MAX_RETRIES constant defined in config.py?"
"Find every place in the project where the User class is instantiated."
"List all files that connect to the database directly."

These search prompts work across the entire project folder, not just one file.

Working with a Feature That Spans Files

Some features touch many files at once. Describe the feature and let Claude Code trace it:

"Trace the login feature from start to finish. Show me every file involved, starting from when a user submits their credentials to when they get a session token."

Claude Code follows the data flow across files and gives you a step-by-step trace of the feature.

Adding a New Feature Across Multiple Files

"I need to add a feature that logs every time a user deletes an item. The deletion happens in items.py. Add the logging call there and create a new file called audit_log.py that handles writing the log entries."

Claude Code creates the new file and edits the existing one as part of a single coordinated change.

Handling Import Errors Between Files

Import errors are common when files do not correctly reference each other. Claude Code diagnoses these quickly:

"I get ImportError: cannot import name 'process_order' from 'orders.py'. Read both main.py and orders.py and tell me what is wrong."

Claude Code checks the export in orders.py and the import statement in main.py, finds the mismatch, and fixes both.

Keeping Files Consistent

As projects grow, files drift out of sync — one file uses a different naming convention than another, or two files define the same utility function separately. Ask Claude Code to audit this:

"Read all the files in /utils and tell me if any functions are duplicated or if there are inconsistent naming styles."
"Check whether the error handling pattern in api.py matches the pattern used in the other service files."

Key Points

  • Claude Code reads multiple files simultaneously and synthesizes answers across them.
  • Multi-file changes — renames, moves, additions — are handled as one coordinated action.
  • Always start a multi-file session with a project map prompt to understand file dependencies.
  • Claude Code finds all callers and importers before making a change that affects many files.
  • One approval covers all related changes in a multi-file operation.
  • Use Claude Code to audit consistency and find duplicated code across your project.
Previous lessons
Back to courses
Next lessons

Leave a Comment