CLAUDE.md: what to put in it, where it goes, and a template

What is a CLAUDE.md file?

CLAUDE.md is a plain Markdown file that Claude Code reads at the start of every session. Every session starts with an empty context, so this file is how you carry knowledge forward: the build command, the test runner, the folder layout, the rules your team follows. Write down anything you would otherwise re-explain.

Claude treats it as context, not as enforced configuration. Clear, specific lines get followed far more reliably than vague ones, and a short file gets followed better than a long one. If a rule must hold every time with no exceptions, enforce it with a hook or a permission rule instead.

Where does CLAUDE.md go?

A project CLAUDE.md goes at ./CLAUDE.md or ./.claude/CLAUDE.md, and Claude Code also reads one from ~/.claude/CLAUDE.md, ./CLAUDE.local.md and a managed policy location. They do not override each other. All of them load and are joined together, broadest first.

A few loading rules worth knowing:

• Parent folders load at launch. Start Claude Code in foo/bar/ and it reads foo/bar/CLAUDE.md and foo/CLAUDE.md. The file closest to where you started is read last.
• Subfolders load on demand. A CLAUDE.md inside packages/api/ loads once Claude reads or edits a file in that folder. This is how monorepos give each package its own notes.
• HTML comments are stripped. Block-level <!-- notes --> are removed before the file reaches Claude, so you can leave notes for humans without spending tokens.
• Check what loaded. Run /context and look under Memory files. Run /memory to open and edit any of these files.

Imports

A CLAUDE.md can pull in other files with @path/to/file. Relative paths resolve from the file doing the importing, and imports can nest up to four levels deep.

See @README.md for the project overview and @package.json for npm scripts.

## Git workflow
- @docs/git-instructions.md

Imports help organize a long file, but they do not save context: imported files load in full along with the file that imports them. The first time a project imports a file from outside the repo, such as @~/.claude/my-notes.md, Claude Code asks you to approve it. To mention a path without importing it, wrap it in backticks.

What should CLAUDE.md include?

A CLAUDE.md should hold what Claude cannot learn from the code: commands, style rules that differ from defaults, test instructions, conventions, architecture decisions, setup quirks and gotchas. The best test for every line: would removing it cause Claude to make a mistake? If not, cut it.

Write each instruction so you could check whether it was followed:

• "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".

Good moments to add a line: Claude makes the same mistake twice, a code review catches something Claude should have known, or you type the same correction you typed last session.

A copy-ready CLAUDE.md template

Start from this and delete what does not apply. Aim to keep the result well under 200 lines.

# Project name

One sentence on what this project is and who uses it.

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (http://localhost:3000)
- Test all: `pnpm test`
- Test one file: `pnpm test path/to/file.test.ts`
- Typecheck and lint: `pnpm typecheck && pnpm lint`

## Stack
- Next.js App Router, TypeScript strict, Tailwind
- Database access only through `src/lib/db.ts`

## Code style
- Named exports, no default exports
- Server code never imports from `src/components/`
- Prefer small functions; no new abstraction until a pattern repeats three times

## Workflow
- Run the typecheck and the tests for touched files before saying a task is done
- One logical change per commit, message in the imperative ("Add rate limit")
- Branch names: `feat/<topic>` or `fix/<topic>`

## Gotchas
- `.env.local` holds secrets; never print or commit it
- The payments module talks to a sandbox in dev; see @docs/payments.md

## When compacting
- Keep the list of modified files and the test commands

The last section is a real trick from the docs: you can tell Claude what to preserve when it summarizes a long session.

If you are starting from nothing, run /init first. Claude reads your codebase and writes a starter file, then you trim it and add what it could not discover on its own.

Keep it short

A bloated CLAUDE.md is the most common reason Claude "ignores" instructions: the rule that matters is buried among fifty that do not. Three ways to stay lean:

1. Prune on a schedule. If Claude already does something right without the line, delete the line. Running /doctor prompt-audit asks Claude to find outdated or conflicting instructions and propose edits.
2. Move file-specific rules to .claude/rules/. A rule file with a paths field loads only when Claude touches matching files:

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

# API rules
- Every endpoint validates its input
- Use the standard error response format

3. Move procedures into skills. A ten-step release checklist does not need to sit in every session. As a skill, only its short description loads until you or Claude uses it.

If one instruction keeps getting skipped, add emphasis such as "IMPORTANT" to that line only. Emphasize many lines and none stand out.

CLAUDE.md vs skills vs AGENTS.md

AGENTS.md is the shared format many coding agents read. Recent versions of Claude Code read it directly when your project has no CLAUDE.md. If you use several tools, the cleanest setup is one AGENTS.md that every tool shares, plus a small CLAUDE.md that imports it and adds Claude-specific notes:

@AGENTS.md

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

Coming from Cursor? /init reads .cursor/rules/ and .cursorrules and folds the relevant parts into the CLAUDE.md it generates. See Cursor rules for how the two compare.

Reusing your best instructions

Good CLAUDE.md sections tend to get copied from project to project. Kipt keeps those snippets, along with your prompts and skills, in a private GitHub repo you own, so you can press ⌘K, find your standard "Workflow" block and paste it into a new repo. When a section grows into a procedure, Promote to skill turns it into a SKILL.md that installs anywhere with one npx skills add command.

Source: How Claude remembers your project and Best practices for Claude Code.