Claude Code in Monorepos: Hierarchical CLAUDE.md and Package-Scoped Instructions

Monorepos are common for full-stack TypeScript projects (Next.js + API + shared packages). Claude Code works well in monorepos with the right configuration structure.

---

The Problem with a Single CLAUDE.md

If you have one CLAUDE.md at the repo root for a monorepo with:

• packages/api/ — Express backend
• packages/web/ — Next.js frontend
• packages/shared/ — Shared types/utils
• apps/mobile/ — React Native app

A single CLAUDE.md either:

• Is too generic to be useful ("use TypeScript")
• Has conflicting rules (API-specific things confuse web development)

---

Hierarchical CLAUDE.md

Place CLAUDE.md files at multiple levels:

my-monorepo/
├── CLAUDE.md              # Rules for ALL packages
├── packages/
│   ├── api/
│   │   └── CLAUDE.md      # API-specific rules
│   ├── web/
│   │   └── CLAUDE.md      # Frontend-specific rules
│   └── shared/
│       └── CLAUDE.md      # Shared package rules (strict!)

Claude Code reads all CLAUDE.md files from root to current directory.

---

Root CLAUDE.md (Universal Rules)

# Monorepo: my-app

## Package Manager
- pnpm workspaces (never use npm or yarn)
- Add packages: `pnpm --filter @myapp/api add <package>`
- Install all: `pnpm install`

## Build System
- Turborepo: `pnpm turbo build`
- Run for specific package: `pnpm --filter @myapp/api build`
- Run tests: `pnpm turbo test`

## Universal Rules (all packages)
- TypeScript strict: true
- No `any` type
- No `console.log` in production code

## Cross-Package Dependencies
- `api` can import from `shared`
- `web` can import from `shared`
- `shared` CANNOT import from `api` or `web` (circular dep prevention)
- `api` and `web` should NOT directly import from each other

## Protected Files
- `packages/shared/src/types/` — shared types, changing breaks everything
- `pnpm-lock.yaml` — never edit manually
- `turbo.json` — changes affect build order for all packages

---

packages/api CLAUDE.md

# Package: @myapp/api

## Stack
- Express 4 + Prisma ORM + PostgreSQL

## Architecture
- Router → Controller → Service → Repository
- No DB operations in Controllers
- No HTTP types in Services

## Commands
- Run: `pnpm --filter @myapp/api dev`
- Test: `pnpm --filter @myapp/api test`
- DB migrate: `pnpm --filter @myapp/api prisma:migrate`

## Key Files
- DB: src/lib/db.ts (Prisma singleton)
- Auth middleware: src/middleware/auth.ts
- Shared types: imported from @myapp/shared

---

packages/web CLAUDE.md

# Package: @myapp/web

## Stack
- Next.js 14 (App Router) + Tailwind CSS

## Architecture
- Server Components by default
- Client Components: only for interactivity
- API calls: use src/lib/api.ts wrapper (NOT fetch directly)

## Commands
- Dev: `pnpm --filter @myapp/web dev`
- Build: `pnpm --filter @myapp/web build`

## Key Files
- API client: src/lib/api.ts
- Auth: src/lib/auth.ts (next-auth config)
- Shared types: imported from @myapp/shared

---

Always Specify the Package Scope

When working in a monorepo, tell Claude Code which package you're in:

I'm working in packages/api. Please:
- Only modify files under packages/api/
- Import types from @myapp/shared, don't duplicate them
- Don't touch packages/shared/ types directly

[your request here]

Without this context, Claude Code might modify the wrong package or duplicate shared types.

---

Shared Package Constraints

The shared package needs the strictest rules:

# Package: @myapp/shared

## ⚠️ HIGH IMPACT PACKAGE
Changes here affect ALL packages (api, web, mobile).

## Change Process
1. Discuss with team before changing existing types
2. Adding new types: OK without discussion
3. Changing/removing types: requires team sign-off
4. After change: run `pnpm turbo build` to verify all packages compile

## Rules
- Pure types and utilities only (no framework dependencies)
- No direct imports from api, web, or mobile
- Exports must be stable (prefer adding over changing)

---

/refactor-suggest in Monorepos

When refactoring, specify the scope:

/refactor-suggest packages/api/src/services/user.service.ts

Then review whether changes would require updating packages/shared types.

---

Code Review Pack (¥980) on PromptWorks includes skills configured to work with monorepo CLAUDE.md hierarchies.

👉 prompt-works.jp

Myouga (@myougatheaxo) — Security-focused Claude Code engineer.