Monorepo Setup: Large Codebases with Nested CLAUDE.md

A monorepo can have: 1. Root CLAUDE.md: global rules (all agents must follow). 2. Package CLAUDE.md: local overrides (this package's rules).

When Claude Code starts in a package directory, it reads the local CLAUDE.md first. If a rule is missing, it inherits from the root. This lets the root enforce guardrails (no destructive operations, no credentials in code) while packages define their own tools and skills.

Example: root forbids rm -rf globally. But packages/build/ has a CLAUDE.md that permits npm run clean (which safely removes dist/). The package rule refines the root rule; it doesn't override the safety intent.

A skill is a tool or routine that an agent can invoke. Skills can be scoped to a package. Example: only agents in packages/db/ can run database migrations. Agents in packages/ui/ can't.

Path-gating implements this: a rule has a paths field that restricts where it applies. An agent running in packages/ui/ sees skills defined globally + skills in packages/ui/.claude/CLAUDE.md, but not skills from packages/db/.claude/CLAUDE.md.

A monorepo has 1M+ lines. Claude Code doesn't need to index all of it to work on one package. Sparse worktrees check out only the files you need, reducing disk I/O and indexing time.

The pattern: define .worktreeinclude that lists which paths to include (e.g., packages/ui/, packages/shared/). When you create a worktree with --sparse, only those paths are downloaded. Claude Code indexes only what's needed. Time to ready: 2s (sparse) vs. 20s (full).

Claude Code builds an index of symbols (functions, classes, types) to enable fast navigation and dependency discovery. In a monorepo, the index can balloon. With path-gating and sparse worktrees, you control index scope.

Best practice: index only the current package. The index includes: exported types from shared/, internal implementation of the current package, and test files. It excludes other packages' internals. This keeps the index compact and focused.

Claude Code reads files on demand. But if you ask an agent to 'understand the entire repo', it will try to read everything, consuming tokens and context. The boundary: be explicit about scope.

Instead of 'implement feature X', say 'in packages/ui/, implement feature X'. This scopes the agent to one package. If it needs types from shared/, the package's tsconfig.json guides the import; the agent doesn't need to read other packages.

For true monorepo understanding (which packages import which), use a separate analysis pass: a subagent that maps the dependency graph, returns a report, and other agents use that report as input.

Three repos: frontend (Next.js, 200k LOC), backend (Go, 300k LOC), shared (TypeScript types, 50k LOC). Organized as a monorepo: root CLAUDE.md sets global rules, each package has its own.

Scenario: implement a new API endpoint (backend) + UI page (frontend) + shared types (types). Traditionally: 3 developers, 3 PRs, coordinate types. With Claude Code: 1 agent orchestrates, spawns 3 subagents (one per package), passes types through state, validates, merges.

Time: 30 min (instead of 2 hours of coordination). Cost: ~$1 in tokens.

At 1M+ lines, the monorepo is too large for one agent to comprehend. Instead, decompose into agents:

1. Indexer agent: maps repo structure, exports (packages, types, public APIs). 2. Planner agent: reads indexer output, breaks down the feature into subtasks. 3. Worker agents: each handles one subtask (e.g., implement API, add UI, add types). 4. Validator agent: checks correctness (tests pass, types valid, no conflicts). 5. Merger agent: coordinates merges, resolves conflicts.

This pipeline is more reliable and scalable than a single monolithic agent. Each agent is specialized, smaller context, easier to debug.