Turborepo Per-Package AI Context
Root-level CLAUDE.md with per-package CLAUDE.md files that Claude auto-loads when working in subdirectories. Works with Turborepo, Nx, and pnpm workspaces.
Description
Claude Code automatically loads CLAUDE.md files from ancestor and descendant directories. In a monorepo, this means root/CLAUDE.md sets repo-wide conventions while packages/api/CLAUDE.md adds API-specific context. Claude merges them — child files append to parent context, they don't override. Cursor supports the same pattern with nested .cursor/rules/ directories. Copilot supports nested AGENTS.md files. The Puzzmo team found monorepos ideal for LLM work because schema, API definitions, and implementation are all accessible in one place. Keep the root file under 200 lines covering cross-cutting concerns, and let package-level files handle domain specifics.
Who is this for
Teams running Turborepo, Nx, or pnpm workspace monorepos with 3+ packages or services.
Why files are split this way
A single CLAUDE.md cannot capture domain-specific context for multiple packages without becoming unwieldy. Per-package files mirror how the code itself is organized. Root handles shared conventions (Git workflow, CI, coding standards). Package files handle domain rules (API validation patterns, frontend component structure, shared library constraints).
What changed from the previous setup
A single root-level CLAUDE.md trying to cover all packages, or per-package README files that AI tools did not read automatically.
Related patterns
Universal AGENT.md with Symlinks
One AGENT.md file as the single source of truth, with symlinks to CLAUDE.md, .cursorrules, .windsurfrules, and copilot-instructions.md.
Multi-Editor Frontend Setup
Frontend-optimized AI config covering design system tokens, component conventions, and testing patterns across Cursor, Copilot, and Claude Code simultaneously.
Spec-Driven AI Development
Separates what to build (SPEC.md) from how the AI should work (CLAUDE.md). Specs define features and constraints, CLAUDE.md defines workflow and conventions.