CLAUDE.md Templates: Copy-Paste Starters for Every Project Type (2026)

A CLAUDE.md tells Claude Code what it can't infer from your code, your conventions, your constraints, and the things it should never touch. These are complete files you can copy and edit.

Quick Answer: Put a CLAUDE.md in your project root. Claude Code reads it at session start. The useful content is conventions, architecture decisions, and explicit "don't do this" rules, not a description of your stack, which Claude can read from package.json. Run /init to generate a starting point, then rewrite it.

Template 1: TypeScript API service

# payments-api

Node 20, TypeScript strict mode, Fastify, Postgres via Drizzle, Vitest.

## Conventions
- No default exports. Named exports only.
- Errors: throw a typed AppError. Never return null to signal failure.
- All database access goes through repositories in src/repos/.
  Never write inline SQL in route handlers.
- Tests live beside source as *.test.ts, not in a __tests__ folder.
- Zod schemas for every request body, defined in src/schemas/.

## Architecture decisions
- Money is stored as integer cents. Never float, never decimal.
- All external HTTP goes through src/clients/ with retry and timeout.
- Migrations are forward-only. Never edit a migration that has run.
- Idempotency keys are required on every write endpoint.

## Commands
- Test: npm test -- --run
- Typecheck: npm run typecheck
- Migrate: npm run db:migrate

Run typecheck and tests after any change before saying you're done.

## Don't
- Don't add dependencies without asking.
- Don't touch src/legacy/. It's being deleted this quarter.
- Don't change the shape of any response in src/routes/public/.
  External clients depend on it.

What this demonstrates: the value is in "Architecture decisions" and "Don't". Claude can read your stack from package.json. It cannot infer that money is cents or that legacy code is off limits.

Recommended skills

skill-router-2

by Shippers · 5

Automatically detect, load, and stack the perfect skills combo for any user requ…

$5

Solo SaaS Architect

by tudor.ai

Automatically builds complete, launch-ready SaaS websites, databases, and secure…

$5

Hooks & Settings for Claude Code

by Markus Isaksson · 19

Master Claude Code's settings hierarchy and hook framework to automate workflows…

Free

Browse all Claude Md skills

Template 2: React application

# dashboard

React 19, TypeScript, Vite, Tailwind, TanStack Query, Vitest + Testing Library.

## Conventions
- Components in src/components/, one per file, named export.
- Colocate: Button.tsx, Button.test.tsx, Button.stories.tsx together.
- Server state via TanStack Query. Client state via useState or context.
  No Redux, no Zustand.
- Tailwind utility classes only. No CSS modules, no styled-components.
- Forms use react-hook-form with a Zod resolver.

## Patterns
- Data fetching lives in src/hooks/queries/, never inline in components.
- Every list needs a loading, empty, and error state. All three.
- Use the design tokens in tailwind.config.ts. Never hardcode a hex value.

## Commands
- Dev: npm run dev
- Test: npm test -- --run
- Build: npm run build

## Don't
- Don't add a component library. We're not using shadcn or MUI.
- Don't use useEffect for data fetching. That's what TanStack Query is for.
- Don't create index.ts barrel files. They break tree shaking here.

What this demonstrates: frontend CLAUDE.md files should be mostly negative constraints. The failure mode is Claude reaching for a familiar pattern that conflicts with yours.

Template 3: Python service

# ingest-worker

Python 3.12, FastAPI, SQLAlchemy 2.0 async, Pydantic v2, pytest, uv.

## Conventions
- Type hints on every function signature. mypy strict passes.
- Pydantic models for all boundaries. No raw dicts crossing a module.
- Async everywhere. No sync database calls.
- Repository pattern in app/repos/. No ORM queries in route handlers.

## Architecture decisions
- Every task is idempotent. Retries must be safe.
- Timestamps are UTC, timezone-aware, stored as timestamptz.
- Failures go to a dead letter queue, never silently swallowed.
- Config comes from environment via pydantic-settings. No config files.

## Commands
- Test: uv run pytest
- Typecheck: uv run mypy app
- Lint: uv run ruff check --fix

## Don't
- Don't use requests. Use httpx with an explicit timeout.
- Don't catch bare Exception.
- Don't add Celery. We're using arq deliberately.

What this demonstrates: the "Don't" section prevents the specific wrong choices Claude would otherwise make from general Python convention.

Template 4: Monorepo

# platform (monorepo)

pnpm workspaces, Turborepo, TypeScript.

## Structure
- apps/web      Next.js customer app
- apps/admin    Internal React admin
- packages/ui   Shared components
- packages/db   Drizzle schema and client
- packages/config  Shared eslint and tsconfig

## Rules
- Cross-package imports use the workspace name (@platform/ui),
  never a relative path across package boundaries.
- Shared code goes in packages/. If two apps need it, move it.
- packages/db is the only place that talks to Postgres.
- Every package needs its own tsconfig extending packages/config.

## Commands
- Run everything: pnpm dev
- Test one package: pnpm --filter @platform/ui test
- Build: pnpm build

## When working in this repo
State which package you're changing before you change it.
If a change touches more than one package, list them first
and wait for confirmation.

## Don't
- Don't add a dependency to the root package.json. It goes in the package
  that needs it.
- Don't import from apps/ into packages/. Dependencies flow one way.

What this demonstrates: monorepos need an explicit instruction to state scope before acting. Without it, Claude makes changes across package boundaries that break the dependency graph.

What belongs in a CLAUDE.md

Conventions Claude can't infer. Naming, error handling, file layout, testing style.

Architecture decisions and their reasoning. "Money is cents" prevents a class of bug. "We chose arq over Celery" prevents Claude helpfully migrating you.

Commands. Test, typecheck, build, migrate. Give exact strings so Claude runs the right thing.

Explicit prohibitions. The "Don't" section is usually the highest-value part of the file.

What to leave out

Your dependency list. Claude reads package.json.

Generic best practices. "Write clean code" and "add error handling" are noise.

Anything that changes weekly. A stale CLAUDE.md is worse than none, because Claude follows it confidently.

Secrets, tokens, or connection strings. It's a file in your repo.

CLAUDE.md or a skill

They overlap and the distinction is worth getting right.

CLAUDE.md is project-specific and loads for every session in that project. It's the right place for "this codebase does X."

A skill is portable and loads when its description matches the task. It's the right place for "this is how I review code", a method that follows you across projects and across agents.

If you'd want the same rule in your next project, it's a skill. If it's only true here, it's CLAUDE.md.

For methods worth making portable: code-reviewer (764 installs, free) and git-commit-writer (232 installs, free) are the two most installed. Browse all skills on Agensi.

Using these templates

1. Run /init in your project to generate a baseline
2. Delete the stack description it produces
3. Paste the closest template above and edit it to match reality
4. Add a "Don't" section with the three things you'd correct most often
5. Re-read it monthly and delete anything no longer true

For the difference between the file formats, read SKILL.md vs CLAUDE.md.