CLAUDE.md Template: Give Your AI Coding Agent a Memory
Quick answer
CLAUDE.md is a markdown file in your project root that Claude Code reads at the start of every session. Put your stack, commands, coding rules, and off-limits areas in it. Copy the template below, fill in the brackets, and keep the file under 200 lines, which is Anthropic's guidance for reliable adherence.
The CLAUDE.md template
Save this as CLAUDE.md in the root of your project. Replace every bracket. Specific beats
vague: “Use Zustand for client state” is followable; “write clean code” is not.
# Project Context
## What this is
[One sentence: what the app does and who it's for]
## Stack
- Framework: [Next.js (App Router)]
- Language: [TypeScript, strict mode]
- Styling: [Tailwind CSS]
- State: [Zustand / TanStack Query]
- Database: [Postgres via Supabase]
## Commands
- Dev server: [npm run dev]
- Tests: [npm test]
- Lint and typecheck: [npm run lint && npm run typecheck]
## Code rules
- [Components in /components, one component per file]
- [Never use `any`; define types in /types]
- [All API calls go through /lib/api.ts]
## Off-limits
- Never edit [/migrations] without asking
- Never commit secrets or .env files
- Never disable row-level security on database tables
## Definition of done
- Tests and typecheck pass
- No new console errors
- [Accessible: keyboard and screen reader friendly]What each section does
| Section | Why it's there |
|---|---|
| What this is | Gives every decision a goal to check against. |
| Stack | Stops the agent from adding a second library for something you already use. |
| Commands | Lets the agent run your tests and checks without guessing. |
| Code rules | Keeps new files consistent with existing ones. |
| Off-limits | Protects the areas where a mistake is expensive. |
| Definition of done | Tells the agent when to stop and what to check first. |
Where CLAUDE.md files live
| File | Scope | Shared with |
|---|---|---|
./CLAUDE.md |
This project | Your team, through git |
./CLAUDE.local.md |
This project, your preferences only | Only you (add it to .gitignore) |
~/.claude/CLAUDE.md |
Every project on your machine | Only you |
Claude Code also loads a CLAUDE.md placed in a subfolder once it works on files in that
folder, which is useful for rules that apply only to, say, /api.
CLAUDE.md and AGENTS.md: one file for every tool
| File | Read by |
|---|---|
CLAUDE.md |
Claude Code, Cursor |
AGENTS.md |
Cursor, ChatGPT Codex, Antigravity, and Claude Code when no CLAUDE.md exists |
GEMINI.md |
Antigravity CLI |
If you use more than one tool, write your rules once in AGENTS.md. Then either skip
CLAUDE.md entirely, or create a CLAUDE.md that contains @AGENTS.md plus any Claude-only
notes. The @path syntax imports another file into CLAUDE.md.
Keep it working as the project grows
- Start with
/init. Claude Code drafts a CLAUDE.md from your codebase; you add what it can't discover, like off-limits areas. - Stay under 200 lines. Move folder-specific rules into
.claude/rules/, which load only when Claude works on matching files. - Remove contradictions. If two rules conflict, the agent may follow either one.
- Update it after big changes. An outdated context file is a common cause of the Vibe Wall.
- Use hooks for must-never-happen rules. CLAUDE.md is guidance. A hook can block an action outright.
Go deeper: Chapter 1b: Context Files in the full guide.
Frequently asked questions
What is the difference between CLAUDE.md and AGENTS.md?
Both are markdown instruction files for AI coding agents. CLAUDE.md is Claude Code's own format. AGENTS.md is read by Cursor, ChatGPT Codex, and Antigravity, and Claude Code also reads it when the project has no CLAUDE.md. To keep one source of truth, write AGENTS.md and add a CLAUDE.md that imports it with @AGENTS.md.
How long should a CLAUDE.md file be?
Anthropic recommends keeping each CLAUDE.md under 200 lines. The whole file loads into every session, so longer files cost more context and are followed less consistently. Move rules that apply to only part of the codebase into path-scoped files in .claude/rules/.
Should I commit CLAUDE.md to git?
Yes, commit the project CLAUDE.md so your whole team and every tool session share the same rules. Put personal, project-specific preferences in CLAUDE.local.md and add that file to .gitignore.
How do I create a CLAUDE.md automatically?
Run /init in Claude Code. It analyzes your codebase and writes a starting CLAUDE.md with build commands, test instructions, and conventions it finds. If a CLAUDE.md already exists, /init suggests improvements instead of overwriting it.
Can CLAUDE.md enforce rules?
No. Claude treats CLAUDE.md as context, not enforced configuration. To block an action every time, such as committing without passing tests, use a hook in Claude Code.