Docs
CLAUDE.md Examples That Actually Work
Three real CLAUDE.md files — Next.js, Python API, monorepo — and the anti-patterns that make Claude Code ignore yours.
CLAUDE.md is Claude Code's project instruction file — loaded into context at the start of every session in your repo. It's the highest-leverage file in the repository: a hundred good lines shape thousands of agent decisions. Here are three examples that hold up in real use, and the patterns that quietly break.
Example 1 — Next.js app
# Agent Instructions
You are a senior engineer pairing with the maintainer. Skip beginner
explanations; flag real risks; push back with reasons.
## Conventions
- Server Components by default; "use client" only when hooks demand it.
- TypeScript strict stays on. No \`any\`, no \`as\` to silence errors.
- Mutations via Server Actions, not ad-hoc API routes.
## Workflow
- Before reporting done: run \`pnpm lint\` and \`pnpm build\`, and
exercise the change in the running app. Report actual results.
## Constraints
- Never read, print, or commit .env values. Names only.
- Change only what the task requires — note other issues, don't fix them.Why it works: every line is checkable. "Run pnpm lint" either happened or didn't. Compare that with "write clean code" — which an agent can neither follow nor violate measurably.
Example 2 — Python API
# Agent Instructions
You are a test-first backend engineer on a FastAPI service.
## Knowledge
- Postgres schema source of truth: alembic/ migrations, never models alone.
- The /internal/* routes bypass auth by design — they're firewalled.
## Workflow
- Bug fixes start with a failing test. Run one test: \`pytest path::test -x\`
- Migrations: \`alembic revision --autogenerate\`, review SQL before apply.
## Constraints
- Raise specific exceptions; bare \`except:\` is banned.
- No new dependencies without approval — state package, size, and what
it replaces.The /internal/* line is the kind that earns its place: it looks like a security bug to a fresh reader, and an uninformed agent would "fix" it.
Example 3 — Monorepo
# Agent Instructions
You are a minimalist engineer: smallest correct change, delete before add.
## Knowledge
Apps live in apps/, shared packages in packages/. Cross-package imports
go through package entry points — never deep-import internals.
## Workflow
- Changes to packages/* require checking every consumer before merging.
- Refactors land separately from behavior changes.
## Tools
- Everything runs through turbo from the root: \`turbo test --filter=web\`.
Never cd into a package and run its scripts directly.The anti-patterns
The essay. A 3,000-word CLAUDE.md costs its full length in tokens on every request, and the important rules drown. Under ~150 lines is the working range.
Vague adjectives. "Be careful with the database" gives the agent nothing to act on. "Schema changes go through migrations; direct SQL against production is never acceptable" does.
No commands. If the file doesn't say how to run tests, the agent reads package.json and guesses — sometimes wrong, always slower.
Stale facts. A file that says "we use yarn" two migrations after moving to pnpm is worse than no file. Treat CLAUDE.md like code: update it in the same PR that changes what it describes.
Everything is shouting. When half the file is bold ALL-CAPS warnings, nothing stands out. Reserve emphasis for the few rules that hold even when a request implies otherwise — and state the why, which travels further than volume.
Skip the blank page.
Groundrules assembles files like this from curated blocks — pick a starter pack, fill in your project facts, export.