CLAUDE.md Examples That Actually Work

CLAUDE.md is Claude Code's project instruction file — loaded into context at the start of every session in your repo. It's the highest-leverage file in the repository: a hundred good lines shape thousands of agent decisions. Here are four examples that hold up in real use, where Claude Code actually looks for this file, and the patterns that quietly break it.

Example 1 — Next.js app

Why it works: every line is checkable. "Run pnpm lint" either happened or didn't. Compare that with "write clean code" — which an agent can neither follow nor violate measurably.

Example 2 — Python API

The /internal/* line is the kind that earns its place: it looks like a security bug to a fresh reader, and an uninformed agent would "fix" it.

Example 3 — Monorepo

Example 4 — Small CLI or library

Single-package projects need less structure, not more — the whole point is that there's no architecture to explain.

Twelve lines of substance. Nothing here restates what package.json already says.

Where Claude Code looks for CLAUDE.md

Claude Code loads more than one file, and knowing the set helps you decide where a given rule belongs:

Project and local files load from your working directory and every directory above it as soon as a session starts; a subdirectory's own CLAUDE.md loads on demand, the moment Claude reads a file underneath it. Your personal ~/.claude/CLAUDE.md applies to everything you touch, everywhere — put per-machine habits there, not project facts. CLAUDE.local.md is the release valve for the notes that are true for you but wrong for a teammate: a local database URL, a preferred test fixture, a scratch note you don't want reviewed. It loads alongside CLAUDE.md and is treated the same way — just keep it out of git. Organizations can also deploy a managed, org-wide CLAUDE.md that individual settings can't opt out of — the same mechanism IT teams use to push a security policy to every machine, out of scope for most teams but worth knowing exists if you're on one.

When files disagree

Multiple CLAUDE.md files are concatenated into context, not merged into one ruleset — nothing overrides anything automatically. If a root-level file and a subdirectory file give conflicting instructions, Claude may pick one arbitrarily rather than reconcile them for you, the same failure mode two contradicting bullets inside one file already have. This matters most in a monorepo like Example 3: a package's own CLAUDE.md should narrow or extend the root file, not quietly contradict it. If you're picking up ancestor CLAUDE.md files from a part of a large monorepo that isn't yours, they can be excluded per project or per user rather than edited out of a shared file — worth reaching for before you're tempted to just delete someone else's rules.

Importing other files with @path

A CLAUDE.md doesn't have to contain everything inline. Reference another file with @path/to/file and Claude expands it into context at session start:

Both relative and absolute paths work; a relative path resolves against the file doing the importing, not your current directory. Imports can chain — an imported file can import another — up to four hops deep before Claude Code stops following the chain. Import parsing skips code spans and fenced code blocks, so if you want to mention a path without triggering an import, wrap it in backticks and it stays literal text instead of pulling the file in.

Drafting a first file with /init

If a repo has no CLAUDE.md yet, run /init inside a Claude Code session. It reads the codebase and writes a starting file with the build commands, test instructions, and conventions it can actually discover. If a CLAUDE.md already exists, /init proposes improvements instead of overwriting it, so it's safe to rerun after a big refactor. Treat its output as a first draft, not a finished file — it can't know that the /internal/* routes in Example 2 are intentional; only you can add that. If you'd rather start from vetted examples than a blank prompt, the Groundrules builder assembles a first draft from curated blocks instead of /init's codebase scan.

CLAUDE.md and AGENTS.md

Claude Code reads CLAUDE.md; on its own, it does not read AGENTS.md. If your repo already has an AGENTS.md for other tools, the common bridge is a CLAUDE.md that's one line:

Claude loads the imported file at session start, the same way it would load inline content. Add Claude-specific instructions below the import if you need a handful:

One file stays the source of truth instead of two copies drifting apart. See what belongs in AGENTS.md if you're starting from neither.

What to put in, what to leave out

A quick filter before adding a line: would Claude plausibly get this wrong without being told? If the answer is no — because the code already shows it — leave it out. In practice:

Put in:

• Build, test, and lint commands, verbatim, not "use the usual command."
• Architecture decisions and boundaries the code doesn't advertise (which module owns what, what's frozen, what's intentionally weird).
• Rules you've corrected an agent on more than once — the second correction is the signal it belongs here, not in chat.
• Anything a new teammate would need on day one to avoid an easy mistake.

Leave out:

• Directory listings and type signatures — Claude reads the code.
• Framework tutorials or language basics.
• Aspirational style guidance nobody actually enforces in review.
• Anything that changes weekly; a stale rule is worse than none.
• Multi-step procedures that only apply to one corner of the codebase — those tend to age better as a comment near the code itself than as a permanent line loaded into every single session.

The anti-patterns

The essay. A 3,000-word CLAUDE.md costs its full length in tokens on every request, and the important rules drown. Under ~150 lines is the working range.

Vague adjectives. "Be careful with the database" gives the agent nothing to act on. "Schema changes go through migrations; direct SQL against production is never acceptable" does.

No commands. If the file doesn't say how to run tests, the agent reads package.json and guesses — sometimes wrong, always slower.

Stale facts. A file that says "we use yarn" two migrations after moving to pnpm is worse than no file. Treat CLAUDE.md like code: update it in the same PR that changes what it describes.

Everything is shouting. When half the file is bold ALL-CAPS warnings, nothing stands out. Reserve emphasis for the few rules that hold even when a request implies otherwise — and state the why, which travels further than volume. System prompts have the same failure mode — the fix is the same wording pattern either way.