Guide · CLAUDE.md

CLAUDE.md: an example and template for Claude Code

By Shamaz Khan · 18 Nov 2026 · 6 min read

CLAUDE.md is the file Claude Code reads at the start of a session in your project. A good one is short, specific and current. A bad one is a long essay the agent half-follows.

What belongs in CLAUDE.md

What to leave out

Template

# Project: Acme web app
Next.js app with a Postgres API. Customers use it to manage invoices.

## Commands
- Install: npm ci
- Dev: npm run dev
- Test: npm test
- Lint: npm run lint

## Current task
Add CSV export to the reports page.
Only change: src/export/**, src/pages/reports.tsx, tests/export/**
If you need another file, stop and ask.

## Never edit without asking
- prisma/migrations/**
- .github/**
- package-lock.json

## Must keep working (run before saying you're done)
- L1 Sign-in works: npm test -- tests/auth
- L2 Invoice totals are correct: npm test -- tests/billing

## Decisions
- D-001 Money is stored in integer cents. Don't use floats.
- D-002 Dates are UTC in the API, local only in the UI.

## When you finish
Run the tests above, then summarise: what changed, which files,
test results, and anything you were unsure about.
Never edit, skip or delete a test to make it pass.

CLAUDE.md vs AGENTS.md

AGENTS.md is the shared rules file many agents read (Codex, Cursor, Copilot and others). CLAUDE.md is Claude Code's. If you use more than one agent, keep one source of truth and generate both, or have CLAUDE.md point to AGENTS.md, so the rules never drift apart.

Keep it current automatically

The "current task" section goes stale the moment the task changes. Stet generates both files from one charter and updates them when you set a scope, add a lock or log a decision:

npx stet-cli init
stet scope set "Add CSV export" --allow "src/export/**,tests/export/**"
stet lock add "Sign-in works" --cmd "npm test -- tests/auth"
stet decide "Money is stored in integer cents" --why "Avoid float rounding"

Then stet guard and stet check verify that the agent actually followed the file.

FAQ

Where does CLAUDE.md go?

In the root of your project, so Claude Code reads it when you start a session there. Claude Code also supports a personal file in your home directory for preferences that apply to every project.

How long should CLAUDE.md be?

Short enough to read in a minute: roughly a screen. Long files compete with themselves and the agent gives each rule less weight.

Should I have both CLAUDE.md and AGENTS.md?

If you use agents other than Claude Code, yes, but keep one source of truth so they never disagree. Stet generates both from the same charter.

Put guardrails on your AI coding agent

Stet is a free, open-source CLI and MCP server for Claude Code, Cursor, Codex and Copilot. It runs locally: no account, your code never leaves your machine.

npx stet-cli init · Install · Setup guide · GitHub

Related