Fabler Labs → Guides → CLAUDE.md example

CLAUDE.md example: a complete, annotated template

Free · no signup · verified against the current docs · last updated July 2026

A CLAUDE.md is the file Claude Code reads at the start of every session to learn how your project is built — how to run it, how to test it, the conventions that aren't obvious from the code, and what not to touch. It's the single highest-ROI file in most repos. This page gives you a complete, copy-paste example, then the details that actually matter: where the file goes, the exact load order, imports, AGENTS.md, and what to leave out.

A complete CLAUDE.md example

Here's a realistic CLAUDE.md for a TypeScript / Node service. Copy it, delete what doesn't apply, and replace the specifics with yours. The point isn't the exact commands — it's the shape: concrete, verifiable instructions, grouped under headers, with a clear "don't touch" list.

# Project: Acme API

TypeScript + Node service. REST API backed by Postgres. This file tells you
how it's built — read it before making changes.

## Commands
- Install: `pnpm install` (we use pnpm, never npm or yarn)
- Dev server: `pnpm dev` (runs on http://localhost:3000)
- Test: `pnpm test` — run this before every commit
- Test one file: `pnpm test path/to/file.test.ts`
- Typecheck: `pnpm typecheck`
- Lint/format: `pnpm lint --fix` (Biome; do not add Prettier or ESLint)

## Architecture
- HTTP handlers live in `src/api/handlers/`, one file per resource.
- Business logic goes in `src/services/`; handlers stay thin.
- Database access goes through `src/db/` only — never import `pg` directly
  from a handler or service.
- Shared types live in `src/types/`. Generated types are in `src/types/gen/`
  — never edit those by hand; regenerate with `pnpm gen:types`.

## Conventions
- 2-space indentation. Named exports only (no default exports).
- Validate all request input with the Zod schemas in `src/schemas/`.
- Return errors via `problemJson(res, status, detail)` — never `res.json`
  a raw error. This keeps the error shape consistent for clients.
- Every new endpoint needs a test in `tests/` and an entry in `openapi.yaml`.

## Testing
- Vitest. Tests are colocated as `*.test.ts` next to the code they cover.
- Integration tests need a local Postgres: `docker compose up -d db` first.
- After changing an endpoint, run the tests and confirm they pass before
  saying you're done — don't just typecheck.

## Do not
- Do not edit anything under `src/types/gen/` or `migrations/` by hand.
- Do not commit directly to `main`; branch and open a PR.
- Do not add new dependencies without flagging it first — check if a helper
  in `src/lib/` already does the job.

<!-- Maintainer note: this comment is stripped before Claude sees it. -->

Notice what's not here: no "write clean code," no restating language docs, no essay. Every line is something a new teammate would have to be told, phrased concretely enough that Claude can act on it.

Where the file goes (and the load order)

CLAUDE.md files can live in several places, each with a different scope. Claude Code loads them from broadest scope to most specific, concatenating all of them — so an instruction closer to where you launched Claude is read last:

1. Managed policy (org-wide, set by IT) — e.g. /etc/claude-code/CLAUDE.md on Linux. Can't be overridden by individuals.
2. User — ~/.claude/CLAUDE.md. Your personal preferences across every project.
3. Project — ./CLAUDE.md or ./.claude/CLAUDE.md. Checked into version control; shared with your team. This is the one you'll write most.
4. Local — ./CLAUDE.local.md. Your private per-project notes (sandbox URLs, test data). Add it to .gitignore.

Claude also walks up the directory tree from where you launched it, so in a monorepo a root CLAUDE.md and a package-level CLAUDE.md both load, root first. CLAUDE.md files in subdirectories below your working directory don't load at launch — they're pulled in on demand when Claude reads files in those folders.

Good to know: the project-root CLAUDE.md is re-read after /compact, so its instructions survive compaction. Instructions you only typed into chat do not — if you find yourself repeating one, that's the signal to put it in the file.

Keep it short — it loads in full, every time

Unlike auto-memory (which is capped), CLAUDE.md is loaded in full into every session regardless of length. That's exactly why the docs recommend targeting under 200 lines: every line costs context tokens on every run, and longer files measurably reduce how reliably Claude follows any single instruction. When yours starts to sprawl, don't keep growing it — reach for one of the two tools below.

Imports, rules, and AGENTS.md

• @path imports. Write @docs/architecture.md anywhere in CLAUDE.md and that file is expanded into context at launch. Relative and absolute paths both work; imports can nest up to four hops deep. To mention a path without importing it, wrap it in backticks. Note: imports help you organize, but they don't save context — the imported file still loads at launch.
• .claude/rules/. For larger repos, split instructions into topic files under .claude/rules/. Add a paths: field in YAML frontmatter to scope a rule to matching files (e.g. src/api/**/*.ts) so it only loads when Claude touches those files — the right home for guidance that isn't needed in every session.
• AGENTS.md. Claude Code reads CLAUDE.md, not AGENTS.md. If your repo already has an AGENTS.md for other tools, don't duplicate it — create a CLAUDE.md whose first line is @AGENTS.md (then add any Claude-specific notes below), or symlink the two together. New to the open standard? See our AGENTS.md example — a copy-paste template plus how it relates to CLAUDE.md.

Two things people miss

1. HTML comments are stripped before Claude sees them. Block-level <!-- ... --> comments in CLAUDE.md are removed before the file enters context, so you can leave notes for human maintainers without spending tokens on them. (Comments inside code blocks are kept.)
2. CLAUDE.md is guidance, not enforcement. It's delivered as context, not an enforced config — Claude reads it and tries to follow it, but there's no hard guarantee. For something that must happen (e.g. run a linter before every commit, block edits to a path), use a hook instead of a CLAUDE.md line.

The fastest way to a first draft

Run /init in your repo and Claude analyzes the codebase and writes a starting CLAUDE.md with the build commands, test instructions, and conventions it can discover. If one already exists, /init suggests improvements instead of overwriting. Treat the output as a draft: the highest-value lines are the ones Claude couldn't infer — your "don't touch" list, the non-obvious conventions, the gotchas that only bite once. Add those by hand.

The 5-line checklist for a good CLAUDE.md

1. Commands — how to install, run, test, and lint, with the exact invocations.
2. Layout — where things live, so Claude doesn't scatter files.
3. Conventions — the non-obvious rules a new hire would need told.
4. Do-not — generated files, protected paths, "never commit to main."
5. Verify — one line telling Claude to exercise its changes, not just typecheck.