Working CLAUDE.md examples for Python, Node.js, monorepo, and team projects. Copy the template, fill in the brackets, drop into your repo root.
CLAUDE.md is the file Claude Code loads automatically on every session. Put house rules there once and Claude follows them in every conversation. This page has four working templates — pick the one closest to your project, fill the brackets.
# [PROJECT NAME]
## Stack
- Python 3.12, uv for dependencies (lockfile: uv.lock)
- FastAPI for HTTP, SQLAlchemy 2.0 (async) for DB, Postgres 16
- pytest + pytest-asyncio for tests, ruff for lint, mypy strict mode
- pre-commit hooks: ruff format + ruff check + mypy
## House rules
- Always run `uv run pytest -x` after changes. If failures, fix or revert.
- Type hints required on every function. No `Any` unless commented why.
- No print() — use the structured logger from `src/log.py`.
- No mocks of DB layer in tests. Use the test DB fixture in `tests/conftest.py`.
- Database migrations: write with alembic, review the autogenerate output before committing.
## Project layout
- `src/api/` — FastAPI routers
- `src/services/` — business logic (no FastAPI imports here)
- `src/models/` — SQLAlchemy ORM
- `src/log.py` — logging config
- `tests/` — mirrors src/ layout, one test file per module
## Prompts (invoke by name)
### Code review
Review the current diff as a skeptical senior engineer. Output a markdown
table: | file:line | severity 1-5 | category | one-line fix |. Max 12.
If clean, say so in one sentence and stop.
### Test generation
Write tests for [FN]. 2 happy-path, 2 boundary, 2 invalid input,
1 invariant, 1 regression. Do not mock the function under test.
## Commands you have permission to run
- `uv run pytest -x`
- `uv run ruff check .`
- `uv run mypy src`
- `alembic upgrade head` (test DB only)# [PROJECT NAME]
## Stack
- Node 22 LTS, pnpm for deps (frozen lockfile)
- TypeScript 5.6, strict mode, no implicit any
- Express + zod for validation, Prisma for ORM, Postgres
- Vitest for tests, eslint + prettier
- Husky pre-commit: lint-staged + tsc --noEmit
## House rules
- Run `pnpm test` after changes. If failures, fix or revert.
- All API inputs go through zod schemas. No raw req.body access.
- No `any` types. Use `unknown` and narrow.
- Prisma queries: use `select` to limit columns; never `SELECT *` via Prisma's implicit return.
- Errors: throw custom error classes from `src/errors/`. The global handler maps them to HTTP codes.
## Project layout
- `src/routes/` — Express routes (validation + handler)
- `src/services/` — business logic (no express imports)
- `src/db/` — Prisma client wrapper
- `src/errors/` — custom error classes
- `tests/` — vitest tests mirroring src/
## Prompts (invoke by name)
### PR summary
Read the current diff. Output 5 lines: WHY, WHAT, HOW, RISK, TESTS.
No marketing language. No "this PR aims to".
### Refactor (safe rename)
Rename [OLD] to [NEW] across imports, definitions, tests, comments.
Touch no other code. Run `pnpm test`. Confirm green.
## Commands
- `pnpm test`
- `pnpm lint`
- `pnpm tsc --noEmit`# [REPO NAME]
## Layout (pnpm workspaces)
- `packages/api` — backend (TypeScript, Express)
- `packages/web` — frontend (Next.js 15, app router)
- `packages/shared` — types and schemas used by both
- `packages/cli` — Node CLI for ops tasks
## Cross-package rules
- Types that cross package boundaries live in `packages/shared`. Do NOT duplicate.
- A change in `packages/shared` must update both `api` and `web` callers in the SAME PR.
- Never import from `packages/web` into `packages/api` or vice versa.
## Per-package CLAUDE.md
Each package has its own `CLAUDE.md` with package-specific rules.
If you're working inside a package, the package CLAUDE.md is authoritative.
This root CLAUDE.md only covers cross-package concerns.
## Test command
- `pnpm -r test` — runs every package's tests
- After cross-package change, ALWAYS run this, not just one package's tests
## Prompts
### Cross-package change planner
For a change touching [PACKAGE_A] and [PACKAGE_B]:
1. List the shared types/contracts affected
2. Plan: shared first, then api, then web (or matching dependency order)
3. After each step, run `pnpm -r tsc --noEmit`. Stop on first error.# [PROJECT]
## Who's on this project
- Code review must include @backend-leads for changes to `src/api/`
- DB schema changes require @dba review (use the migration template in `docs/migrations.md`)
- Customer-facing copy changes require @design review (label PRs `needs-copy-review`)
## Branching
- Main is protected. Branch from main, PR back to main.
- Branch names: `feat/-`, `fix/-`, `chore/`
- One commit per logical change. Use the commit template (CLAUDE: respect it).
## Deploy
- `main` → staging on merge (auto)
- Production tag `vX.Y.Z` → prod (manual approval in CI)
- Hotfixes: branch from prod tag, not from main
## Safety rules for Claude
- Never push to main directly. Always open a PR.
- Never run `git push --force` unless I explicitly ask, even on feature branches.
- Never run anything against the production DB. If a script touches DB, confirm it points to staging.
- Always create new commits — do not amend unless I ask.
- When generating migrations, only WRITE the migration file. Do NOT run it. I'll review and run.
## Prompts
### Pre-PR checklist
Before I open a PR, check:
- All tests pass locally
- No console.log / print() left in
- No commented-out code
- The PR description follows the template at `docs/pr-template.md`
- Migration (if any) is reversible
Output as a checklist. Fix what you can, flag what you can't. | Include | Leave out |
|---|---|
| Stack and versions (lockfile name) | Generic "we use Python" — Claude knows |
| Test/lint commands you want Claude to run | Long lists of every npm script |
| House rules with "always" or "never" framing | Aspirational style guides Claude can't enforce mechanically |
| Named prompts you reuse | One-off prompts for a single session |
| Safety rules (no force-push, no prod DB) | Generic warnings Claude already follows |
| Project layout if non-standard | The Python/Node default layout — Claude can infer |
The Claude Code Power Prompts PDF gives you 30 named prompts you can paste under ## Prompts in your CLAUDE.md. Paste once, Claude reads them every session, you stop re-typing. £3 launch tonight (first 10 buyers), £5 standard, 8 pages, instant download.