CLAUDE.md Examples

Quick Answer

CLAUDE.md is a markdown file at your repo root that Claude Code loads into every session. It sets language rules, test commands, folder layout, and team conventions. Aim for 150 to 400 words. The 10 templates below cover Node, Next.js, Python, monorepo, library, team, security, data science, mobile, and MVP projects. TLDR: pick the closest match, copy 5 to 10 rules, iterate weekly.

Summary of the 10 templates

1. Minimal Node or TypeScript - 5 rules for small projects
2. Next.js App Router - 6 rules covering server components and image handling
3. Python FastAPI - 7 rules for tooling, type hints, and DB safety
4. Monorepo - ownership map and cross-package import rules
5. Open source library - changelog, semver, and dependency rules
6. Team project - ticket IDs, PR approvals, and staging gates
7. Security-sensitive - secrets, audits, and PII inventory
8. Data science - notebook paths, seeds, and data layout
9. Mobile app - platform targets and device testing
10. Startup MVP - ship velocity over code polish

CLAUDE.md is the single most useful file in a Claude Code project. It gets injected into every session before your first prompt runs. Good contents save a dozen rounds of clarification per task. Bad or missing contents force Claude to guess conventions and pick the wrong ones. The difference between a project with a thoughtful CLAUDE.md and one without is the difference between a collaborator who already knows your codebase and a new hire on day one who has not yet read the onboarding wiki.

This page walks through what CLAUDE.md does, the import syntax, ten copy-ready templates for common stacks, and what to keep out of the file.

What CLAUDE.md does

When you run the claude command in a repo, the agent walks up the directory tree and loads every CLAUDE.md it finds, starting at the working directory and ending at the home folder. All of those files get concatenated into the system prompt of every turn. That has two direct consequences. First, rules in CLAUDE.md are always active, whether the user mentions them or not.

Second, every token in CLAUDE.md costs you on every turn. A 2000-word CLAUDE.md costs roughly one to two cents extra per turn on Sonnet. Most teams land around 150 to 400 words at the repo root and accept that cost as a fair trade for fewer back-and-forth clarifications. Teams that bloat the file to 3000 words often regret it the first time they review a monthly API bill.

A common pattern is to keep the repo-root file short and rule-focused, and to link out to deeper docs via the import syntax. That gives Claude enough context to act correctly on first try, without paying for every architecture essay on every turn.

The import syntax

Inside a CLAUDE.md you can reference another file with an at-sign prefix. Put the path on its own line and Claude will load that file inline the first time the session starts. Imports are resolved once per session and cached. Use them when a doc is large enough that you only want it pulled in when the agent is about to do something that needs it.

A frequent top-line convention is a reference to a shared AGENTS.md. Many teams write AGENTS.md as the canonical project guide and use CLAUDE.md only to add Claude-specific rules on top. That avoids duplicating the same content in two places.

Global vs project CLAUDE.md

Two locations matter in practice. The first is your personal global file in the home directory Claude config folder. The second is the repo-level file checked into git. Keep personal style in the global one: preferred commit message format, editor choice, how you like explanations written. Keep project rules in the repo file: language version, test commands, folder layout, review rules, deploy process.

If there is a conflict between the two, the repo file wins because it loads last and the model gives more weight to later content. In practice conflicts are rare because the files serve different purposes.

Ten templates

Below are ten starting points. Pick the closest match for your stack, then trim the parts that do not apply and extend the parts that do.

1. Minimal Node or TypeScript project

A minimal file is often the right answer. If your project has two commands, one folder, and one language, five lines of rules is plenty. Start with the test command, the lint command, the commit style, and a note to run tests before proposing a commit.

# Project Rules

- Language: TypeScript strict mode, no `any`.
- Test command: `pnpm test`.
- Lint command: `pnpm lint`.
- Commit style: conventional commits (feat, fix, chore).
- Run the tests before proposing a commit.

Five lines. Enough to prevent the most common friction on a small Node or TS project. Add rules as you notice recurring corrections.

