CLAUDE.md for Monorepos

# CLAUDE.md

## Project

[Company] monorepo — pnpm workspaces + Turborepo.

## Package map

- `apps/web` — customer-facing Next.js app
- `apps/admin` — internal admin (Vite + React)
- `apps/api` — Fastify API
- `packages/ui` — shared component library (used by web + admin)
- `packages/config` — shared tsconfig/eslint — changes here affect EVERYTHING
- `packages/db` — Prisma schema + client — the only package allowed to talk to the database

## Commands (always scope to the package)

```bash
pnpm --filter web dev              # run one app
pnpm --filter web test             # test one package
pnpm turbo run build --filter=web...   # build web + its dependencies
pnpm turbo run test --filter=[HEAD^]   # test only what changed
```

Never run bare `pnpm build` / `pnpm test` at the root during iteration — it builds the world.

## Cross-package rules

- Importing between packages: ONLY via workspace deps declared in package.json — never relative paths across package boundaries (`../../packages/ui/src` is banned)
- Changing `packages/ui` or `packages/config`: run the affected-tests command for ALL dependents before finishing
- `packages/db` schema changes follow the migration process in packages/db/CLAUDE.md
- New shared code: goes in an existing package if one fits; creating a new package requires asking first

## Per-package conventions

Each app/package may have its own CLAUDE.md with local rules — READ IT before working in that package. This file covers only repo-wide rules.

## Don't

- Don't hoist dependencies to the root to fix a resolution issue — fix the package's own manifest
- Don't edit generated files (`*.gen.ts`, prisma client output)
- Don't bump shared dependency versions in one package only — keep versions aligned via the catalog

## Verification

Definition of done: `pnpm turbo run lint typecheck test --filter=[your changes]...` passes, including dependents of anything shared you touched.

How to use

1. 1Copy to the monorepo root; write the real package map — it's the section agents use most.
2. 2Add thin per-package CLAUDE.md files for local rules; the root file's job is orientation and cross-package safety.
3. 3The scoped-commands section pays for itself immediately in iteration speed.

Examples

Pro tips

• Keep the package map current — a stale map is worse than none because agents trust it.