CLAUDE.md Templates & Examples That Actually Work in 2026 (Copy-Paste Starter, Rules & Auto Memory)

CLAUDE.md is the single highest-leverage file in a Claude Code project — and most are either bloated and ignored, or thin and useless. This is the practical reference, grounded in the official docs, plus a copy-paste starter you can customize in five minutes. (For the broader workflow, see advanced Claude Code tips.)

What CLAUDE.md actually is (and isn't)

Claude reads CLAUDE.md at the start of every session and treats it as context, not enforced configuration. It tries to follow it; it doesn't guarantee compliance. That single fact drives everything:

• For behavior ("prefer server components," "match existing style") → CLAUDE.md.
• For must-happen enforcement ("run lint before commit," "never write to /secrets") → a PreToolUse hook, which runs as a shell command regardless of what Claude decides.

Writing "IMPORTANT: YOU MUST" louder doesn't make context into enforcement. Use the right tool.

Where it lives (and load order)

CLAUDE.md can sit at several scopes, loaded broad → specific:

Scope	Location	For
User	~/.claude/CLAUDE.md	Your personal preferences, all projects
Project	./CLAUDE.md or ./.claude/CLAUDE.md	Team-shared, in version control
Local	./CLAUDE.local.md (gitignore it)	Your private project notes (sandbox URLs, test data)
Managed	OS policy path	Org-wide standards (can't be excluded)

Claude walks up the directory tree and concatenates everything it finds; subdirectory CLAUDE.md files load on demand when Claude reads files there.

What makes one effective

The official guidance is specific:

• Size: under 200 lines. Longer files consume more context and reduce adherence. (Imports don't help here — imported files still load at launch.)
• Be concrete and verifiable. "Use 2-space indentation" beats "format code properly." "Run npm test before committing" beats "test your changes." "API handlers live in src/api/handlers/" beats "keep files organized."
• Structure with headers + bullets. Claude scans structure like a reader does.
• No contradictions. If two rules conflict, Claude picks one arbitrarily — review periodically.
• Only what Claude would get wrong. If it's inferable from the code, leave it out.

A good test: add to CLAUDE.md when Claude makes the same mistake twice, when a review catches something it should've known, or when you type the same correction you typed last session.

Copy-paste starter template

Keep it tight — customize the brackets, delete what doesn't apply:

# CLAUDE.md — [Project Name]

## Overview
[One sentence: what this is and who it's for.]

## Stack
- [Framework + version, e.g. Next.js 16 App Router, React 19, TypeScript]
- [DB/backend: Supabase / Prisma + Postgres]
- [Auth, payments, storage]
- Tests: [Vitest / Playwright] · Tooling: [Biome/ESLint, pnpm]

## Commands (Claude can't infer these reliably)
- Dev: `pnpm dev`
- Test: `pnpm test`
- Lint/format: `pnpm lint`
- Typecheck: `tsc --noEmit`
- DB migrate: `npx prisma migrate dev`

## Conventions
- TypeScript strict; no `any` without a comment.
- Server components/actions where possible.
- Naming: PascalCase components, camelCase functions, kebab-case files.
- Always handle loading/error states. Never commit secrets or `.env`.

## Workflow
- After behavior changes, run the relevant tests or typecheck.
- Minimal, surgical edits — change only what the task needs.
- If requirements are unclear, ask before implementing.
- For bugs: reproduce with a test before fixing.

## Pointers (progressive disclosure)
- Architecture: @docs/architecture.md
- See `.claude/rules/` for path-scoped detail.

<!-- maintainer note: HTML comments are stripped before Claude sees this, so they cost zero tokens -->

That last detail is real and underused: block-level HTML comments are stripped before the file enters context — free notes for human maintainers.

Beyond the root file

When the root file gets crowded, don't grow it — scope it:

• @import other files. @docs/architecture.md, @package.json — imported inline at launch (max depth 4 hops). Wrap a path in backticks to mention it without importing. If you already have an AGENTS.md, put @AGENTS.md at the top of CLAUDE.md so both tools share one source.
• .claude/rules/ with path scoping. Drop topic files (testing.md, api-design.md) in .claude/rules/. Add a YAML paths: frontmatter and the rule loads only when Claude touches matching files — the cleanest way to keep context lean:

---
paths:
  - "src/api/**/*.ts"
---
# API rules
- All endpoints validate input and use the standard error format.

• Auto memory (the lesser-known one): Claude writes its own notes as it works — a per-repo MEMORY.md plus topic files — based on your corrections and discoveries. It's on by default; run /memory to view, edit, or toggle it. This is how a project "learns" your build quirks without you writing them down.

Real examples worth studying

• multica-ai/andrej-karpathy-skills (~180k★) — literally "a single CLAUDE.md file to improve Claude Code." Minimal, behavior-focused (think before coding, simplicity, surgical changes, verify). A great merge-in.
• shanraisshan/claude-code-best-practice (~58.7k★) — a meta-example showing advanced patterns and conventions.

Pitfalls

• Bloat — the #1 killer. Over 200 lines and adherence drops; trim or scope to rules.
• Contradictions across nested files — Claude picks arbitrarily.
• Treating it as enforcement — it's context; use hooks for hard rules.
• Dumping inferable facts — if Claude can read it from the code, don't repeat it.

Go deeper

• The broader workflow: advanced Claude Code tips.
• Big or existing repo? See Claude Code on large codebases for hierarchical CLAUDE.md + semantic search.
• Structure the whole project: the projects hub.
• Shipped something with a tight setup? List it free on SaaSCity.

FAQ

How long should CLAUDE.md be? Under 200 lines (official guidance). Scope the rest into .claude/rules/.

Why does Claude ignore it? It's context, not enforcement. Use a PreToolUse hook for must-happen rules; make instructions specific.

Use /init? Yes to bootstrap, then customize. CLAUDE_CODE_NEW_INIT=1 for the interactive version.

CLAUDE.md vs rules vs auto memory? CLAUDE.md = universal, you write it. .claude/rules/ = scoped, path-triggered. Auto memory = Claude's own notes.