2. Next.js App Router project

Next.js projects often mix the old pages router and the new app router. Be explicit about which one applies. Also be explicit about server vs client components because the default behavior changes the answer to almost every question Claude is asked.

# Rules

- Framework: Next.js 15, App Router only. No pages directory.
- Server components by default. Add `use client` only when hooks are required.
- TypeScript strict, zero `any`.
- Folder layout: `src/app` for routes, `src/components` for UI, `src/lib` for pure logic.
- Tests: `pnpm test` (Vitest). E2E: `pnpm e2e` (Playwright).
- Use `next/image` for images. Never raw `<img>`.

3. Python FastAPI project

Python projects benefit from explicit tooling rules because the ecosystem has five ways to do everything. Pin the Python version, the package manager, the formatter, the linter, and the migration command. Ban writes to the production database from tests.

# Rules

- Python 3.12 in a uv-managed venv.
- Type hints on every function signature.
- Format with ruff: `uv run ruff format .`.
- Lint with ruff: `uv run ruff check .`.
- Tests: `uv run pytest`.
- Migrations: `uv run alembic upgrade head`.
- Never write to production DB from a test.

4. Monorepo with multiple packages

Monorepos confuse coding agents more than any other shape of project. Claude reads a file and has to guess which package it lives in. A short ownership map at the top of CLAUDE.md cuts this confusion in half. Make it obvious which package owns what and state the import rules between packages.

# Monorepo Rules

- Package manager: pnpm with workspaces.
- Builds use Turborepo: `pnpm turbo build`.
- Test a single package: `pnpm --filter <pkg> test`.
- Ownership:
  - `packages/api` - backend, Postgres schema lives here
  - `packages/web` - Next.js frontend
  - `packages/shared` - pure TS types and utils, no IO
- Never import from `web` into `api` or vice versa. Shared code goes through `shared`.

5. Open source library

Library projects care about semver, changelog hygiene, and reviewer expectations. Put those upfront. A Claude contribution that ignores the changelog rule costs more review time than the one extra rule took to write.

# Contributor Rules

- Every PR needs a changelog entry in `CHANGELOG.md` under Unreleased.
- Public API changes need a version bump proposal (major/minor/patch).
- Tests required for every new feature and bug fix.
- Docs live in `docs/`. Update the relevant page when behavior changes.
- Semver: breaking changes only in major versions.
- License: MIT. Do not add GPL dependencies.

6. Team project with a sprint cadence

Teams with a ticketing system want branch names and PR titles to include the ticket ID. Teams with a staging environment want main-branch merges gated on a green staging deploy. Teams with code owners want two approvals on sensitive files. Spell out each of these rules.

# Team Rules

- Every branch name starts with the Linear ticket: `eng-1234-short-description`.
- PRs reference the ticket in the title and body.
- Deploys go through staging first. Never merge to main without green staging.
- Two approvals required on PRs touching `src/billing/` or `src/auth/`.
- Code owners are enforced via GitHub. Respect the assignment.

7. Security-sensitive project

Security projects need explicit prohibitions. An agent that commits a secret in a fintech repo is a real incident. Scan with gitleaks. Audit dependencies. Keep the env file ignored. List PII fields in a shared inventory. These rules exist for a reason, and stating them keeps Claude within bounds.

# Security Rules

- Never commit a secret. Scan with `gitleaks detect` before every commit.
- Run `pnpm audit` and resolve critical issues before merging.
- No dependencies without review. New deps need an architecture note.
- `.env.local` only. Never create an `.env` file at the repo root.
- PII fields must be listed in `docs/data-inventory.md` when added.
- Auth tokens use the shared helper in `lib/auth`. No raw jwt handling.

8. Data science project

Data projects mix notebooks, scripts, raw data, and models in the same tree. Without rules, Claude writes outputs wherever seems convenient and commits datasets by accident. Pin each data path and remind the agent to clear notebook outputs before commit.

# Notebook Rules

