Monorepo Context Patterns

Overview

Claude Code 2.1.20 introduces --add-dir for multi-directory context, enabling monorepo-aware sessions where each service maintains its own CLAUDE.md instructions.

Monorepo Detection

Indicators that a project is a monorepo:

Indicator Tool

pnpm-workspace.yaml

pnpm

lerna.json

Lerna

nx.json

Nx

turbo.json

Turborepo

rush.json

Rush

3+ nested package.json files Generic

Per-Service CLAUDE.md

Each service can have its own context instructions:

monorepo/ CLAUDE.md # Root context (workspace-wide rules) packages/ api/ CLAUDE.md # API-specific patterns package.json web/ CLAUDE.md # Frontend-specific patterns package.json shared/ CLAUDE.md # Shared library context package.json

--add-dir Usage

Start Claude Code with additional directory context:

From api service, add shared library context

claude --add-dir ../shared

Multiple directories

claude --add-dir ../shared --add-dir ../web

Environment Variable

Enable automatic CLAUDE.md loading from additional directories:

export CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1

When set, Claude Code reads CLAUDE.md from all --add-dir directories.

Root vs Service Context Separation

Root CLAUDE.md

• Workspace-wide conventions (commit messages, branch naming)

• Cross-service dependency rules

• CI/CD pipeline overview

• Shared tooling configuration

Service CLAUDE.md

• Service-specific patterns and frameworks

• Local test commands

• API contracts and schemas

• Service-specific environment variables

Related Skills

• configure

• OrchestKit configuration including monorepo detection

• project-structure-enforcer

• Folder structure enforcement