Monorepo Navigation Pattern

WorkflowIntermediate

Monorepos with dozens of packages create navigation challenges for Claude Code. Without guidance, it wastes context reading irrelevant packages. This pattern uses CLAUDE.md to provide a package map, dependency graph, and routing rules so Claude knows exactly where to look. Includes conventions for cross-package changes, shared type updates, and package-specific overrides.

monoreponavigationturborepoworkspace

Pattern Code

# Monorepo Navigation Pattern

## Root CLAUDE.md — Package Map
```markdown
# Monorepo: Acme Platform

## Package Map
| Package | Path | Purpose | Owner |
|---------|------|---------|-------|
| @acme/web | apps/web | Next.js frontend | frontend-team |
| @acme/api | apps/api | Express API server | backend-team |
| @acme/admin | apps/admin | Admin dashboard | frontend-team |
| @acme/ui | packages/ui | Shared UI components | design-system |
| @acme/types | packages/types | Shared TypeScript types | all |
| @acme/db | packages/db | Database client + schema | backend-team |
| @acme/auth | packages/auth | Auth utilities | security-team |
| @acme/config | packages/config | Shared configs (ESLint, TS) | infra-team |

## Dependency Graph (simplified)
web → ui, types, auth, config
api → types, db, auth, config
admin → ui, types, auth, config
ui → types, config
db → types, config

## Routing Rules
- UI changes: start in packages/ui, then check apps/{web,admin}
- Type changes: update packages/types, then fix ALL consumers
- Auth changes: update packages/auth, verify in apps/api first
- Schema changes: packages/db first, then packages/types, then apps/api

## Cross-Package Change Checklist
1. Update the source package
2. Run `turbo build --filter=...^...` to check dependents
3. Update consumers if the public API changed
4. Run `turbo test` from root to verify everything
```

## Package-Level CLAUDE.md (apps/api/CLAUDE.md)
```markdown
# @acme/api

## Entry Point
- src/index.ts (Express app setup)
- src/routes/ (route definitions, one file per resource)

## Testing
- Run: `pnpm --filter @acme/api test`
- Integration tests need DATABASE_URL set

## Local Dependencies
- @acme/types: import { User, Order } from "@acme/types"
- @acme/db: import { db } from "@acme/db"
- @acme/auth: import { verifyToken } from "@acme/auth"
```

Copy this pattern into your project configuration to implement.

Terminal Preview

Monorepo Navigation Pattern

About Monorepo Navigation Pattern

Claude Code patterns are proven architectural designs and workflow structures that help you tackle complex development scenarios. Monorepo Navigation Pattern is a Workflow pattern at the Intermediate level that provides a tested, repeatable approach you can adapt to your projects for more efficient and consistent results.

Related Patterns

Parallel Task Execution

Split large tasks into independent subtasks and execute them concurrently across multiple Claude Code instances.

Code Review Feedback Loop

Establish an iterative review cycle where Claude Code reviews, fixes, and re-validates code changes automatically.

Context Window Management

Strategies to maximize Claude Code's effectiveness within context window limits on large codebases.