Monorepos — Per-Package Config, Sparse Checkouts, Cross-Package Rules

Claude Code's hierarchical CLAUDE.md loading is purpose-built for monorepos. How to structure per-package configs, define cross-cutting rules at the root, use sparse checkouts for large repos, and apply /batch across all packages simultaneously.

Quick Reference

→CLAUDE.md is loaded hierarchically — deepest wins, root is fallback
→Working in packages/web/src/ loads its own CLAUDE.md + package + root in sequence
→Per-package CLAUDE.md covers that package's stack, build commands, testing patterns
→Root CLAUDE.md covers workspace protocol, shared types, cross-package import rules
→.claude/rules/ holds package-type rules (all UI packages, all API packages)
→worktree.sparsePaths restricts checkout to relevant packages for large monorepos
→/batch applies a pattern change across all packages — each gets its own agent and PR
→pnpm workspace: protocol and Turborepo caching are first-class patterns to document

The CLAUDE.md Hierarchy in Monorepos

Claude Code walks the directory tree upward from the current working directory and loads every CLAUDE.md it finds, from deepest to root. In a monorepo, this hierarchy is exactly what you need: package-specific rules that override root defaults, without duplication.

CLAUDE.md loading order for a nested monorepo path

This means you can define 'all packages use TypeScript strict mode' at the root, 'the web package uses React 19 patterns' at the package level, and 'the auth component follows PKCE flow' at the component level. Claude applies the most specific rule that matches.

The hierarchy diagram

The claude-md-hierarchy diagram in the Context & Reasoning section visualizes this loading chain. Review it before designing your monorepo CLAUDE.md structure — the diagram makes the precedence rules obvious in ways that prose descriptions don't.

CLAUDE.md level	What it covers	Example rules
Root (/repo/CLAUDE.md)	Workspace-wide conventions	workspace: protocol, shared type packages, commit format
Packages (/repo/packages/CLAUDE.md)	All packages policy	Package export patterns, inter-package import rules
Package (/repo/packages/web/CLAUDE.md)	This package's stack	React patterns, Next.js conventions, test framework
Subdirectory (/repo/packages/web/src/CLAUDE.md)	Module-level specifics	Component structure, naming, state management approach

Per-Package CLAUDE.md

Each package's CLAUDE.md is a configuration contract between you and every Claude Code session that works in that package. It encodes what a correct implementation looks like for that package's specific stack, without requiring you to re-explain it every session.

Root CLAUDE.md for Cross-Cutting Rules

The root CLAUDE.md is the workspace contract. It covers things that are true of every package: how packages reference each other, where shared types live, cross-package import rules, workspace tooling conventions.

Sign in to read this article

This is a premium article. Sign in with your Google account to continue.