Blog
4 min read

Cursor Rules Explained: .cursor/rules, AGENTS.md, and CLAUDE.md

Rules files tell an AI coding tool how your project works so you don't repeat yourself every chat. How Cursor's project rules work, the rule types, what to put in them, how they compare with AGENTS.md and CLAUDE.md, and how to share one set of rules across tools.

Every AI coding tool has the same problem: it starts each conversation knowing nothing about your project. It doesn't know you use pnpm, that tests live next to the code, or that you never touch the legacy/ folder. Rules files fix that: a file in your repo that the tool reads automatically.

In Cursor these are Cursor Rules. Claude Code uses CLAUDE.md. Many tools now also read AGENTS.md. Same idea, different file names.

Cursor project rules

Cursor's rules live in your repository under .cursor/rules/, one file per rule, written in Markdown with a small header (the .mdc format):

---
description: Conventions for API route handlers
globs: src/app/api/**/*.ts
alwaysApply: false
---

- Validate request bodies with Zod before using them.
- Return errors as { error: string } with the right status code.
- Never query the database directly in a route; use functions in src/lib/db.

The header decides when the rule is used:

Type Header Applied
Always Apply alwaysApply: true In every chat in this project
Apply to Specific Files globs: ... When files matching the pattern are involved
Apply Intelligently description: ... only When the agent decides it's relevant, based on the description
Apply Manually none of the above Only when you mention it with @rule-name

Older projects sometimes have a single .cursorrules file in the root; that's the legacy format, and current docs only describe .cursor/rules/ (and AGENTS.md). Keep each rule focused and under a few hundred lines. Cursor also has User Rules (Customize → Rules) — personal preferences that apply to Agent chats across all your projects — and Team Rules on business plans, which take precedence.

What to put in rules

Good rules are things the AI can't work out from the code and would otherwise get wrong:

  • Commands: how to install, run, test, lint. "Use pnpm, not npm."
  • Conventions: "Components in PascalCase, one per file." "Use server actions, not API routes, for forms."
  • Boundaries: "Don't edit files in src/generated/." "Never change database migrations that have already run."
  • Gotchas: "Dates are stored in UTC; display them in the user's time zone."
  • Definition of done: "Run pnpm typecheck && pnpm test before saying a task is complete."

What to leave out:

  • Generic advice ("write clean code", "follow best practices") — the model does that anyway.
  • Long documentation — link to it instead.
  • Anything that changes weekly.

Short and specific wins. A 40-line rules file that's all signal beats 400 lines that bury the important bits.

AGENTS.md and CLAUDE.md

  • AGENTS.md is a plain Markdown file in the repo root that a growing list of tools reads (Codex, Cursor, and others). No special header — just instructions.
  • CLAUDE.md is Claude Code's equivalent, loaded at the start of every session, with support for nested files per folder and imports. (How to write a CLAUDE.md)

Using several tools on one project

If your team uses Cursor and Claude Code and Codex, you don't want three diverging copies of the same rules. Options:

  • Keep the main content in AGENTS.md, and have CLAUDE.md import it with a line like @AGENTS.md, adding only Claude-specific notes.
  • Keep Cursor's .cursor/rules for glob-scoped rules (e.g. API-route rules), and keep project-wide guidance in AGENTS.md.

Whatever you choose, have one source of truth and point the others at it.

Rules guide; they don't enforce

Rules are instructions the model usually follows. For things that must always happen — formatting, blocking edits to .env, running tests — use a mechanism that doesn't depend on the model's judgement: a linter, a pre-commit hook, CI, or in Claude Code, hooks.

Keep them alive

  • When the AI makes the same mistake twice, add a rule.
  • When a rule is obsolete, delete it — stale rules cause confusing behaviour.
  • Commit rules to git so the whole team (and every agent) shares them.

The summary

  • Rules files give AI tools project knowledge automatically.
  • Cursor: .cursor/rules/*.mdc with always, auto-attached, agent-requested or manual rules.
  • AGENTS.md and CLAUDE.md are the same idea for other tools; share one source of truth.
  • Keep rules short, specific and current; use hooks and CI for hard requirements.

EasySpawn gives Claude Code (and your rules files) a persistent server, so the project, its CLAUDE.md and its tooling are always in place when the agent picks up the next task. See how it works or join the waitlist.

Related: How to Write a CLAUDE.md · Claude Code vs Cursor · Context Engineering for Coding Agents · Best AI Coding Tools in 2026

Keep reading