Claude Code in a monorepo or large codebase: keep it focused

Claude Code works at any size, but in a repository with many packages the defaults tuned for small projects can fill the context window with instructions and file reads that have nothing to do with the task. That costs tokens and can make answers worse. The fix is to scope Claude to the part of the code you are touching. These are the settings that do it, in the order most people need them.

1. Choose where to start Claude

Where you run claude decides what it can read and edit without a further permission grant, which CLAUDE.md files load at launch and which project settings apply.

• From the repository root: every file is reachable, only the root CLAUDE.md loads at launch, and subdirectory ones load on demand. Good when a task spans packages.
• From a subdirectory: only that subtree is reachable until you grant more, and that directory's CLAUDE.md plus every parent's load. Good when the work lives in one package.

One trap, as we read the docs: .claude/settings.json is not inherited from parent directories the way CLAUDE.md files are. If you start from packages/api/, that package's own .claude/ is the one that counts. See which settings file wins.

2. Layer CLAUDE.md files by directory

One giant root file either grows to cover every subsystem, wasting context on things unrelated to today's task, or stays too vague to help. Split it in two levels instead:

• Root CLAUDE.md: rules that apply everywhere, such as coding standards and commit conventions.
• A CLAUDE.md in each package or subsystem: the conventions of that stack, for example “copy .env.example to .env before running anything” or “never edit a migration after it has merged”.

Start Claude in packages/api/ and it loads that file plus the root one, with nothing from packages/web/. To check what actually loaded, run /context and look at the memory files list. Commit these files so teammates inherit them, and let each directory's owner maintain theirs.

The alternative is path-scoped rules in a central .claude/rules/ folder, which load when Claude touches a file matching a paths: pattern. Per-directory files keep conventions next to the code; rules keep everything in one place. More on choosing in CLAUDE.md vs skill vs hook and memory.

3. Exclude the CLAUDE.md files you never need

Started from the root, Claude can load any subdirectory's CLAUDE.md on demand. The claudeMdExcludes setting skips files by glob so they never load, which suits other teams' packages, legacy code and vendored trees. Patterns match absolute paths, so start relative-looking ones with **/:

{
  "claudeMdExcludes": [
    "**/packages/web/**"
  ]
}

Put it in .claude/settings.local.json if it is only for you. The list is static, not a per-task switch: to focus on a different package tomorrow, start Claude from that package instead of editing exclusions.

4. Stop it reading generated and vendored code

Content searches respect .gitignore, so node_modules/, dist/ and build/ are already out of the way if they are ignored. Things that are checked in, such as a vendored SDK or committed generated code, need Read deny rules:

{
  "permissions": {
    "deny": [
      "Read(./**/dist/**/*)",
      "Read(./**/*.generated.*)",
      "Read(./**/vendor/**/*)"
    ]
  }
}

• Directory patterns end in /**/* so the contents are blocked but Claude can still list or enter the directory.
• Commit the rules to .claude/settings.json for everyone, or use .claude/settings.local.json for yourself. Relative patterns anchor at the directory you start in, so if you start from subdirectories, write personal rules as //-absolute paths.
• Deny rules cover Claude's file tools and the file commands it recognizes in Bash, like cat and grep with a denied path as an argument. They do not cover subprocesses that open files themselves, and a broad grep -r over a directory can still surface denied files. Treat them as a strong guard rail, not a vault. For the syntax, see the permissions starter.

5. Let a language server find definitions

In a big tree, finding where a symbol is defined or used can cost many file reads. Code intelligence plugins connect Claude to a language server so it can jump to definitions and references and see type errors directly. The official marketplace has plugins for TypeScript, Python, Go, Rust and others, and each needs that language's server binary on your machine. How plugins install is in installing plugins. To enable one for the whole team, add it to the project's enabledPlugins setting.

6. Smaller worktrees, wider access

• Sparse worktrees. claude --worktree starts a session in a new git worktree, which by default checks out the whole repository. The worktree.sparsePaths setting lists the directories to write to disk, plus root-level files, so worktrees start faster and use less space. Background in worktrees and parallel sessions.
• Sibling packages. Started from packages/api/, Claude can only touch that directory. For a change that also needs packages/shared/, use --add-dir or put "permissions": { "additionalDirectories": ["../shared", "../web"] } in that package's settings. Relative paths resolve from where you start Claude. The same works for a second repository.

7. Changes that span packages

• Give Claude the whole change in one session, the shared edit and its call sites together, so the decisions behind each edit stay consistent.
• Plan first in plan mode. Claude writes the plan to a file, and Claude Code re-injects that file after each compaction, so the plan survives even when the conversation history does not. See what survives a compact.

Keep it from rotting

• Review CLAUDE.md changes in pull requests like any documentation.
• Revisit after major model releases: a rule that worked around an old limitation can become pure overhead.
• Run /doctor on a CLAUDE.md that has grown too big.

All the guides are in the guides index, and the token side of this is in reducing token usage. This follows Anthropic's large-codebase documentation as we read it in October 2026, shortened on purpose. We are not affiliated with Anthropic. We wrote this from the documentation and have not tested every repository layout. Setting names and behavior can change, and where this page and the documentation disagree, the documentation wins.

The free loop-stop skill gives long tasks a limit and a stop rule. If you want a second pair of eyes on your CLAUDE.md and settings, the Tune-Up Kit is a checklist for exactly that.