The rule behind every good CLAUDE.md
Keep a line only if Claude can't easily discover it, it matters in most sessions, and it's specific enough to act on. Everything else is noise that dilutes the lines that matter. Aim for well under 200 lines; great files are often under 50.
1. Web app
CLAUDE.md
# Storefront (Next.js)
## Commands
- Dev `pnpm dev` · Test one file `pnpm test -- <path>` · Types `pnpm tsc --noEmit`
## Must-knows
- Server components by default; add "use client" only for interactivity.
- Prices are integer cents. Format only in `lib/money.ts`.
- E2E tests need `pnpm db:seed` first.
## Done means
- Types clean and affected tests pass; say what you ran.2. REST API
CLAUDE.md
# Orders API (Python, FastAPI)
## Commands
- Test `uv run pytest -q` · Lint `uv run ruff check .` · Run `uv run fastapi dev`
## Conventions
- Validate every request with the pydantic models in `app/schemas/`.
- Errors are `{"error": {"code", "message"}}`, never bare strings.
- New endpoints need a test in `tests/api/`.
## Gotchas
- `app/legacy/` is frozen. Wrap it, don't edit it.3. Monorepo
CLAUDE.md
# Acme monorepo (pnpm + turbo)
- Run tasks per package: `pnpm --filter <pkg> test`.
- `packages/ui` is published. Changes need `pnpm changeset`.
- Package-specific rules live in each package's CLAUDE.md and in .claude/rules/.Pair this with path-scoped rules in .claude/rules/ so React rules load only when Claude touches React files.
4. Data / analytics
CLAUDE.md
# Analytics (dbt + DuckDB)
- Build `dbt build --select <model>+` · Test `dbt test --select <model>`
- Never query raw tables for metrics; use `marts/`.
- Revenue = `net_amount_cents` after refunds. Finance signs off on changes to `fct_revenue`.5. Open-source library
CLAUDE.md
# tinyparse
- Zero runtime dependencies. Don't add any.
- Public API is `src/index.ts` only; anything else is internal.
- Every bug fix needs a regression test named after the issue number.What to leave out
- Architecture essays (Claude can read the code)
- Long procedures (make them skills)
- Rules that must never break (make them hooks or deny rules)
- Generic advice like "write clean code"
Want the full method, including path-scoped rules and auditing with /doctor? It's in Lesson 12.