How to write a great CLAUDE.md / .cursorrules file

What a rules file really is

Claude Code reads CLAUDE.md. Cursor reads .cursorrules (or "Project Rules"). Codex and OpenClaw read AGENTS.md. Different filenames, same idea: a plain-text brief, sitting at the root of your repo, that the agent loads before every task. It's the difference between briefing a new contractor once and re-explaining the job on every single ticket.

Most teams either skip it or dump a wall of vague aspirations into it ("write clean code", "follow best practices"). Both fail for the same reason: the agent can't act on what it can't pin down. A good rules file is specific, authoritative, and short enough to be read every time. Think operating manual, not mission statement.

A rules file the agent never finishes reading is a rules file it ignores. Keep it under ~150 lines.

One file, many agents

You don't need to maintain four versions. Write the content once and mirror it. The substance is identical; only the filename and a couple of tool-specific lines change.

• Claude Code → CLAUDE.md at repo root (and optional nested ones per package).
• Cursor → .cursorrules, or the newer .cursor/rules/*.mdc "Project Rules".
• Codex / OpenClaw → AGENTS.md.
• Copilot → .github/copilot-instructions.md.

The trick is to treat the rules file as source code for behavior: commit it, review changes to it in PRs, and update it the moment the agent does something you have to correct twice.

The 10 sections that matter

Order them from most to least frequently needed — the agent's attention, like yours, fades down the page.

1. What we're building. One concrete paragraph. Name the product, the users, and the single most important quality attribute (correctness? latency? accessibility?). When a trade-off is ambiguous, the agent optimizes for that.
2. Tech stack (authoritative). List only what's actually used, and pin majors. "TypeScript 5, strict" beats "modern JS". Add the package manager and forbid the others — pnpm only, never npm or yarn stops a whole class of mistakes.
3. Project map. Point at the 5–8 directories that matter and one line on what each holds. This saves the agent a filesystem crawl and stops it inventing folders.
4. Commands you may run. Install, dev, test, test-one-file, lint, typecheck, build. The agent will prefer these over guessing. End with: "always run lint and typecheck before declaring a task done."
5. Conventions. Match the style of the file being edited. Pure functions where possible. Descriptive names. Errors thrown and handled at the boundary, never swallowed. Comments explain why, not what.
6. Testing policy. Every bug fix starts with a failing test. New logic ships with tests. And the line that saves you most pain: "do not weaken or delete a test to make the suite pass."
7. Guardrails — ask first. The most valuable section. Force the agent to stop and surface a plan before adding a dependency, editing more than N files, or touching auth, billing, migrations, or anything under infra/.
8. Security (non-negotiable). Never log or commit secrets. Validate external input at the boundary. Parameterized queries only. No new network calls or telemetry without approval.
9. How to work. The loop: restate the task, outline a plan, make the smallest change, run tests, show the diff. "If stuck after two attempts, stop and summarize" prevents the doom-spiral of an agent digging a deeper hole.
10. Definition of done. A literal checklist: behavior matches the request, tests pass, lint and typecheck clean, diff is minimal, no stray debug logs. The agent will grade itself against it.

The copy-paste template

Here's a compressed, battle-tested skeleton. Fill the {{placeholders}}, delete what doesn't apply, and keep it tight.

# CLAUDE.md — {{project}}

## 1. What we're building
{{One paragraph. Users + the ONE quality attribute that wins ties.}}

## 2. Stack (authoritative)
- Language: {{TypeScript 5.x, strict}}
- Framework: {{Next.js 15 App Router}}
- Data: {{Postgres 16 + Drizzle}}   Tests: {{Vitest + Playwright}}
- Package manager: {{pnpm}} — do not use npm or yarn.

## 3. Project map
- `src/lib/`  pure business logic (test this hardest)
- `src/app/`  routes + server components
- `src/db/`   schema, migrations, queries

## 4. Commands
- test: `{{pnpm test}}`   lint+types: `{{pnpm lint && pnpm typecheck}}`
- Always run lint + typecheck before "done".

## 5. Conventions
- Match the file you're editing. Smallest diff. Throw typed errors.
- Comments say WHY. Delete dead code, don't comment it out.

## 6. Testing
- Bug fix = failing test first. New lib fn = unit test.
- Never weaken a test to pass CI.

## 7. Guardrails — ask before you act
Surface a plan BEFORE: new deps · >8 files · auth/billing/migrations · infra/.

## 8. Security
- Never log/commit secrets. Parameterized queries only.
- Validate external input at the boundary.

## 9. How to work
Restate → plan → smallest change → tests → show diff.
Stuck after 2 tries? Stop and ask one specific question.

## 10. Definition of done
[ ] behavior matches  [ ] tests pass  [ ] lint+types clean
[ ] minimal diff       [ ] no secrets / debug logs

Paste that into CLAUDE.md, copy the same content to .cursorrules and AGENTS.md, and you've just upgraded every future request across every tool — for free.

Five mistakes that get your rules ignored

• It's too long. Past ~150 lines, the agent skims. Cut adjectives, keep imperatives.
• It's aspirational, not operational. "Write maintainable code" is noise. "Pure functions in src/lib, side effects at the edges" is a rule.
• No guardrails. Without an explicit "ask before X", the agent will happily refactor 20 files or add a dependency you didn't want.
• It lies about the stack. Listing a library you removed sends the agent down dead ends. Treat the stack section as authoritative and keep it current.
• It never changes. The best rules files are living documents. Every time you correct the agent twice, add a line so you never correct it a third time.

Start small — sections 1, 4, 7 and 10 alone will noticeably improve output. Then grow the file as your agent surprises you. The goal isn't a perfect document; it's a repo where the agent already knows how you work before you say a word.