Set up Claude Code in a monorepo or large codebase changedlarge-codebases
Nearest release: v2.1.239, published under an hour before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+16added
Lines−25removed
From line
71
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits20to this page, all time
The whole hunk
from line 71, old and new numbered
/
from line 71
7171
7272A common split is two levels:
7373
74* **Root `CLAUDE.md`**: instructions that apply everywhere, such as coding standards, commit conventions, and repository layout
74* **Root `CLAUDE.md`**: instructions that apply everywhere, such as coding standards and commit conventions
7575* **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/`
7676
7777Commit these files to the repository so teammates inherit them. Each directory's owner typically maintains its file.
7878
79The root `CLAUDE.md` orients Claude to the repository structure:
79To trim a file that is already checked in, run the [`/doctor` checkup](/docs/en/memory#my-claude-md-is-too-large). The root `CLAUDE.md` holds the rules that apply in every package:
8080
8181```markdown CLAUDE.md theme={null}
82This is a monorepo with three packages under packages/:
83
84- packages/api: Node.js REST API with Express, TypeScript, and PostgreSQL
85- packages/web: React frontend with Vite, TypeScript, and TailwindCSS
86- packages/shared: shared TypeScript utilities used by both api and web
87
88Run commands from the package directory, not the monorepo root.
89Each package has its own tsconfig.json, package.json, and test suite.
82Run package scripts from the package directory, not the monorepo root.
83Prefix commit subjects with the package name, for example `api: add rate limiting`.
84Never edit files under packages/*/generated/. Run `npm run codegen` in the package instead.
9085```
9186
92Each subdirectory's `CLAUDE.md`, here `packages/api/CLAUDE.md`, adds context specific to that area's stack:
87Each subdirectory's `CLAUDE.md`, here `packages/api/CLAUDE.md`, adds the conventions specific to that area:
9388
9489```markdown packages/api/CLAUDE.md theme={null}
95This package is the REST API server.
96
97- Run tests: `npm test` (uses Vitest)
98- Run dev server: `npm run dev` (port 3001)
99- Database migrations: `npm run migrate`
100- Environment variables: copy `.env.example` to `.env`
101
102API routes are in src/routes/. Each route file exports an Express router.
103Database queries use Knex in src/db/. Never write raw SQL strings in route handlers.
90Copy `.env.example` to `.env` before running anything. Tests and the dev server fail without it.
91Write database queries with the Knex query builder. Never put raw SQL strings in route handlers.
92Never edit a migration after it has merged. Add a new migration instead.
10493```
10594
10695When you start Claude from `packages/api/`, it loads both `packages/api/CLAUDE.md` and the root `CLAUDE.md`. Claude sees the local instructions alongside the repository-wide rules, with no instructions from `packages/web/` in context. The same holds for any subdirectory in a non-monorepo tree. To confirm which files loaded, run `/context` and check the list under **Memory files**.
from line 149
160149
161150Claude's content searches respect `.gitignore` by default, so paths already listed there, such as `node_modules/`, `dist/`, and `build/`, stay out of search results without additional configuration.
162151
163For paths that are checked in, such as a vendored SDK or committed generated code, add `Read` deny rules in `permissions.deny` to block Claude from opening those files even when a search lists them.
152For paths that are checked in, such as a vendored SDK or committed generated code, add `Read` deny rules in `permissions.deny` to block Claude from opening those files.
164153
165154The deny rules can cover everyone working in the repository, only you, or every session on the machine, depending on which settings file you put them in:
166155
from line 172
183172}
184173```
185174
186Deny rules cover Claude's built-in file tools and recognized Bash file commands, including `cat`, `head`, `grep`, and `find`, when a denied path is passed as an argument. They do not filter denied paths out of a recursive search's output, and they do not cover arbitrary subprocesses that open files themselves. For the full pattern syntax, see [Read and Edit permission rules](/docs/en/permissions#read-and-edit).
175Deny rules cover Claude's built-in file tools and recognized Bash file commands, including `cat`, `head`, `grep`, and `find`, when a denied path is passed as an argument. Claude Code also makes a best-effort attempt to leave denied paths out of the results of the built-in Grep and Glob tools. Claude still sees denied paths in the output of a Bash search such as `grep -r` or `find`.
187176
177Deny rules don't cover subprocesses that open files themselves. For the full pattern syntax, see [Read and Edit permission rules](/docs/en/permissions#read-and-edit).
178
188179### Reduce file reads with code intelligence
189180
190181In a large codebase, finding where a symbol is defined or used can cost many file reads and grep calls. [Code intelligence plugins](/docs/en/discover-plugins#code-intelligence) connect Claude to a language server so it can jump to definitions, find references, and surface type errors directly instead of scanning the tree.
from line 461
470461Two techniques help keep a cross-package change consistent:
471462
472463* **Give Claude the whole change in one session**: handing over the shared edit and its call sites together keeps the decisions behind each edit consistent, rather than re-deriving them per package
473* **Save the plan to a file before editing**: [plan first](/docs/en/best-practices#explore-first-then-plan-then-code) and ask Claude to write the plan to a markdown file in the repository. A long cross-package session [compacts its context](/docs/en/context-window#what-survives-compaction) along the way, and the saved plan survives where conversation history may not
464* **Plan before editing**: [plan first](/docs/en/best-practices#explore-first-then-plan-then-code) in [plan mode](/docs/en/permission-modes#analyze-before-you-edit-with-plan-mode), and Claude writes the plan to a file. A long cross-package session [compacts its context](/docs/en/context-window#what-survives-compaction) along the way. Claude Code re-injects the plan file after each compaction, so the plan survives where conversation history may not
474465
475466## Next steps
476467
No line in this hunk matches that.