Claude Code in Monorepos

In a monorepo, a single root-level CLAUDE.md is not enough. You need a layered approach: a root CLAUDE.md for shared conventions, plus package-level CLAUDE.md files for package-specific rules. The root CLAUDE.md should cover cross-cutting concerns: the monorepo tool (Turborepo, Nx, pnpm workspaces), shared linting and formatting rules, and the overall architecture pattern. Package-level files should describe that specific package's tech stack, testing approach, and API contracts. Claude Code reads CLAUDE.md files hierarchically. When working in packages/api, it loads both the root CLAUDE.md and packages/api/CLAUDE.md. This means you do not need to repeat shared conventions in every package file.

Worktrees are a game-changer for monorepo development. Instead of switching branches and rebuilding everything, worktrees let you work on multiple features simultaneously in isolated copies of the repository. Claude Code integrates with git worktrees natively. You can spin up a worktree, make changes in isolation, and merge back when ready. This is especially useful in monorepos where a change in one package might affect others — the worktree lets you test the full impact without disrupting your main working copy. A practical pattern is to use one worktree per feature branch. Each worktree gets its own Claude Code session, so you can context-switch between features without Claude losing track of what you were doing.

One of Claude Code's strengths in monorepos is cross-package refactoring. Renaming a shared type, updating an API contract, or migrating a dependency across all packages would be tedious manually but Claude can handle it in a single session. The key is to give Claude the full picture. Start by telling it which packages are affected and what the change entails. Claude will read the relevant files across packages, plan the changes, and apply them consistently. For large refactors spanning more than 5 packages, consider breaking the work into phases. Do the shared packages first, then update consumers. This reduces the chance of inconsistent intermediate states and makes code review easier.

Monorepo build times can be long, so it is important to tell Claude how to run targeted builds and tests. Without guidance, Claude might run a full monorepo build after every change, wasting time and resources. Configure your CLAUDE.md with the commands for building and testing individual packages. Most monorepo tools support this natively: Turborepo has --filter, Nx has --projects, and pnpm has --filter. Teaching Claude these commands dramatically speeds up the feedback loop. Also consider adding a build dependency graph to your CLAUDE.md. When Claude understands that packages/api depends on packages/shared, it knows to rebuild shared first when it changes a shared type. This prevents confusing build errors that waste debugging time.