CLAUDE.md Examples and Templates (2026)

A useful CLAUDE.md is a short, version-controlled operating guide for Claude Code. It tells the agent how this repository is built, where important code lives, which commands prove a change works, and which project-specific rules it cannot infer from the files alone.

The templates below are starting points, not documents to paste unchanged. Keep only instructions that prevent a real mistake in your project. If you are still setting up the CLI, start with the Claude Code installation guide, then return here once claude runs inside your repository.

What Is a CLAUDE.md File For?

CLAUDE.md gives Claude Code persistent instructions for a user, project, or directory. Claude loads the relevant files as context, so the same build commands, architecture constraints, and repository etiquette do not need to be repeated in every session.

It is guidance, not an enforcement mechanism. A sentence such as “run the API tests before finishing” helps Claude choose the right validation, but it does not technically prevent Claude from skipping the command. Put hard controls in permissions, sandbox settings, or hooks. Anthropic makes that distinction explicit in its project memory documentation.

Claude Code can generate an initial file with /init. That is useful for discovery, but the output still needs an owner to remove obvious information and add the decisions only your team knows.

A Minimal CLAUDE.md Template

Start with five sections: purpose, map, commands, conventions, and verification. This is enough context for most small repositories and stays easy to audit.

# Project guide

## Purpose
- This repository builds [one-sentence product description].
- The primary user flow is [critical path].

## Repository map
- src/app/: routes and server entry points
- src/components/: reusable UI
- src/lib/: shared domain logic
- scripts/: maintenance and validation commands

## Commands
- Install: pnpm install
- Develop: pnpm dev
- Lint: pnpm lint
- Build: pnpm build

## Conventions
- Use TypeScript with 2-space indentation.
- Prefer named exports for reusable components.
- Keep server-only credentials out of client modules.
- Preserve unrelated changes in a dirty worktree.

## Before finishing
- Run pnpm lint and pnpm build.
- Manually verify every affected route.
- Report anything you could not validate.

Replace every bracketed line and delete sections that add no new information. A package script already visible in package.json may still be worth naming when it is the required acceptance gate. A generic rule such as “write clean code” is never worth keeping because nobody can verify it.

CLAUDE.md Example for Next.js

A Next.js CLAUDE.md should identify the routing model, client boundary, data source, and route-level validation. Those choices prevent more mistakes than a long list of React style preferences.

# Next.js application

## Architecture
- Use the App Router under src/app/.
- Keep pages and layouts as Server Components by default.
- Add "use client" only for hooks, browser APIs, or interactive state.
- Read editorial data from src/data/. Do not duplicate registries.

## UI
- Reuse components from src/components/ before creating a new primitive.
- Use next/link for internal navigation and next/image for content images.
- Preserve keyboard navigation and visible focus states.

## Data and security
- Read secrets only in server modules and route handlers.
- Validate request bodies at the server boundary.
- Never expose provider credentials or internal error payloads to the browser.

## Validation
- Run pnpm lint.
- Run pnpm build.
- Verify changed static and dynamic routes in pnpm dev.

Notice what the example leaves out: explanations of React, a list of every component, and rules the formatter already enforces. The file records local decisions. My guide to structuring projects for AI agents goes deeper on making those decisions discoverable in the codebase itself.

CLAUDE.md Example for Python

A Python CLAUDE.md should name the environment manager, package layout, type checker, test runner, and integration-test boundary. Claude otherwise has to guess among several equally common conventions.

# Python service

## Environment
- Python 3.13 is the supported runtime.
- Use uv for dependencies and virtual environments.
- Run commands with uv run instead of activating a shell manually.

## Layout
- Application code lives in src/service/.
- HTTP routes belong in src/service/api/.
- Domain logic must not import from the API layer.
- Tests mirror the source tree under tests/.

## Quality
- Format and lint: uv run ruff check .
- Type check: uv run pyright
- Unit tests: uv run pytest tests/unit
- Full tests: uv run pytest

## Test rules
- Unit tests may mock network clients.
- Integration tests use recorded fixtures, not live production services.
- Add a regression test for every bug fix.

Match the commands to the repository. If the project uses Poetry, Hatch, mypy, or unittest, say so directly. Do not list several alternatives and ask Claude to choose on every task.

CLAUDE.md Example for a Monorepo

A monorepo works best with a small root CLAUDE.md for shared rules and narrower instructions near each package. This keeps frontend rules out of backend tasks and reduces contradictions.

# Monorepo guide