- Notebooks live in `notebooks/`. Clear output cells before commit.
- Raw data goes to `data/raw/` and is git-ignored.
- Processed data goes to `data/processed/` with a generator script in `scripts/`.
- Models save to `models/` with a timestamped name.
- Always set a random seed at the top of the notebook.
- Python 3.11 via uv. `uv run jupyter lab` to launch.

9. Mobile app

Mobile teams need platform targets stated explicitly. iOS 16 and Android 12 support different API surfaces than iOS 13 and Android 9. Pin the build command and the device targets you test against so Claude does not propose features that break on older devices.

# Mobile Rules

- React Native via Expo, SDK 52.
- Target platforms: iOS 16+, Android 12+.
- Build command: `pnpm expo prebuild && pnpm ios` or `pnpm android`.
- Tests: `pnpm test` runs Jest on JS logic only.
- Device testing for native features: iPhone 14 and Pixel 7.
- Never hardcode API URLs. Use `app.config.ts` env.

10. Startup MVP

MVP projects optimize for shipping. Tell Claude to skip premature abstractions. Name the stack you standardized on (auth, payments, database) and forbid rolling your own. Gate tests to the parts of the codebase where bugs are expensive.

# MVP Rules

- Ship velocity over code polish. A working feature beats a clean abstraction.
- Skip: premature TypeScript generics, abstract base classes, custom hooks for one-time code.
- Always: auth via Clerk, payments via Stripe, DB via Supabase. No rolling our own.
- Tests required only for `src/billing` and `src/auth`.
- Feature flags via ConfigCat. Ship behind a flag, expand rollout later.

What NOT to put in CLAUDE.md

Treat CLAUDE.md as a rules file, not a knowledge base. The following content belongs elsewhere.

Full API references bloat the token count for every turn. Import the raw docs with a link if the agent needs them, or let Claude fetch the docs on demand. Long architecture essays also do not belong here. Summarize in three bullets and put the rest in a dedicated architecture doc referenced from CLAUDE.md.

Dependency lists are redundant. The package manifest already declares them. Historical changelog content belongs in git. Every style preference you have ever had does not belong either. Start with five rules and add more when you catch yourself repeating a correction.

A good CLAUDE.md reads like the first page of an onboarding wiki. Rules first, commands next, and one or two pointers to deeper docs at the bottom.

Testing that CLAUDE.md is active

After editing CLAUDE.md, confirm it actually loads. Run the agent in the repo and ask it to paraphrase the rules it loaded. If the paraphrase does not match what you just wrote, the file is not at the expected path. Check the working directory first, then walk the parent tree.

The /status command also shows the active CLAUDE.md paths in recent versions. A faster sanity check is to add a deliberate joke rule (greet the user in pirate accent). Run the agent, send a prompt, and confirm the response arrives in pirate. Remove the joke rule afterwards.

Layering global and project files

Example stack for a real workflow. Your personal global file holds forty words about explanation style. The repo root file holds two hundred words about language, test command, and folder layout. A service-specific subfolder file holds eighty words about the migration command and helper locations.

When you run the agent inside the service subfolder, all three files load in order. The most specific file wins for contradictions, and general rules from the global file still apply. This layering scales well: large monorepos often ship ten or more CLAUDE.md files across different subdirectories.

Iterating on CLAUDE.md

Better CLAUDE.md files come from noticing mistakes. Every time you correct Claude on something that should have been obvious, ask yourself whether it is a one-time issue or whether it will repeat. If it will repeat, add a rule.

After a week, review the file. Drop rules that stopped mattering. Merge rules that overlap. Keep the count under twenty for the repo root file. Any single rule over three lines probably belongs in an imported doc instead.

Teams that treat CLAUDE.md like a living document hit a steady state at roughly 250 to 400 words and rarely edit it after that. Teams that never touch the file after initial setup pay a tax every single session in rework and retries.

Writing the first version takes twenty minutes. Maintaining it takes a five-minute review every two weeks. That is the cheapest investment in your Claude Code setup, and it compounds on every task the agent picks up.