CLAUDE.md Examples: 6 Copy-Paste Files for Real Projects (2026)

Published 2026-10-22 · 6 min read · by AgentKit Co

CLAUDE.md is the file Claude Code reads at the start of every session so you don't have to re-explain your project. The best ones are short, concrete and boring: commands, layout, a few rules Claude can't guess. This page gives six you can copy today, one for each place a CLAUDE.md usually lives, with a note on why each line earns its spot.

Everything here was checked against Anthropic's Claude Code memory docs on 2026-10-20. Claude Code ships fast, so re-check the docs for anything you depend on.

Where the files go

Claude Code loads instruction files from several places, broadest first, so more specific files appear later in context:

Files in your working directory and every folder above it load at launch and are joined together, not overridden. A CLAUDE.md in a subfolder loads only when Claude starts working with files there. To check what actually loaded, run /context and look under Memory files.

Don't want to start from zero? Run /init and Claude drafts a CLAUDE.md from your codebase. Then trim it and add what it couldn't discover.

Example 1: a Next.js app

# Project: storefront (Next.js 15, App Router, TypeScript)

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (port 3000)
- Test one file: `pnpm vitest run path/to/file.test.ts`
- Before saying a task is done: `pnpm lint && pnpm typecheck && pnpm test`

## Layout
- Routes live in `app/`. Shared UI lives in `components/ui/`.
- Server-only code goes in `lib/server/` and must never be imported by a client component.
- Database access only through `lib/server/db.ts` (Drizzle). No raw SQL in route files.

## Rules
- Use pnpm, never npm or yarn.
- New components are server components unless they need state or browser APIs.
- Don't edit files in `components/ui/` generated by shadcn; wrap them instead.

Why it works: every line is something Claude would otherwise get wrong or have to search for. "Test one file" saves whole-suite runs, which saves time and tokens.

Example 2: a Python API

# Project: billing-api (Python 3.12, FastAPI, Postgres)

## Commands
- Setup: `uv sync`
- Run: `uv run uvicorn app.main:app --reload`
- Tests: `uv run pytest -q` (one test: `uv run pytest tests/test_invoices.py::test_total`)
- Lint and format: `uv run ruff check --fix . && uv run ruff format .`

## Conventions
- Handlers in `app/routes/`, business logic in `app/services/`. Routes stay thin.
- Every new endpoint gets a Pydantic request and response model.
- Money is integer cents everywhere. Never use float for amounts.
- Migrations: `uv run alembic revision --autogenerate -m "msg"`, then read the file before applying.

## Don't
- Don't touch `app/legacy/`; it's frozen until the rewrite.

The "money is integer cents" line is the kind of fact the docs mean by "concrete enough to verify". "Write good code" is not.

Example 3: a monorepo root

# Monorepo: acme (pnpm workspaces + Turborepo)

- `apps/web` Next.js site, `apps/api` Node API, `packages/*` shared libraries.
- Run tasks through Turbo from the root: `pnpm turbo run test --filter=web`.
- Each app has its own CLAUDE.md with app-specific rules. Read it before working there.
- Shared types live in `packages/types`. Change them there, never copy them into an app.
- Never bump a dependency in one app only; use `pnpm -r up <pkg>`.

Keep the root file about the whole repo and put app details in apps/web/CLAUDE.md and so on. Those load on demand, so Claude only pays for them when it works in that app. If another team's CLAUDE.md keeps getting picked up, the claudeMdExcludes setting in .claude/settings.local.json can skip it on your machine.

Example 4: your personal ~/.claude/CLAUDE.md

# My preferences (all projects)

- Explain the plan in 3 bullets before editing more than 2 files.
- Prefer small commits with conventional messages (feat:, fix:, chore:).
- When a command fails, show me the exact error before trying a fix.
- I use macOS with zsh. Use `gsed` instead of `sed -i` tricks.

This file is for how you like to work, not for any one codebase. Keep project facts out of it.

Example 5: CLAUDE.local.md for private project notes

# Local only (gitignored)

- My dev database: postgres://localhost:5433/billing_dev
- Seed test data with `uv run python scripts/seed.py --small`.
- I'm working on the invoices refactor; ask before touching `app/services/tax.py`.

CLAUDE.local.md loads next to CLAUDE.md but stays out of git. One catch: it only exists in the worktree where you made it. If you use several git worktrees, import a file from your home folder instead, for example @~/.claude/billing-notes.md.

Example 6: a path-scoped rule instead of a bigger CLAUDE.md

When an instruction only matters for part of the code, move it to .claude/rules/ with a paths field. It then loads only when Claude reads or edits a matching file.

---
paths:
  - "src/api/**/*.ts"
  - "tests/api/**/*.test.ts"
---

# API rules
- Validate every request body with zod before using it.
- Errors use `{ error: { code, message } }` and the right HTTP status.
- Every new endpoint gets a test in `tests/api/`.

paths is the only frontmatter field Claude Code reads in a rule. A rule with no paths loads every session, just like CLAUDE.md.

Tricks worth knowing

• Imports. Write @README or @docs/git-workflow.md anywhere in CLAUDE.md to pull a file in. Imports nest up to four levels. They help organize, but they don't save context, because imported files load at launch too. Wrap a path in backticks to mention it without importing it.
• Hidden notes. Block-level HTML comments like <!-- why this rule exists --> are stripped before Claude sees the file, so you can leave notes for humans for free.
• AGENTS.md. If your repo has an AGENTS.md and no CLAUDE.md (or CLAUDE.local.md) in the working folder or above it, recent Claude Code versions read the AGENTS.md instead. If you do have a CLAUDE.md, add @AGENTS.md to it so Codex, Cursor and Claude share one source. Our AGENTS.md vs CLAUDE.md vs Cursor rules guide compares all three.
• Audit. On v2.1.283 or later, /doctor prompt-audit reports stale or conflicting instructions across your CLAUDE.md, rules and skills, and changes nothing until you say so.

What to leave out

1. Long procedures. A ten-step release process belongs in a skill, which loads only when needed.
2. Style a linter already enforces. Let Prettier or Ruff do formatting.
3. Anything that must never happen. CLAUDE.md is guidance, not enforcement. To truly block an action, use a permission rule or a PreToolUse hook; see our Claude Code hooks examples and settings.json permissions guide.
4. Length. Anthropic suggests staying under 200 lines per file. Longer files cost context in every session and get followed less reliably, which also burns through your usage limits faster.
5. Contradictions. If two lines disagree, Claude may pick either. Review the file whenever you add to it.

A good rule of thumb from the docs: add a line when Claude makes the same mistake twice, or when you catch yourself typing the same correction you typed last session.

Skip the blank page

Our free AGENTS.md generator builds an instruction file from your real package.json or pyproject.toml, right in your browser, and you can import it from CLAUDE.md in one line. For more, the AI Coding Agent Config Kit ($14) has templates for 12 stacks, Cursor rules and prompts that draft and audit your own files.

Sources: Claude Code memory docs (checked 2026-10-20). Related: how to write an AGENTS.md. AgentKit Co is not affiliated with Anthropic. This guide was written with AI assistance and checked against the page above.

Keep reading