# CLAUDE.md variants Three variants of the anti-bloat starter, written as diffs from the base file (CLAUDE-starter.md). Take the base, apply the swaps below, delete what doesn't apply. Each finished file should still land under ~100 lines. --- ## Variant 1: Next.js SaaS Use when: you're building a paid web app (Stripe, auth, a database). ### Swap in "What this is" ``` [APP NAME] is a Next.js SaaS: users pay via Stripe for [FEATURE]. Money and auth code (src/billing/, src/auth/) is ask-first territory. ``` ### Swap in "Commands" ``` - Dev server: `npm run dev` (Turbopack; assume it's already running) - Tests: `npm test` - Typecheck + lint: `npm run check` - DB migration: `npx prisma migrate dev --name [name]` (ask before running) - Deploy: push to main, Vercel auto-deploys. Never `vercel --prod` manually. ``` ### Swap in "Code style" ``` - TypeScript strict, no `any`, no `@ts-ignore` without a comment saying why - Server components by default; add 'use client' only for interactivity - All data access through src/lib/db.ts helpers, never raw Prisma in components - Tailwind only, no CSS files, no inline style props - Ask before adding any dependency ``` ### Add to "Never touch" ``` - `src/billing/webhooks.ts` (Stripe webhook handler; a bug here loses money) - `prisma/migrations/` (immutable once applied; new migrations OK) - Anything under `app/api/auth/` ``` ### Add to "Definition of done" ``` 5. `npm run build` succeeds (catches server/client component mistakes that dev mode hides) ``` --- ## Variant 2: Python script project Use when: scrapers, data pipelines, automation scripts, CLI tools. No frontend, often no tests yet. ### Swap in "What this is" ``` [PROJECT] is a set of Python scripts that [WHAT, e.g. "pull leads from an API, enrich them, and write to a Google Sheet"]. Entry point is main.py; everything runs locally or via cron. ``` ### Swap in "Commands" ``` - Run: `python main.py` (uses .venv; activate with `source .venv/bin/activate`) - Install deps: `pip install -r requirements.txt`, then update requirements.txt - Lint/format: `ruff check . && ruff format .` - There is no test suite yet. For any new function with logic in it, add a test under tests/ and run `pytest`. ``` ### Swap in "Code style" ``` - Python 3.12+, type hints on all function signatures - One script = one job; shared helpers go in utils.py, nothing else shared - All secrets from environment variables via os.environ, never hardcoded - Print progress with logging, not bare print() - Ask before adding any dependency beyond the standard library ``` ### Swap in "Never touch" ``` - `.env` (secrets; read names if needed, never edit or print values) - `output/` and `data/` (generated artifacts; scripts write here, you don't) - Any file with `_prod` in the name unless I explicitly say so ``` ### Swap in "Definition of done" ``` 1. `ruff check .` passes 2. The script runs end to end on real (or sample) input without a traceback 3. You show me the actual output, not a description of what it should output ``` --- ## Variant 3: Monorepo Use when: multiple apps/packages in one repo (e.g. web app + API + shared packages). The base file becomes the root CLAUDE.md; per-package detail goes in each package's own CLAUDE.md. ### Swap in "What this is" ``` Monorepo with [N] workspaces: apps/web (customer app), apps/api (backend), packages/ui (shared components). Each workspace has its own CLAUDE.md with specifics; this file is only what applies everywhere. ``` ### Swap in "Commands" ``` - Everything runs from the repo root via [turbo/nx/pnpm]: - Dev: `pnpm dev --filter [workspace]` - Tests: `pnpm test --filter [workspace]` (or no filter for all) - Build all: `pnpm build` - Never cd into a workspace and run npm/pnpm there; always filter from root. ``` ### Swap in "Code style" ``` - Cross-workspace imports only through packages/* public exports, never deep imports into another workspace's src/ - A change to packages/* requires running the full test suite, not just the package's own tests - Ask before adding a dependency; check if a workspace already has it first ``` ### Swap in "Never touch" ``` - Root config files (turbo.json, pnpm-workspace.yaml, tsconfig.base.json) without asking; a wrong edit breaks every workspace - Other workspaces than the one the task is about, unless the task explicitly spans workspaces ``` ### Add to "When unsure" ``` - Not sure which workspace a change belongs in: ask, don't duplicate code into both. ``` ### Add a new closing note ``` ## Per-workspace files apps/web/CLAUDE.md, apps/api/CLAUDE.md etc. hold workspace-specific rules. Keep those under ~40 lines each. If a rule applies to two or more workspaces, it moves here. ``` --- ## Keeping any variant honest Whichever variant you use, the same two constraints apply: 1. Every line must be checkable or intent the agent can't infer from code. 2. New lines are earned: add one only after the agent gets the same thing wrong twice. Delete lines the moment they stop being true.