A CLAUDE.md example for Claude Code you can copy

CLAUDE.md is the file Claude Code reads at the start of every session. Whatever you put there is what Claude "remembers" about your project. Most people either leave it empty or let /init write a long file that Claude then half-ignores. This article gives you a short, working CLAUDE.md example you can copy, explains each section, and covers the settings that decide whether Claude actually reads it.

Checked on 28 Oct 2026 against Claude Code's memory docs (code.claude.com/docs/en/memory).

A CLAUDE.md example you can copy

Put this in ./CLAUDE.md (or ./.claude/CLAUDE.md) at the root of your repo and edit the stack line and the commands first. Those two edits do most of the work.

# CLAUDE.md

## Project
Invoice tracker for freelancers. Next.js (App Router), TypeScript strict,
Supabase (Postgres + Auth), Tailwind 4. Deployed on Vercel.

## Commands
- Install: `npm install`
- Dev: `npm run dev`
- Typecheck: `npm run typecheck`
- Lint: `npm run lint`
- Test: `npm test` (one file: `npm test -- path/to/file`)
- Build: `npm run build`

## How to work
- Read a file before you edit it. Do not edit from memory.
- For anything bigger than a one-file fix, write a short plan and wait for "go".
- One task, one small diff. Do not refactor code the task does not need.
- Check the installed version in package.json before using a framework API.
- You are done only when typecheck, lint and tests pass. Say what you ran.
- If the same fix fails twice, stop and summarise what you tried.

## Conventions
- Server Components by default. `"use client"` only where needed.
- Database access only on the server, through `lib/db/`.
- Named exports. Components in `components/`, one per file.

## Never
- Never read, print or commit `.env*` files or keys.
- Never put a secret in a `NEXT_PUBLIC_` variable.
- Never edit applied migrations in `supabase/migrations/`.
- Never run `git push`, `git reset --hard` or force flags unless asked.

That is about 35 lines. Claude Code's docs recommend targeting under 200 lines per CLAUDE.md, because longer files use more context and reduce adherence. Short and specific wins.

What each section is for

Project

One paragraph and a stack line. "Next.js App Router, TypeScript strict, Supabase" saves Claude from guessing between the Pages Router and the App Router, or between two auth libraries. Name versions only if they matter and you will keep them current.

Commands

The single most useful section. When Claude knows the exact typecheck, lint and test commands, it can check its own work instead of telling you "it should work". If a command does not exist yet, delete the line rather than leaving a guess.

How to work

These are behaviour rules, not style rules. They target the failure modes that cost the most time with any coding agent: editing files it has not read, giant rewrites, invented APIs from an older version, and fix loops. Each line is concrete enough to verify, which is what the docs ask for: "Run npm test before committing" rather than "Test your changes".

Conventions

Only the conventions Claude cannot work out from the code, or keeps getting wrong. Claude already knows how to write TypeScript. It does not know that your database calls live in lib/db/.

Never

Hard boundaries. Keep this list short so each line stands out. Note that CLAUDE.md is guidance, not enforcement. The docs say to use a PreToolUse hook or permissions.deny in settings when something must be blocked no matter what.

Where Claude Code looks for CLAUDE.md

• Project: ./CLAUDE.md or ./.claude/CLAUDE.md. Commit it so everyone gets the same rules.
• Personal, this project: ./CLAUDE.local.md. Add it to .gitignore.
• Personal, all projects: ~/.claude/CLAUDE.md.
• Subfolders: a CLAUDE.md inside packages/api/ loads when Claude reads or edits a file in that folder, not at launch.

Files are added together, not overridden. Instructions closer to where you started Claude are read last. If two files contradict each other, Claude may follow either, so keep them consistent.

To check what loaded, run /context in a session and look under Memory files. /memory lists the files and lets you open them in your editor.

Scope rules to folders with .claude/rules/

When one part of the codebase needs its own rules, do not grow CLAUDE.md. Put a file in .claude/rules/ with a paths field, and it only loads when Claude works on matching files:

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

# API rules
- Validate every request body with the shared Zod schemas.
- Check the session on the server before reading user data.
- Return errors as { code, message }. Never throw raw strings.

paths is the only frontmatter field Claude Code reads from a rule. A rule without it loads every session, like CLAUDE.md.

CLAUDE.md and AGENTS.md together

If you also use Cursor, Codex or another tool, you may already have an AGENTS.md. Claude Code can read AGENTS.md directly (v2.1.277 or later), but by default only when there is no CLAUDE.md or CLAUDE.local.md in your working directory or above it. If you want both, keep the shared rules in AGENTS.md and import it:

@AGENTS.md

## Claude Code
Use plan mode for changes under src/billing/.

Imports are expanded when the file loads, so they help organise rules but do not save context. For the full comparison of file types, see Cursor rules vs CLAUDE.md vs AGENTS.md, and for a shared starter file, the AGENTS.md example.

Should you use /init?

/init analyses your codebase and writes a starting CLAUDE.md with build commands and conventions it finds. It is a reasonable first draft. Then cut it down: delete anything Claude can work out from the code (directory listings, dependency lists, architecture tours) and add the rules it would not discover on its own, such as "never edit applied migrations". Since Claude Code v2.1.283 you can also run /doctor prompt-audit to find outdated or conflicting lines.

When Claude ignores your CLAUDE.md

1. Run /context. If the file is not under Memory files, Claude cannot see it. Check the location.
2. Look for contradictions between CLAUDE.md, CLAUDE.local.md, nested files and .claude/rules/.
3. Make the rule concrete. "Use 2-space indentation" works better than "format code nicely".
4. Shorten the file. Every line you remove makes the rest easier to follow.
5. If the rule must always happen at a fixed point, such as before every commit, write it as a hook instead.

If Claude is already stuck in a loop, the prompts in When your AI agent keeps breaking your code will get it out.

FAQ

Where do I put CLAUDE.md?

In the repo root as CLAUDE.md or .claude/CLAUDE.md. Personal notes go in CLAUDE.local.md (gitignored) or ~/.claude/CLAUDE.md for every project.

How long should CLAUDE.md be?

Claude Code's docs say to target under 200 lines. Move rules that only apply to part of the codebase into .claude/rules/ with a paths field.

Does Claude Code read AGENTS.md?

Yes, from v2.1.277, when there is no CLAUDE.md or CLAUDE.local.md in your working directory or above it. Otherwise add @AGENTS.md to your CLAUDE.md.

Is CLAUDE.md enforced?

No. Claude treats it as context and tries to follow it. Use hooks or permission settings for anything that must be blocked.

Can I use the same rules in Cursor?

Yes. Cursor reads AGENTS.md and its own .cursor/rules/*.mdc files. Write the rules once and generate or import the rest, so the files do not drift apart.