Working across files
Claude in VS Code: Pair Programming
Chapter 7 · Working Across Files — Project-Wide Changes and Architecture
Previous chapters focused on single files or functions. Real work rarely stays that contained — a feature touches multiple modules, a rename ripples across the project, an architecture question requires reading a dozen files before you can answer it. This chapter covers how Claude's cross-file awareness works, how to make project-wide changes safely, and how to ask architectural questions that produce useful answers.
How Claude's Cross-File Awareness Actually Works
Claude doesn't automatically read your entire project into memory. It reads files on demand — either because you have them open, because you reference them explicitly, or because Claude decides it needs to read them to answer your question. Understanding this model prevents both over-reliance and under-utilisation.
Auto
Currently open files — always in context. Claude reads the active editor tab and any other open tabs automatically. The more relevant files you have open, the better Claude's cross-file answers will be.
Action: open the files relevant to your task before starting a cross-file conversation.
On demand
Files Claude reads when needed — when you ask a question that requires a specific file, Claude reads it. It can also proactively read files it identifies as relevant from imports or references in code you've shown it.
Action: name the file explicitly if Claude needs something you haven't opened — "see how this is done in services/auth.py".
Limited
Project-wide search — Claude can search across the project using Grep and Glob, but this is bounded by what the search returns. A search for a function name finds all references; it doesn't read every file in the project.
Action: for broad questions, ask Claude to search first and tell you what it found before drawing conclusions.
Not available
Runtime state, git history, external systems — Claude reads static files. It cannot see what's currently running, what values exist in the database, or what changed between commits.
Action: provide this context manually when it's relevant — paste the relevant git diff, the DB query result, or the runtime log.
Cross-File Prompt Patterns
Dependency trace
Which files in this project import or depend on `UserService`? I'm planning to rename it and need to know the full blast radius.
Claude searches the project and returns the list. Verify with Ctrl+Shift+F as a second source of truth.
Data flow across modules
Trace what happens to `order.total` from the moment it's calculated in order_service.py to when it's stored. What files touch it along the way?
Open the entry and exit files before asking. Claude follows the data through imports and function calls.
Consistency check
I've added a new field `cancelled_at` to the Order model. What other files might need updating — serialisers, schemas, tests, migrations?
Claude reads the model and scans the project for related patterns. Works best after you've made the model change so Claude can see it.
Pattern survey
How does this project handle authentication across different endpoints? Look at a few route files and tell me if the pattern is consistent.
Useful for onboarding and for spotting divergence before it becomes a security problem.
Dead code detection
Is `LegacyPaymentAdapter` referenced anywhere other than its own file? I want to delete it if nothing uses it.
Combine with a manual search. Claude's answer is a strong indicator but may miss dynamic references (e.g. string-based imports).
Interface alignment
The `process()` method on `OrderService` changed its return type. Show me every place it's called and whether the caller handles the old or new return value.
Open both the service and the key callers first. Claude checks each call site and flags mismatches.
Making a Project-Wide Change Safely
State the change and ask for a plan first. "I want to change the `User.username` field to `User.handle` everywhere in the project. Before we start, list every file and type of change that will be needed." Claude produces a change plan you can review.
Cross-check Claude's list with a project search. Use
Ctrl+Shift+F to search for username. Compare against Claude's list — any file Claude missed needs to be added to the plan.Start with the definition, not the callers. Make the change at the source (the model or interface) first. This makes the compiler or type checker flag all the broken callers immediately, giving you a definitive list.
Work file by file, reviewing each diff. Ask Claude to update one file at a time. Read the diff before accepting. Batch changes across files make it hard to isolate the source of a newly introduced bug.
Run the test suite after each file. A test failure immediately after updating a specific file tells you exactly where the problem is. Waiting until all files are done makes attribution much harder.
Do a final search sweep. After all changes are accepted, search the project for the old name one more time. Any remaining hits that aren't comments or string literals are missed updates.
Dynamic references slip through
Claude and Ctrl+Shift+F both find static references. If your codebase uses dynamic dispatch, string-based imports (importlib, require(variableName)), or config-driven class loading, those references won't appear in a text search. Flag these areas explicitly when planning a rename.
Asking Architecture Questions
Claude can answer questions about how your system is designed — not just what individual functions do. These questions require reading multiple files and synthesising an answer, which Claude handles well as long as you give it the right starting points.
"Where should I add the new notification logic — in the service layer or the controller?"
Opens a discussion about your existing layering. Claude reads the service and controller pattern, then makes a recommendation consistent with what's already there.
"Is there a single place where all external API calls are made, or are they scattered across the codebase?"
Claude surveys import patterns and call sites. Useful before deciding whether to centralise HTTP logic.
"What would break if I removed the caching layer from the user lookup?"
Claude traces what depends on the cached value. Gives you the blast radius before you experiment.
"Does this project follow a consistent error handling strategy, or are there different approaches in different modules?"
Claude reads several modules and compares patterns. Surfaces inconsistency before it becomes a maintenance burden.
"I need to add rate limiting. Where in the existing request pipeline should it go?"
Claude reads the middleware stack and routing, then suggests an insertion point consistent with existing middleware.
"How tightly coupled is the payment module to the order module? Could they be separated?"
Claude examines imports and shared types between the modules. Gives you a coupling assessment before a refactor decision.
Ground architecture questions in concrete decisions
Vague architecture questions ("is this codebase well-structured?") produce vague answers. Anchor every architecture question to a concrete decision you're facing ("I need to add X — where should it go and why?"). Claude gives more useful answers when the question has a practical outcome.
The Limits of Cross-File Understanding
| Limitation | Why it happens | Workaround |
|---|---|---|
| Large projects exceed context | A project with hundreds of files can't all be read into context simultaneously. Claude reads what it can and may miss relevant files. | Open the most relevant files manually before asking. Name the files Claude should read explicitly. |
| Generated or compiled code | Auto-generated files (protobuf outputs, ORM migrations, bundled JS) are readable but rarely useful for architecture questions. | Direct Claude to the source definitions, not the generated outputs. |
| Implicit conventions | If a pattern exists in your codebase but isn't written down and the example files aren't open, Claude won't know about it. | Open a representative example or describe the convention before asking Claude to follow it. |
| Runtime vs static divergence | What the code says and what actually runs can differ (feature flags, environment config, monkey-patching). Claude only sees the static code. | Provide runtime context manually: "in production, this flag is always false" or paste the relevant config values. |