Monorepo Project Rules

When to use this

A repository containing several packages or apps that share tooling. The specific problem here is that an agent will happily import across package boundaries in ways that break your build graph, so the dependency rules need stating explicitly.

The template

# CLAUDE.md

## What this is

A monorepo managed with [pnpm workspaces / turborepo / nx].

## Packages

- `apps/web` the customer facing app
- `apps/admin` internal admin panel
- `packages/ui` shared components, used by both apps
- `packages/config` shared eslint and tsconfig
- `packages/api-client` generated API client

## Commands

Run from the repository root:

- `pnpm dev` starts everything
- `pnpm build` builds all packages in dependency order
- `pnpm test` runs all tests
- `pnpm --filter web test` runs tests for one package

Always run commands from the root unless working inside a single package.

## Dependency rules

- Apps may depend on packages. Packages must never depend on apps.
- `packages/ui` must not import from any app.
- Nothing imports from another package's internals. Use the package's public entry point only.
- Adding a cross package dependency requires updating that package's manifest, not just an import.

## Conventions

- Each package owns its own tests
- Shared config comes from `packages/config`, do not create per package eslint files
- A change touching more than one package should say so in the commit message

## Do not

- Do not import across packages using relative paths that escape the package directory
- Do not add a dependency to the root manifest unless it is genuinely shared tooling
- Do not modify `packages/api-client`, it is generated
- Do not change the workspace or build pipeline config without asking

## Ask first

- Creating a new package
- Adding a dependency between packages that did not previously depend on each other
- Any change to the build pipeline
- Changing a package's public entry point, which may break consumers

What to change

Replace the package list with your real one and say in one line what each is for. This is the part that stops the agent guessing.

The dependency rules section is the point of this template. Write down the direction dependencies are allowed to flow in your repo, because an agent has no way to infer it and will produce a cycle that only fails at build time.

If you use a task runner with caching, note that changing a package invalidates the cache for everything downstream, so the agent understands why a small change triggers a long build.