Cursor .cursor/agents vs Rules — How Do You Split Responsibilities?

In Cursor, .cursor/agents/ and .cursor/rules/ both steer Agent behavior, but at different layers. Rules are persistent instructions injected into model context when they apply. Custom agents (subagents) are specialist children that run in their own context window when the parent delegates, then return a final message. This post is separate from the Skills vs Rules angle (cursor-skills-vs-rules). Here we only cover what goes in agents · what goes in rules · what breaks when they overlap.

No pricing, plans, token quotas, affiliates, or invented reviews. Grounded in Cursor’s official Subagents and Rules docs—behavior, paths, and application only.

What belongs in agents?

One-line answer: Put clear specialist roles there. When you need context isolation—long exploration, independent verification, parallel workstreams—define them as YAML frontmatter + prompt bodies under .cursor/agents/*.md (or user-wide ~/.cursor/agents/).

Put this in agents	Why (documented behavior)
Single-responsibility roles (verifier, debugger, security-auditor)	Subagent works in its own context; parent only gets the final message
A sharp `description`	Agent uses it (Task hints) to decide automatic delegation; you can also call `/name` or ask in natural language
`readonly` / `model` / `is_background`	Execution mode: write limits, inherited or pinned model, non-blocking background
Team-shared specialist defs	Commit project `.cursor/agents/`. On name conflicts: project beats user; within a project `.cursor/` beats `.claude/` / `.codex/`

Documented frontmatter fields (summary):

Field	Default	Role
`name`	filename	Display id (lowercase + hyphens)
`description`	—	Short text Agent reads for delegation
`model`	`inherit`	Same as parent, or a specific model ID
`readonly`	`false`	`true` restricts edits and state-changing shell
`is_background`	`false`	`true` does not block the parent

Minimal verifier example:

---
name: verifier
description: Validates completed work. Use after tasks are marked done.
model: inherit
readonly: true
---

You are a skeptical validator. Verify claimed work actually works.
Run relevant checks. Report passed vs incomplete.

Do not park here: short “always-on” coding norms that must apply every chat. If nothing delegates the subagent, the parent session never sees that text. Docs also point simple one-shot procedures toward Skills (out of scope for this post). Vague descriptions like “helps with coding” give no delegation signal.

repo/
  .cursor/
    agents/
      verifier.md      ← specialist child (isolated context)
      debugger.md
    rules/
      api-conventions.mdc  ← persistent guidance (injected when applied)

What belongs in rules?

One-line answer: Put short, recurring constraints, norms, and architecture decisions in rules. Project rules live as .cursor/rules/*.mdc. When applied, contents are included at the start of model context. A plain .md under .cursor/rules is ignored (no frontmatter). For simple cases, root/nested AGENTS.md is a plain-markdown alternative to Project Rules—and that is not the same as .cursor/agents/.

Rule type	Behavior
Always Apply (`alwaysApply: true`)	Included in every chat; globs/description ignored
Apply to Specific Files (`globs`)	Auto-attached when a matching file is in context
Apply Intelligently (`description`)	Agent pulls it in when relevant
Apply Manually	Only via `@rule`

Frontmatter combinations from the docs:

`alwaysApply`	`description`	`globs`	Behavior
`true`	—	—	Always included
`false`	—	set	Auto-attach on matching files
`false`	set	omitted	Agent includes when relevant
`false`	omitted	omitted	Manual `@` only

Practical placements:

Never edit dist//build/, never hardcode secrets — short alwaysApply: true.
Naming/export rules under src/components/**/*.tsx — globs + alwaysApply: false.
Occasional domain notes — description only (Intelligent).
One-off long checklists — not a fat Rule; split toward Skills/@ files/agents as needed (remember only: long how-tos are a poor Always Rule).

Minimal glob rule:

---
description: API route validation and typed errors
globs: src/routes/api/**/*.ts
alwaysApply: false
---

- Validate inputs at the route boundary.
- Return the existing typed error shape.
- Update the nearest unit test before claiming done.

Docs guidance: keep rules focused (under 500 lines), prefer concrete examples and @ file references, avoid dumping entire style guides. User Rules are global prefs in Customize → Rules for Agent (Chat); they do not apply to Inline Edit (Cmd/Ctrl+K). Team Rules are dashboard-managed; documented precedence when guidance conflicts is Team → Project → User.

What breaks when they overlap?

One-line answer: If the same guidance lives both as an always-injected Rule and as an agent prompt that only runs when delegated, timing and context diverge—you get misses, duplication, or conflicts.

Overlap pattern	What breaks
Stuffing a long multi-step procedure into an `alwaysApply` Rule	Every chat context bloats. Docs push focus and length limits. Procedural work belongs on the agents/skills axis
Putting repo-wide norms only in agents, nowhere in rules	Unless the subagent is delegated, the parent never sees the norm. “Always enforce” fails
Cloning the same ban into Rule and agent body with different wording	Parent sees Rules; child starts clean with only the parent’s handoff + its own prompt. One side drifts → conflict
Vague Intelligent Rule `description` and vague agent `description`	Wrong inclusion timing and wrong delegation
Treating `AGENTS.md` as the same folder as `.cursor/agents/`	`AGENTS.md` = simple Rules alternative. `.cursor/agents/` = subagent definitions. Different paths and jobs
Expecting custom agents to be “always on” after saving a file	Custom subagents start via auto-delegation, `/name`, or a natural-language ask—unlike Always Apply Rules

Safe split checklist:

Must be short and present every (or matching) session → .cursor/rules (or simple AGENTS.md).
Needs isolated specialist work / verification / parallelism → .cursor/agents/.
If a child must obey a norm, do not assume silent inheritance—summarize it in the handoff or encode checks in a readonly verifier agent. Subagents do not get prior chat history by default.
Keep Skills (cursor-skills-vs-rules) separate: norms = Rules, specialist children = Agents, procedural packages = Skills.

Tip: cursor-custom-subagents covers where to define subagents and when to delegate. This post only locks the boundary with Rules.

FAQ

Q. Are .cursor/agents and AGENTS.md the same?
No. AGENTS.md is a plain-markdown alternative to Project Rules. .cursor/agents/*.md defines custom subagents.

Q. Do subagents automatically inherit every Project Rule?
Docs describe subagents starting with a clean context; the parent includes needed information in the prompt. “Always inject” is the Rules axis. If the child needs the same constraint, summarize on handoff or spell it in the agent body.

Q. How is this different from Skills?
Skills are the multi-step procedure package axis. This post is only agents (isolated specialists) vs rules (persistent guidance). See cursor-skills-vs-rules for Skills decisions.

What should you remember?

One sentence for Cursor agents rules: short persistent norms → .cursor/rules (or AGENTS.md); isolated specialist roles → .cursor/agents/. Overlap causes bloat, missed application, or conflicting copies. Keep the Skills angle separate, and split only by official Subagents and Rules behavior.