What Does Claude Need Before a Multi-File Edit?
In Claude Code, less than you might expect. It reads the repo itself, and Anthropic now lists describing your file layout in CLAUDE.md as advice to stop following. Give it what the repo can't show: what must not change, which pattern wins, and what done means. In the Claude app, you do have to supply the files.
I want to [change]. Before editing anything, find every place this touches: definitions, callers, types, tests, config and docs. Start from [search term or symbol]. Things you can't see from the code: - Don't touch: [paths, e.g. src/gen/, which is generated] - Still live, but don't copy its patterns: [paths] - Constraints: [e.g. old and new versions run side by side during rollout] - Done means: [commands that must pass] Give me the list of files with one line each, plus anything you're unsure about. Then wait.
- File layout and callers
- Types and tests
- Conventions in the code
- What must not change
- Which of two patterns wins
- Rollout and data constraints
- What done means
Try it now
- 1In Claude Code, press
Shift+Tabuntil the status bar shows⏸ plan mode on, then send the prompt. - 2Compare its list with what you expected. A file you didn't think of is the payoff, and a file you'd protected showing up is a warning.
- 3In the Claude app, click +, choose Add from GitHub, select the files involved, and add one line on how each relates to the others.
- 4It worked if the list includes callers you hadn't named and leaves out your protected paths.
Use it when
Renames, signature changes and moved concepts, or any edit that reaches past one file. It matters most where the repo misleads: generated code, a legacy folder that looks unused, or a rollout where old and new versions run side by side.
Skip it when
A local edit in one file. And don't write Claude a tour of the codebase in Claude Code. It will read the code anyway, and a long map you wrote by hand can go stale and contradict what's really there.
Why it works
Anthropic's docs say current models find your layout, conventions and tests by reading the code, and that a good test for anything you write down is whether Claude could find it and would actually look. A language server plugin improves this further by finding references by symbol rather than by text. What's left is what was never in the repo: a decision from a meeting, or a deploy process in one person's head. Keep the whole change in one session too. Anthropic's large-codebase guide says that keeps the decisions behind each edit consistent, rather than re-deriving them per package. The Claude app is different: Claude only sees what you add, and selected content must fit its context window.
Example
You're renaming User.email to User.contactEmail. Claude Code can find the model, the call sites and the tests. It can't know that mobile apps on old versions still send email for six months, so the API must accept both. That one sentence changes the whole plan, from a rename to a compatibility window, and only you could have supplied it.
Going further
In a large repo, control what loads. Start Claude from the package you're changing, and it loads that directory's CLAUDE.md plus every ancestor's. Add siblings with --add-dir ../shared. Block generated output with Read deny rules such as Read(./**/vendor/**/*). And since plan files survive compaction, per Anthropic's guide, plan before a long cross-package edit. A rule that must hold, such as never editing src/gen/, belongs in a PreToolUse hook. In a prompt or CLAUDE.md, it's still Claude's call.
Common mistakes
- Describing your architecture in
CLAUDE.md. Anthropic's docs say Claude reads the repo itself, and every line takes some attention on every task. - Using
@on many files to be helpful. The help center says that pulls in each whole file plus itsCLAUDE.mdtree, while a bare path lets Claude read selectively. - Pasting one file into the Claude app, then wondering why the callers still break. Claude can't see files you didn't add.
- Stating a hard rule only in the prompt. If it has no exceptions, enforce it with a hook or deny rule.
Sources
- Best practices for Claude Code
- Set up Claude Code in a monorepo or large codebase
- Code intelligence plugins, Claude Code Docs
- Using the GitHub integration, Claude Help Center
- Models, usage, and limits in Claude Code, Claude Help Center
Checked 6 November 2026. Products change often, so confirm details with the vendor.