Skip to main content
A large codebase can be one repository with millions of lines or a monorepo with many packages. Claude Code works at any size, but as the codebase grows, the defaults tuned for smaller projects can fill the context window with instructions and file reads unrelated to the task, costing tokens and degrading Claude’s performance. This guide shows individual developers and engineering teams how to scope Claude to the part of the codebase a task touches. Each section notes whether a setting is personal to your machine or committed to the repository.

​
What this guide covers

The table below lists each setting and what it accomplishes. The file tree after it is the example monorepo every code sample on this page refers to.

​
Settings on this page

Each setting below is independent. They layer rather than replace each other, so apply whichever fit your repository. Choose where to start Claude determines where your settings files live, so read it first. Put it together shows all of them combined.
For workflow techniques that keep context small in any repository, such as running exploration in a subagent so file reads stay out of the main conversation, see Best practices for Claude Code. To roll out a baseline configuration to every developer in your organization, see Set up Claude Code for your organization.

​
The example monorepo

The examples throughout this page refer to a monorepo with three packages. The same patterns work in a large single-tree codebase: where an example uses packages/api/, substitute your own subsystem directory such as src/backend/ or lib/core/.

​
Choose where to start Claude

Where you launch claude determines which files Claude can read and edit without an additional permission grant, which CLAUDE.md files load into context at startup, and which project settings apply. Project settings in .claude/settings.json load only from your starting directory and are not inherited from parent directories the way CLAUDE.md files are: a .claude/settings.json at the repository root applies only when you start from the root. Each section below states whether its settings file belongs at the repository root or in the subdirectory you start from, and whether it is committed or kept local.

​
Layer CLAUDE.md files by directory

In a large codebase, a single CLAUDE.md at the repository root tends to either grow to cover every subsystem’s conventions, costing context on instructions unrelated to the current task, or stay too generic to be useful. Splitting instructions across per-directory files means Claude loads repository-wide rules plus only the conventions for the code you’re working in. Claude Code loads every CLAUDE.md file from your working directory and every parent directory at launch, then loads each subdirectory’s file on demand when it reads files there. A root file sets repository-wide rules and each subdirectory adds its own. A common split is two levels:
  • Root CLAUDE.md: instructions that apply everywhere, such as coding standards, commit conventions, and repository layout
  • Per-subdirectory CLAUDE.md: conventions specific to that area’s stack. In a monorepo that’s one per package. In a large single tree it’s one per subsystem such as src/db/ or src/api/
Commit these files to the repository so teammates inherit them. Each directory’s owner typically maintains its file. The root CLAUDE.md orients Claude to the repository structure:
CLAUDE.md
Each subdirectory’s CLAUDE.md, here packages/api/CLAUDE.md, adds context specific to that area’s stack:
packages/api/CLAUDE.md