Set Up Claude Code for Monorepo Navigation

Monorepos confuse Claude. It reads files from the wrong package, mixes up shared dependencies, and wastes context on irrelevant code. Fix that with proper configuration.

.claudeignore for Monorepos

# .claudeignore
node_modules/
dist/
.next/
coverage/

# Ignore packages you're not working on
packages/legacy-app/
packages/deprecated-*/
apps/admin-panel/   # only if you're not touching it

Package-Specific Rules

Use .claude/rules/ to scope instructions per package:

# .claude/rules/packages-api.md
When working in packages/api/:
- Use Express, not Fastify
- Tests are in __tests__/ next to source files
- Run `pnpm --filter api test` to verify

# .claude/rules/packages-web.md
When working in packages/web/:
- This is a Next.js app
- Components are in src/components/
- Run `pnpm --filter web dev` to preview

CLAUDE.md for Monorepos

# CLAUDE.md
This is a pnpm monorepo. Key packages:
- packages/api: Express backend
- packages/web: Next.js frontend
- packages/shared: Shared types and utils

Always specify which package you're working in.
Run tests with: pnpm --filter <package> test

Scope Your Prompts

Working in packages/api only.
Add a new /users endpoint.
Don't modify anything outside packages/api.

Tip

Start every monorepo session by telling Claude which package you’re in. It prevents cross-package confusion and keeps context focused.