CLAUDE.md for Monorepo
Several packages in one repository, where knowing the boundaries matters most.
How to use this
Save it as CLAUDE.md in your repository root and replace the placeholders in angle brackets. Claude reads it before every task, so keep it short — the Playbooks table at the bottom is how you add detail without paying for it on every unrelated request.
The file
# <project name>
<What the system does, and what each package is responsible for.>
## Commands
- `pnpm dev` — everything in dev mode
- `pnpm build` — build all packages in dependency order
- `pnpm test` — all tests
- `pnpm --filter <pkg> <cmd>` — scope a command to one package
## Packages
- `packages/core` — shared domain logic; depends on nothing internal
- `packages/ui` — shared components
- `apps/web` — the application
## Conventions
IMPORTANT: dependencies point one way — apps depend on packages, never the reverse.
YOU MUST: state which package you are changing before editing.
NEVER: import across packages by relative path; use the package name.
- A change to `core` affects everything. Say so, and run the full build.
## Verification
`pnpm build` and `pnpm test` pass from the repository root.
## Working with Claude Code
- Explore the relevant files before proposing a change.
- For anything non-trivial, plan first (Shift+Tab into plan mode) and let me review.
- Run the verification command below before telling me something works.
- Keep commits small and conventional (`feat:`, `fix:`, `docs:`, `chore:`).
## Playbooks
- Adding a new workspace package → read `.claude/playbooks/add-package.md` first
- Releasing and versioning packages → read `.claude/playbooks/release.md` first
The playbooks it expects
The routing table points at files that don't exist yet. Create them as you need them — each one holds a procedure too long to sit in CLAUDE.md and too rare to justify the context cost.
.claude/playbooks/add-package.mdAdding a new workspace package.claude/playbooks/release.mdReleasing and versioning packages
Other starting points
Next.js + Supabase
App Router, TypeScript, Tailwind and Supabase with row-level security.
R Data Analysis
Tidyverse analysis project with reproducible figures and a clear data pipeline.
Python Research Project
Analysis codebase with notebooks for exploration and modules for anything reused.
Python REST API
FastAPI service with typed schemas, tests and migrations.
CLI Tool
A command-line tool where the interface is the contract.
Need something else? Build one from scratch with the generator.