Writing a CLAUDE.md from scratch is tedious. You know the format, you understand the concept, but staring at an empty file and deciding what to include for your specific type of project is where momentum dies.
These 10 templates solve that problem. Each one is a complete, working CLAUDE.md tailored to a specific project type. Copy the one that matches your stack, edit the details, and you are ready to go. Every template follows the patterns we identified in our guide to writing CLAUDE.md files and draws from the best real-world examples in our gallery.
1. Next.js / React Web App
The most common use case. This template covers the App Router, server/client component boundaries, and the conventions that trip Claude up most often in React projects.
# Project
Next.js 15 app using App Router, TypeScript, Tailwind CSS, and Drizzle ORM with PostgreSQL.
## Tech Stack
- Framework: Next.js 15 (App Router)
- Language: TypeScript (strict mode)
- Styling: Tailwind CSS with cn() utility from @/lib/utils
- Database: PostgreSQL via Drizzle ORM
- Auth: NextAuth.js v5
- Package manager: pnpm
## Code Style
- Functional components with arrow functions. No class components.
- Named exports only. No default exports except for pages/layouts.
- File naming: kebab-case for files, PascalCase for components.
- Imports: React first, third-party second, local third. Blank line between groups.
- No `any` type. Use `unknown` and narrow with type guards.
- Prefer `interface` over `type` for object shapes.
## Architecture
- Server Components by default. Only add 'use client' when the component needs interactivity, browser APIs, or React hooks.
- Data fetching happens in Server Components or Server Actions. Never fetch in client components.
- Server Actions for all mutations. Define them in `src/app/actions/`.
- Validate all inputs with Zod schemas defined in `src/lib/validators/`.
## File Structure
- `src/app/` — Routes and layouts (App Router)
- `src/components/` — Reusable UI components
- `src/components/ui/` — shadcn/ui primitives
- `src/lib/` — Utility functions, validators, constants
- `src/db/` — Drizzle schema and migrations
- `src/app/actions/` — Server Actions
## Commands
- `pnpm dev` — Start dev server on port 3000
- `pnpm build` — Production build
- `pnpm lint` — ESLint check
- `pnpm db:push` — Push schema changes to database
- `pnpm db:studio` — Open Drizzle Studio
## Do NOT
- Do not install new dependencies without asking first.
- Do not use inline styles. Use Tailwind classes.
- Do not create API routes when Server Actions would work.
- Do not put business logic in components. Extract to lib/.2. Python Data Science / ML Project
ML projects have unique needs: notebook conventions, environment management, data pipeline patterns, and model versioning. This template sets boundaries that prevent Claude from creating unmaintainable research code.
# Project
Python machine learning project for [describe task]. Uses PyTorch, scikit-learn, and pandas.
## Environment
- Python 3.11+
- Package manager: uv (use `uv pip install` and `uv run`)
- Virtual env: `.venv/` (do not use system Python)
- Dependencies: pyproject.toml (do not use requirements.txt)
## Code Style
- Follow PEP 8. Max line length: 120 characters.
- Type hints on all function signatures. Use `from __future__ import annotations`.
- Docstrings: Google style on all public functions and classes.
- Use pathlib.Path instead of os.path for all file operations.
- Use logging module, not print(), for any output in library code.
## Project Structure
- `src/` — Package source code (importable modules)
- `src/data/` — Data loading, preprocessing, feature engineering
- `src/models/` — Model definitions and training loops
- `src/evaluation/` — Metrics, evaluation scripts, reporting
- `notebooks/` — Jupyter notebooks (exploratory only, not production)
- `configs/` — YAML experiment configs (Hydra or plain YAML)
- `scripts/` — CLI entry points for training, evaluation, inference
- `tests/` — Pytest tests
## Conventions
- Notebooks are for exploration only. Any reusable logic must be extracted to src/.
- Config-driven experiments. Hyperparameters go in YAML configs, not hardcoded.
- Reproducibility: always set random seeds. Log all experiment parameters.
- Data paths are never hardcoded. Use config files or environment variables.
- Large files (models, datasets) are in .gitignore. Use DVC or cloud storage.
## Commands
- `uv run pytest` — Run tests
- `uv run python scripts/train.py --config configs/baseline.yaml` — Train model
- `uv run python scripts/evaluate.py --checkpoint outputs/latest/` — Evaluate
## Do NOT
- Do not commit data files, model checkpoints, or notebooks with outputs.
- Do not use global variables for configuration. Pass configs explicitly.
- Do not use wildcard imports (`from module import *`).
- Do not train models in notebooks. Use scripts/ entry points.3. REST API Backend (FastAPI)
API projects need clear rules about endpoint patterns, validation, error handling, and database access. This template uses FastAPI, but the patterns apply to Express or any other framework with minor edits.
# Project
REST API built with FastAPI, SQLAlchemy 2.0 (async), PostgreSQL, and Pydantic v2.
## Tech Stack
- Framework: FastAPI 0.115+
- ORM: SQLAlchemy 2.0 with async sessions
- Validation: Pydantic v2 (model_validator, field_validator)
- Database: PostgreSQL 16
- Migrations: Alembic
- Auth: JWT with python-jose
- Testing: pytest + httpx (async)
## Code Style
- Type hints on every function. Use Pydantic models for request/response bodies.
- Async by default. Use `async def` for all route handlers and DB operations.
- Docstrings on all route handlers (they become OpenAPI descriptions).
- Max function length: 30 lines. Extract to service layer if longer.
## Architecture
- `app/routers/` — Route handlers grouped by resource. Thin layer: validate input, call service, return response.
- `app/services/` — Business logic. All database queries happen here.
- `app/models/` — SQLAlchemy ORM models.
- `app/schemas/` — Pydantic request/response schemas. Separate Create, Update, and Response schemas per resource.
- `app/core/` — Config, security, dependencies.
- `app/core/deps.py` — Dependency injection (get_db, get_current_user).
## Conventions
- Every endpoint returns a Pydantic response model. No raw dicts.
- Use dependency injection for DB sessions and auth. Never instantiate sessions in handlers.
- HTTP exceptions raised in services, not in route handlers.
- Alembic for all schema changes. Never modify the database manually.
- Pagination: use limit/offset with a max limit of 100.
## Commands
- `uvicorn app.main:app --reload` — Start dev server
- `pytest -x --asyncio-mode=auto` — Run tests
- `alembic upgrade head` — Apply migrations
- `alembic revision --autogenerate -m "description"` — Generate migration
## Do NOT
- Do not put business logic in route handlers. Use services.
- Do not return SQLAlchemy models directly. Convert to Pydantic schemas.
- Do not use synchronous database calls.
- Do not hardcode secrets. Use environment variables via app/core/config.py.4. Mobile App (React Native)
Mobile development has platform-specific pitfalls that Claude needs to know about. This template covers the navigation patterns, platform branching, and performance conventions that matter most.
# Project
Cross-platform mobile app built with React Native (Expo SDK 52), TypeScript, and Expo Router.
## Tech Stack
- Framework: React Native with Expo (managed workflow)
- Navigation: Expo Router (file-based routing)
- State: Zustand for global state, React Query for server state
- Styling: NativeWind (Tailwind CSS for React Native)
- API: REST with axios
- Testing: Jest + React Native Testing Library
## Code Style
- Functional components with arrow functions. No class components.
- TypeScript strict mode. No `any` types.
- Named exports for components. Default exports only for route screens.
- Use `StyleSheet.create()` or NativeWind classes. No inline style objects.
## Architecture
- `app/` — Expo Router screens and layouts
- `components/` — Reusable UI components
- `components/ui/` — Design system primitives (Button, Text, Card)
- `hooks/` — Custom hooks
- `stores/` — Zustand stores
- `services/` — API client and request functions
- `constants/` — Colors, spacing, config values
- `utils/` — Pure utility functions
## Platform Conventions
- Use `Platform.select()` or `.ios.tsx`/`.android.tsx` file extensions for platform-specific code.
- Always test on both iOS and Android. Mention which platform you tested if relevant.
- Use `SafeAreaView` from react-native-safe-area-context, not from react-native.
- Avoid heavy computation on the JS thread. Use `InteractionManager.runAfterInteractions` for deferred work.
- List components: use `FlashList` from @shopify/flash-list, not FlatList.
## Commands
- `npx expo start` — Start Expo dev server
- `npx expo run:ios` — Build and run on iOS simulator
- `npx expo run:android` — Build and run on Android emulator
- `npm test` — Run Jest tests
- `npx expo lint` — Lint check
## Do NOT
- Do not use `react-native-gesture-handler` directly. Use the Expo-compatible version.
- Do not add native modules without checking Expo compatibility first.
- Do not use `Alert.alert` for user-facing messages. Use the custom toast component in components/ui/Toast.
- Do not hardcode dimensions. Use responsive values from useWindowDimensions.5. DevOps / Infrastructure as Code
IaC projects are easy to get wrong with AI because small changes have big consequences. This template emphasizes safety, idempotency, and review requirements.
# Project
Infrastructure as Code for [project name]. AWS, Terraform, and GitHub Actions.
## Tech Stack
- IaC: Terraform 1.9+ with AWS provider
- CI/CD: GitHub Actions
- Containerization: Docker with multi-stage builds
- Monitoring: CloudWatch + Grafana
- Secrets: AWS Secrets Manager (never SSM Parameter Store)
## File Structure
- `terraform/` — Root Terraform configs
- `terraform/modules/` — Reusable Terraform modules
- `terraform/envs/` — Environment-specific tfvars (dev, staging, prod)
- `.github/workflows/` — CI/CD pipeline definitions
- `docker/` — Dockerfiles and compose files
- `scripts/` — Operational scripts (deploy, rollback, db-migrate)
## Terraform Conventions
- All resources must have tags: Name, Environment, Team, ManagedBy=terraform.
- Use modules for any resource group used more than once.
- State is stored in S3 with DynamoDB locking. Never use local state.
- Variable naming: snake_case. Outputs: descriptive names matching resource purpose.
- Pin all provider and module versions. No open-ended version constraints.
## Safety Rules
- Never modify production tfvars or prod workflow files without explicit approval.
- Always show `terraform plan` output before applying. Never auto-apply.
- Destructive changes (resource deletion, replacement) must be called out explicitly.
- Secrets are never written in Terraform files, tfvars, or workflow YAML. Use references to Secrets Manager.
- IAM policies: principle of least privilege. No wildcard (*) actions in production.
## Docker Conventions
- Multi-stage builds. Final image must use a distroless or alpine base.
- Non-root user in all containers. Never run as root.
- Pin base image versions by SHA digest, not just tag.
- HEALTHCHECK instruction required in every Dockerfile.
## Commands
- `terraform plan -var-file=envs/dev.tfvars` — Plan dev changes
- `terraform apply -var-file=envs/dev.tfvars` — Apply dev changes
- `docker build -f docker/Dockerfile -t app:local .` — Build container
- `act -j test` — Run GitHub Actions locally with act
## Do NOT
- Do not modify any file in `terraform/envs/prod/` without asking first.
- Do not use `terraform destroy` under any circumstances.
- Do not store credentials or secrets in any file. No exceptions.
- Do not create resources without cost estimation (use `infracost`).6. Open Source Library
Libraries have concerns that applications do not: public API surface, backwards compatibility, documentation, and contributor experience. This template covers what matters for publishing reusable code.
# Project
[Library name]: A TypeScript library for [purpose]. Published to npm as `@scope/package-name`.
## Tech Stack
- Language: TypeScript 5.x (strict mode)
- Build: tsup (ESM + CJS dual package)
- Test: Vitest
- Docs: TypeDoc (auto-generated from JSDoc/TSDoc)
- Package manager: pnpm
## Public API
- All public exports go through `src/index.ts`. No deep imports.
- Every public function and type must have a TSDoc comment with @param, @returns, and @example.
- Semantic versioning: breaking changes require major bump. New features minor. Fixes patch.
- Deprecations: use @deprecated JSDoc tag. Keep deprecated APIs for at least one minor version.
## Code Style
- Pure functions preferred. Minimize side effects.
- No runtime dependencies unless absolutely necessary. Check bundle size impact.
- Generics over `any`. Use type narrowing and inference.
- Error handling: throw typed errors extending a base `LibraryError` class. No string throws.
- Named exports only. No default exports.
## File Structure
- `src/` — Library source code
- `src/index.ts` — Public API barrel file
- `src/internal/` — Internal utilities (not exported)
- `tests/` — Test files matching src/ structure
- `benchmarks/` — Performance benchmarks
- `docs/` — Additional documentation
## Testing
- Every public function needs unit tests with edge cases.
- Tests mirror src/ structure: `src/parser.ts` -> `tests/parser.test.ts`.
- Run `pnpm test` before suggesting changes are complete.
- Test both ESM and CJS builds: `pnpm test:build`.
## Commands
- `pnpm dev` — Watch mode build
- `pnpm build` — Production build (ESM + CJS)
- `pnpm test` — Run Vitest
- `pnpm test:build` — Test built output
- `pnpm lint` — ESLint + type check
- `pnpm size` — Check bundle size with size-limit
## Do NOT
- Do not add runtime dependencies without discussing bundle size impact first.
- Do not change the public API signature without flagging it as a breaking change.
- Do not use Node.js-specific APIs unless the library is Node-only.
- Do not export internal utilities through src/index.ts.7. Monorepo (Turborepo)
Monorepos are where CLAUDE.md becomes essential. Without clear guidance, Claude will mix up packages, misapply conventions, and import across package boundaries incorrectly. This root-level template defines the shared rules, while each package should have its own CLAUDE.md for specifics.
# Monorepo
Turborepo monorepo with pnpm workspaces. Contains a Next.js web app, a React Native mobile app, a shared UI library, and backend API services.
## Structure
- `apps/web/` — Next.js 15 web application
- `apps/mobile/` — React Native (Expo) mobile app
- `apps/api/` — Fastify REST API
- `packages/ui/` — Shared component library (React)
- `packages/config/` — Shared ESLint, TypeScript, Tailwind configs
- `packages/db/` — Drizzle ORM schema and client (shared across apps/web and apps/api)
- `packages/types/` — Shared TypeScript types and Zod schemas
## Workspace Rules
- Import shared packages using workspace aliases: `@repo/ui`, `@repo/db`, `@repo/types`.
- Never import directly from another app. Apps can only share code through packages/.
- Changes to packages/types or packages/db affect multiple apps. Run tests for all dependents.
- Each package has its own tsconfig.json extending the base from packages/config.
## Code Style (Global)
- TypeScript strict mode everywhere. No `any`.
- pnpm only. No npm or yarn.
- Biome for formatting and linting (configured in biome.json at root).
- Commit messages: conventional commits (feat:, fix:, chore:, docs:).
## Commands
- `pnpm dev` — Start all apps in development
- `pnpm dev --filter=web` — Start only the web app
- `pnpm build` — Build all packages and apps
- `pnpm test` — Run tests across all workspaces
- `pnpm lint` — Lint all workspaces
- `turbo run build --filter=web...` — Build web app and its dependencies
## Adding Dependencies
- Root-level devDependencies only for build tools: `pnpm add -Dw <pkg>`
- App/package dependencies: `pnpm add <pkg> --filter=<workspace>`
- Shared dependencies must be the same version across workspaces. Check with `pnpm ls <pkg> -r`.
## Do NOT
- Do not install dependencies at root unless they are build/dev tools.
- Do not import between apps directly. Use packages/ for shared code.
- Do not modify packages/config without testing all downstream workspaces.
- Do not skip `turbo` for builds. Always use turborepo pipeline for caching.
- Do not add new workspaces without updating turbo.json pipeline.8. Documentation Site (Astro)
Documentation sites have different priorities than application code: content structure, navigation, cross-references, and build-time optimization matter more than runtime logic. This template uses Astro, but adapts easily to Docusaurus or other frameworks.
# Project
Documentation site built with Astro and Starlight. Hosted on Cloudflare Pages.
## Tech Stack
- Framework: Astro 5 with Starlight
- Content: Markdown and MDX in src/content/docs/
- Styling: Starlight theme with custom CSS overrides in src/styles/
- Search: Pagefind (built into Starlight)
- Deployment: Cloudflare Pages (auto-deploy on push to main)
## Content Structure
- `src/content/docs/` — All documentation pages
- `src/content/docs/guides/` — Step-by-step tutorials
- `src/content/docs/reference/` — API and configuration reference
- `src/content/docs/examples/` — Code examples and recipes
- `public/images/` — Static images (use descriptive filenames: feature-auth-flow.png)
## Writing Conventions
- Frontmatter required: title, description, sidebar (order and optional label).
- Use sentence case for headings ("Getting started", not "Getting Started").
- Code blocks must specify language. Use `title` attribute for filenames: ```ts title="src/config.ts"```.
- Internal links: use relative paths (`../guides/setup`) not full URLs.
- One concept per page. If a page exceeds 800 words, split it.
## Components (MDX)
- Import components in MDX files only when needed. Available: Tabs, Card, LinkCard, Code.
- Custom components live in `src/components/`. Use Astro components (.astro), not React.
- Aside syntax for callouts: `:::note`, `:::tip`, `:::caution`, `:::danger`.
## Commands
- `pnpm dev` — Start dev server with hot reload
- `pnpm build` — Production build (static site)
- `pnpm preview` — Preview production build locally
- `pnpm astro check` — Validate content and types
## SEO and Accessibility
- Every page needs a unique description in frontmatter (50-160 characters).
- Alt text required on all images. No decorative images without empty alt="".
- Table of contents auto-generated from h2/h3 headings. Do not use h4+ for important sections.
## Do NOT
- Do not use React components. Astro components only.
- Do not put images in src/. Use public/images/ for all static assets.
- Do not create pages outside src/content/docs/. Starlight manages routing.
- Do not edit the Starlight config (astro.config.mjs sidebar) without checking existing structure.9. Chrome Extension
Chrome extensions have a unique architecture with background scripts, content scripts, popups, and strict security constraints. Claude needs to understand these boundaries or it will produce code that fails silently.
# Project
Chrome extension (Manifest V3) built with TypeScript and React for the popup UI.
## Tech Stack
- Manifest: V3 (service worker, not background page)
- Language: TypeScript 5.x
- Popup UI: React 19 with Tailwind CSS
- Build: Vite with crxjs plugin
- Storage: chrome.storage.local (synced settings use chrome.storage.sync)
- Testing: Vitest for unit tests
## Architecture
- `src/background/` — Service worker. Handles events, alarms, and message passing.
- `src/content/` — Content scripts injected into web pages. Minimal DOM manipulation.
- `src/popup/` — React app rendered in the extension popup.
- `src/options/` — Options page (React).
- `src/lib/` — Shared utilities used across contexts.
- `src/types/` — TypeScript types for messages, storage schemas, and API responses.
## Extension-Specific Rules
- Content scripts and background scripts run in isolated contexts. Communicate via chrome.runtime.sendMessage.
- Define a typed message protocol in src/types/messages.ts. Every message has a `type` discriminator field.
- Service worker can go idle. Do not store state in variables; persist to chrome.storage.
- Content scripts: minimal footprint. Do not inject large libraries into host pages.
- Permissions: request only what is needed. Use optional_permissions for features that are not always active.
## Storage
- All chrome.storage keys defined in src/lib/storage.ts with typed getters/setters.
- Default values for every storage key. Never assume storage has data.
## Commands
- `pnpm dev` — Start Vite dev server with HMR for popup/options
- `pnpm build` — Production build to dist/
- `pnpm test` — Run Vitest tests
- Load unpacked: chrome://extensions -> Load dist/ folder
## Do NOT
- Do not use Manifest V2 APIs (background pages, chrome.browserAction).
- Do not use eval() or inline scripts. Chrome CSP forbids them.
- Do not request broad permissions ("tabs", "<all_urls>") unless justified.
- Do not store sensitive data in chrome.storage without encryption.
- Do not inject CSS globally from content scripts. Scope styles with Shadow DOM or unique prefixes.10. CLI Tool
CLI tools need clear conventions about argument parsing, output formatting, error handling, and cross-platform behavior. This template covers a Node.js CLI, but the structure applies to Go, Rust, or Python CLIs with minor adjustments.
# Project
CLI tool written in TypeScript. Distributed via npm as a global binary (`npx toolname`).
## Tech Stack
- Language: TypeScript 5.x
- Runtime: Node.js 20+ (ESM)
- Argument parsing: Commander.js
- Output: chalk for colors, ora for spinners
- Config files: cosmiconfig (supports .toolnamerc, toolname.config.ts, etc.)
- Build: tsup (single ESM bundle with shebang)
- Testing: Vitest
## File Structure
- `src/cli.ts` — Entry point. Defines commands with Commander. No business logic here.
- `src/commands/` — One file per command (init.ts, build.ts, lint.ts).
- `src/core/` — Business logic called by commands. Framework-agnostic, testable.
- `src/utils/` — Shared utilities (file I/O, logging, config loading).
- `src/types/` — TypeScript types and interfaces.
- `bin/` — Built executable output.
## CLI Conventions
- Commands follow the pattern: `toolname <command> [options]`. No positional args for main actions.
- Every command has --help with examples. Commander description + .addHelpText('after', ...).
- Exit codes: 0 = success, 1 = user error (bad input), 2 = runtime error (bug/crash).
- Stdout is for machine-readable output (JSON, paths). Stderr for human messages (logs, progress).
- Support --json flag on all commands for CI-friendly output. Disable colors when --json or NO_COLOR is set.
## Error Handling
- Wrap command handlers in try/catch. Format errors with context for the user.
- User-facing errors: class UserError extends Error. Show message only, no stack.
- Unexpected errors: log full stack to stderr, suggest filing a bug report.
- Never call process.exit() in library code. Only in src/cli.ts top-level handler.
## Commands
- `pnpm dev` — Watch mode build
- `pnpm build` — Production build to bin/
- `pnpm test` — Run Vitest
- `pnpm link --global` — Install locally for testing
- `node bin/toolname.js <command>` — Run local build directly
## Do NOT
- Do not use console.log for user-facing output. Use the logger in src/utils/logger.ts.
- Do not read/write files synchronously. Use async fs throughout.
- Do not assume Unix. Use path.join(), os.homedir(), and cross-platform utilities.
- Do not bundle unnecessary dependencies. Keep the install size small.Tips for Customizing These Templates
These templates are starting points, not final versions. Here is how to make them work for your specific project.
Replace the generic descriptions immediately. Every template starts with a placeholder project description. Replace it with your actual project name, purpose, and tech choices. The more specific this section is, the better Claude understands your context.
Add your actual file structure. The file structures in these templates are conventional defaults. Your project almost certainly has some deviations. Update the structure section to match reality, especially if you have unusual directory names or nested packages.
Include your real commands. The dev/build/test commands in these templates use common defaults. Replace them with the exact commands your team uses. If you have a Makefile or task runner with custom targets, list those instead.
Add project-specific prohibitions. The “Do NOT” sections in these templates cover common mistakes. Add your own. If Claude keeps making the same error in your project — wrong import path, deprecated API, forbidden pattern — put it in the Do NOT section. Negative instructions are among the most effective rules you can write.
Keep it under 500 lines. As we noted in our CLAUDE.md guide, longer files dilute the important rules. If your project needs more detail than fits in one file, use subdirectory CLAUDE.md files for package-specific rules.
Add code examples for your patterns. If your project has a specific way of writing components, handlers, or tests, show a 5-10 line example. Claude follows concrete examples more reliably than abstract descriptions.
Update it regularly. Your CLAUDE.md should change as your project evolves. When you find yourself correcting Claude about something more than once, add it to the file. When a convention changes, update the file the same day.
Combine templates for hybrid projects. Building a Next.js app with a CLI? Merge the relevant sections from both templates. The headers and structure are designed to be composable.
Browse our full gallery of CLAUDE.md files to see how real open-source projects implement these patterns at scale, or read our complete guide to writing CLAUDE.md for the underlying principles behind every template here.