## Workspace
- pnpm workspaces and Turborepo manage all packages.
- apps/web is the customer application.
- apps/api is the HTTP service.
- packages/ui contains shared UI primitives.
- packages/contracts owns shared request and event schemas.

## Shared rules
- Change contracts before updating their producers and consumers.
- Do not import application code across apps.
- Run the narrow package checks first, then the root build.

## Commands
- All lint checks: pnpm lint
- All builds: pnpm build
- Web only: pnpm --filter web build
- API only: pnpm --filter api test

Put package-specific guidance in a nested CLAUDE.md or a path-scoped file under .claude/rules/. Anthropic's current documentation says nested files load when Claude reads files in that directory, while path-scoped rules load when matching files enter the task. Use the configuration debugger when a nested rule appears to be missing.

Where CLAUDE.md Files Go

Put shared project instructions at the repository root and personal preferences in your user-level file. Use local or nested files only when their narrower scope is intentional.

Run /memory inside Claude Code to see which instruction files are loaded. That check is faster and more reliable than assuming a filename or directory is being discovered.

Are AGENTS.md and CLAUDE.md the Same?

No. AGENTS.md and CLAUDE.md are separate instruction-file conventions, and Claude Code reads CLAUDE.md directly. A repository can still share one set of instructions by importing AGENTS.md or using a symlink.

How CLAUDE.md Imports Work

CLAUDE.md imports another file with @path/to/file. Imports let one source of truth serve Claude Code and other coding agents without copying the same rules.

@AGENTS.md

## Claude Code
- Use plan mode for changes that alter billing or authentication.
- Run /memory when project instructions appear stale.

Anthropic recommends importing an existing AGENTS.md from CLAUDE.md, or using a symlink when no Claude-specific additions are needed. Relative imports resolve from the file containing the import.

What Belongs in CLAUDE.md?

Include information that changes how Claude should work and that cannot be recovered cheaply from the repository. Every rule should be specific enough for a reviewer to verify.

• The product's purpose and the critical user or data flow.
• The smallest useful map of important directories and ownership.
• Exact install, development, test, lint, build, and release commands.
• Architecture decisions with real alternatives, such as App Router instead of Pages Router.
• Security boundaries, generated-file rules, and state that must remain server-only.
• Validation requirements and the evidence expected at handoff.

The complete Claude Code guide covers how CLAUDE.md fits beside plan mode, hooks, skills, subagents, and worktrees. Those tools solve different problems, so do not force every workflow into this one file.

What Should Stay Out?

Exclude secrets, generic advice, duplicated reference documentation, volatile status, and rules already enforced automatically. Those lines consume context without making the next action clearer.

• Never include API keys, tokens, passwords, or private URLs.
• Do not paste the full repository tree or API documentation.
• Do not describe standard language syntax Claude already knows.
• Do not store a temporary task list that becomes wrong after one PR.
• Do not duplicate formatter rules when running the formatter is clearer.

Move conditional procedures into skills, enforced commands into hooks, and machine-local preferences into ~/.claude/CLAUDE.md orCLAUDE.local.md. A smaller project file is easier for a team to trust.

How Long Is Too Long for CLAUDE.md?

Anthropic recommends keeping each CLAUDE.md under 200 lines. Longer files consume more startup context and make individual instructions easier to miss, especially when several scopes load together.

The useful limit is usually lower. If a section applies only to one package or file type, move it to a nested file or path-scoped rule. If a paragraph explains a concept rather than directing work, link the canonical documentation instead.

Is CLAUDE.md Really Useful?

Yes, when it prevents repeated repository-specific mistakes. It is less useful when it restates obvious code, contains conflicting rules, or becomes a dumping ground for every preference anyone has mentioned.

Measure usefulness by behavior. Track the mistakes you repeatedly correct, add one concrete rule, and see whether the next comparable task improves. If the rule does not change outcomes after several sessions, rewrite or remove it.

A Practical CLAUDE.md Audit

Audit CLAUDE.md by checking discovery, specificity, freshness, conflicts, and enforcement. Ten focused minutes usually removes more confusion than adding another page of instructions.

1. Run /memory and confirm every expected file is loaded.
2. Replace vague verbs such as “handle” and “properly” with observable actions.
3. Run every documented command and delete obsolete ones.
4. Compare root, local, nested, and imported rules for contradictions.
5. Move hard safety requirements into settings, permissions, or hooks.
6. Remove any line whose deletion would not plausibly cause a mistake.

Revisit the file after a tooling migration or architecture change, not on an arbitrary schedule. For broader workflow patterns after the instructions are solid, use the Claude Code topic hub to move from setup into planning, agent teams, hooks, and real project examples.