CLAUDE.md — TypeScript Monorepo (pnpm + Turborepo)

# CLAUDE.md — {{repo_name}} ## What this repo is {{one_paragraph_description}} Monorepo: pnpm workspaces + Turborepo. Packages in `packages/*` (shared libraries), apps in `apps/*` (deployables). ## Commands (exact — do not guess variants) - Install: `pnpm install` (root only — NEVER run install inside a package dir) - Everything checked: `pnpm turbo run build test lint typecheck` (this is the definition of done) - One package: `pnpm --filter {{example_package}} test` (filter syntax works for build/lint/dev too) - Affected only (faster loop): `pnpm turbo run test --filter='...[origin/main]'` - Add dep to a package: `pnpm --filter <pkg> add <dep>` — root `package.json` gets tooling only, never runtime deps ## Workspace rules - Cross-package imports ONLY via workspace packages (`"@{{scope}}/utils": "workspace:*"`) and their public entry points. Deep imports into another package's `src/` are banned — they break the build graph and the published artifacts. - Dependency direction: `apps/*` may depend on `packages/*`; packages may depend on other packages (no cycles — turbo will refuse); packages NEVER import from apps. - Shared config lives in `packages/config-*` (tsconfig, eslint) — extend it, do not fork per-package copies. - Each package's `package.json` declares what it actually imports. No relying on hoisting: undeclared deps break in CI here even when they resolve locally. ## Making changes - Renaming/moving a package export? Search ALL packages for usage first: `pnpm exec turbo run typecheck` after the change tells the truth. - Any user-visible change in `packages/*` needs a changeset: `pnpm changeset` (pick bump level honestly; breaking = major, and say why in the summary). - New package: copy `packages/{{template_package}}` structure — do not hand-roll tsconfig/build setup. - Generated files (`*.gen.ts`, `dist/`, turbo cache) are never edited by hand. ## Verification discipline Run the affected-scope check after each meaningful change, the full `turbo run build test lint typecheck` before declaring done, and paste the actual final output lines in your summary. Turbo caches: a suspiciously instant pass may be a cache hit on unchanged inputs — if your change should have affected a package and its task was cached, something is wrong with what you changed. ## Do not - Edit `pnpm-lock.yaml` by hand, add deps at the root, disable turbo caching, bump package versions manually (changesets own versions), edit another team's `apps/*` without it being in the task, or commit `.env*` files.