Home / CLAUDE.md template for Claude Code

A CLAUDE.md template for Claude Code

Claude Code reads CLAUDE.md from your repo root at the start of every session. A good one is short, specific and boring. A bad one is a 600-line wish list the agent skims and ignores.

What belongs in CLAUDE.md

• Project facts: stack, package manager, where things live.
• Exact commands: how to dev, test, lint and typecheck. Agents guess these wrong constantly.
• Hard rules: the 5 to 10 things that must never happen (disable RLS, commit secrets, edit generated files).
• Workflow: plan first, small diffs, run the tests before saying "done".

Share rules with Cursor and Codex

Keep the shared rules in AGENTS.md and make CLAUDE.md import it with a single @AGENTS.md line, then add only Claude-specific notes below. One source of truth, every tool.

Free template: copy it

@AGENTS.md

# Claude Code notes
- Stack: <<FILL: e.g. Next.js 15 App Router, Supabase, Stripe, pnpm>>
- Commands: pnpm dev | pnpm test | pnpm lint | pnpm typecheck
- Before editing: write a short plan and wait for "go" on anything touching auth, payments or migrations.
- Keep diffs small. Never edit generated files (lib/database.types.ts) by hand.
- Never print, log or commit secrets. Never disable RLS or tests to make something pass.
- "Done" means: tests and typecheck pass, and you list what you changed.

For a ready-made safety section, grab the free agent-guardrails.md from our GitHub repo and paste it into AGENTS.md.