lockstep
6 min readNaman Jain

CLAUDE.md examples and template (Python, React, monorepo)

A CLAUDE.md template plus real examples for Python, React, and a monorepo, built on Anthropic's rule: only write what Claude can't find by reading the repo.

Most CLAUDE.md files start the same way: a paragraph about the project, a directory tree, a list of dependencies, and twenty style rules. Claude could have found almost all of it by reading the code. Meanwhile the one thing it couldn't find, that integration tests need a local Redis and the TEST_STRIPE_KEY variable, isn't there.

This guide gives you a template and three examples built on one rule from Anthropic's own best practices, checked on 16 November 2026: only write down what Claude can't find by reading the repo, or what it would otherwise spend time rediscovering every session.

The one test for every line

Anthropic's best practices suggest asking two questions before you write anything down:

  1. Could Claude find this by reading the code?
  2. Would it actually go and look?

If both answers are yes, leave it out. Current models are good at finding your file layout, conventions, and test framework on their own. What they can't find is information that was never in the repo. The documentation's own examples: a decision your team made in a meeting, a deploy process that lives in one person's head, and the environment variable your integration tests need.

The template

# CLAUDE.md

## Commands
- Install: [command, with any non-obvious flags]
- Test: [command]; one file: [command]
- Lint and typecheck: [command]. Run before every commit.

## Environment
- [Services or variables tests and dev need, and where to get them]

## Gotchas
- [Things that look wrong but are intentional, and why]
- [Things that break in non-obvious ways]

## Decisions
- [Decision made outside the code, with a link to where it was made]

