Claude Code in a Monorepo
Monorepos add complexity for Claude Code context management. Here's what to set up so it stays oriented.
Monorepos — single repos containing multiple packages or applications — are common enough that it's worth talking about the specific challenges they create for Claude Code. The main issue is context: Claude needs to understand which package you're working in and how it relates to the others, without reading everything.
Use package-level CLAUDE.md files
A monorepo might have a root CLAUDE.md for repo-wide conventions, but individual packages should have their own CLAUDE.md files that describe that package specifically. When Claude is working on the payments package, it reads the payments CLAUDE.md. It doesn't need to load context from the notifications package or the admin dashboard.
Root CLAUDE.md: repo-wide rules, shared tooling, cross-package conventions. Package CLAUDE.md: what this package does, its dependencies, its patterns, its entry points.
Be explicit about cross-package imports
Claude will sometimes resolve imports incorrectly in monorepos — using a relative path where you need a package import, or importing from the wrong package. Be explicit in prompts: "Import UserService from @company/auth, not from a relative path."
If your monorepo has workspace packages with consistent naming (all packages under @company/*), include that convention in CLAUDE.md so Claude applies it without being told each time.
Constrain the working directory
When working on a specific package, I start Claude with an explicit scope: "We're working in packages/api. Don't read or modify anything outside that directory unless I tell you to." This prevents Claude from wandering across the repo looking for context and burning context budget on unrelated code.
Shared libraries need extra care
If Claude modifies a shared library, the change affects every package that imports it. Make sure Claude knows when it's working on shared code: "This is the shared utils package. Changes here affect 8 other packages. Only change the specific function I asked about."
For shared library changes I also ask Claude to list the downstream consumers before making changes. It can usually identify them from import patterns in the codebase.
Workspace command differences
Test commands, build commands, and dev server commands differ between packages in a monorepo. Include the commands for the specific package you're working in when starting a session — don't rely on Claude knowing the correct workspace commands from memory.