## Workflow
- [Branching, PR, and deploy steps Claude can't infer]

## More context
- Area rules live in .claude/rules/. Procedures live in .claude/skills/.

Keep it under 200 lines, which is Anthropic's recommendation. Run /init if you want Claude to generate a first draft from your codebase, then cut what it could have found anyway.

Example 1: a Python service

# CLAUDE.md

## Commands
- Install: `uv sync --all-extras` (not pip; the lockfile is uv.lock)
- Test: `uv run pytest -x`; one file: `uv run pytest tests/test_billing.py`
- Lint: `uv run ruff check . && uv run mypy src` before every commit

## Environment
- Integration tests need Redis on localhost:6379: `docker compose up redis`
- Set TEST_STRIPE_KEY from 1Password ("Stripe test key"). Never a live key.

## Gotchas
- `amount` fields are integer cents everywhere. Never floats.
- `src/legacy/` is frozen until the Q1 migration. Don't refactor it.
- The retry in `charge()` is intentional: one provider times out on first call.

## Decisions
- Refunds over $500 need manual approval (decided with Finance, see
  docs/decisions/refund-limits.md). Don't add an auto-approve path.

## Workflow
- Branch from main, open a PR, never push to main.
- Migrations: `uv run alembic revision --autogenerate`, then review the file.

Notice what is missing: no directory tree, no "we use FastAPI", no "write clean code". Claude finds the first two in seconds and the third means nothing.

Example 2: a React and Next.js app

# CLAUDE.md

## Commands
- Install: `pnpm install` (never npm or yarn)
- Dev: `pnpm dev` (port 3000). Tests: `pnpm test`. E2E: `pnpm e2e` needs `pnpm dev` running.
- Before a PR: `pnpm lint && pnpm typecheck && pnpm test`

## Environment
- Copy .env.example to .env.local. NEXT_PUBLIC_API_URL points at staging by default.

## Gotchas
- Use components from src/components/ui before writing new ones.
- Colors, spacing, and font sizes come from tokens in src/styles/tokens.ts. No raw values.
- Server-only code imports "server-only" at the top.

## Decisions
- No modals in the mobile checkout (design review, 3 Nov). Use full pages.

## More context
- UI rules: .claude/rules/ui.md (loads for src/components/** and src/app/**)

The UI rules sit in a separate file with a paths filter, so they load only when Claude works on UI files. That keeps the main file short.

Example 3: a monorepo

In a monorepo, split by directory. Claude Code loads CLAUDE.md from the directory you launch in and every directory above it, and loads a subdirectory's CLAUDE.md when it works on files there.

Root CLAUDE.md:

# CLAUDE.md (root)

## Commands
- Install: `pnpm install` at the root. Build one package: `pnpm --filter @acme/api build`
- Test everything: `pnpm test`. CI runs `pnpm turbo run test lint typecheck`.

## Workflow
- One package per PR when possible. Changes to packages/shared need a reviewer from each consuming team.

## Packages
- apps/web, apps/api, packages/shared. Each has its own CLAUDE.md.

apps/api/CLAUDE.md:

# CLAUDE.md (apps/api)

## Commands
- Dev: `pnpm --filter @acme/api dev` (port 4000). Needs Postgres: `docker compose up db`.

## Gotchas
- Errors use problem+json via httpError() in src/errors.ts.
- The audit_events table is append-only. Corrections are new rows.

If other teams' CLAUDE.md files get picked up when you don't want them, the claudeMdExcludes setting skips them.

What to move out of CLAUDE.md

If the line is...Put it inWhy
Only relevant to one part of the code.claude/rules/ with pathsLoads only when Claude touches matching files
A multi-step procedureA skill in .claude/skills/The body loads only when used
A rule with no exceptionsA hook or a permission ruleRuns regardless of what Claude decides
Your personal preferenceCLAUDE.local.md, in .gitignoreStays out of the team's file
Something Claude can read in the codeNowhereIt will find it

Anthropic's best practices add one more point: if Claude keeps ignoring a line, adding IMPORTANT probably won't fix it. Either the file has grown too long, or the line is a rule that can't have exceptions and belongs in a hook. For the full list of causes, see why Claude Code ignores your CLAUDE.md. For hook examples, see Claude Code hooks: 6 examples.

The section that goes stale fastest

Look at the Decisions section in each example. It is the most valuable part of the file, because it is the information Claude can't find anywhere in the code. It is also the part that goes stale first. "No modals in the mobile checkout" was true on 3 November. If the design team changes its mind in a Slack thread, nobody edits CLAUDE.md, and every agent keeps following the old rule.

Keep only a handful of long-lived decisions in the file, each with a link to where it was made. Decisions that change often need an owner and a status, not a line in a markdown file.

Where Lockstep fits

Lockstep keeps the Decisions section current for you. It captures decisions from PRDs, Slack threads, and pull requests, and each becomes binding when its owner approves it. At the start of each Claude Code session, Lockstep briefs the agent on the decisions that apply to the work, so they don't need to live in CLAUDE.md. When a decision changes, the new version replaces the old one.

Keep everything else in CLAUDE.md: commands, environment, gotchas. Session briefings work with Claude Code today. See how it works.

Sources checked 16 November 2026

For how CLAUDE.md loads and its limits, see how Claude Code memory works. For the shared alternative most agents read, see AGENTS.md vs CLAUDE.md. For the definition, see CLAUDE.md. For Anthropic's wider guidance, see Claude Code best practices. For onboarding people as well as agents, see the engineering onboarding checklist. For instruction files in large repositories, see monorepo vs polyrepo. For which memory file to use, see CLAUDE.md vs CLAUDE.local.md vs auto memory.

Frequently asked questions

What should a CLAUDE.md file contain?
Only what Claude can't find by reading the repository, or would have to rediscover every session: commands with non-obvious flags, environment variables tests need, deploy steps, gotchas, and decisions made outside the code. Anthropic's best practices say to leave out anything Claude would find and actually go look for.
Is there an official CLAUDE.md template?
Running /init in Claude Code generates a starting CLAUDE.md from your codebase, and suggests improvements if one already exists. There is no required format; any markdown with clear headings and bullets works.
How long should a CLAUDE.md be?
Under 200 lines per file, per Anthropic's documentation. Longer files use more context and are followed less reliably. Move rules for one part of the codebase into .claude/rules/ with a paths filter, and multi-step procedures into skills.
Should I write IMPORTANT in CLAUDE.md?
Usually it won't help. Anthropic's best practices say that if Claude keeps ignoring a line, either the file is too long or the rule can't have exceptions, in which case it belongs in a hook, not in stronger wording.
What is the difference between CLAUDE.md and CLAUDE.local.md?
CLAUDE.md is committed and shared with the team. CLAUDE.local.md holds your personal, project-specific notes, such as your sandbox URL, and should be added to .gitignore so it stays out of the repo.

Keep reading