# Cursor Implementation

> Cursor-specific optimization including scoped .mdc rules, glob-based activation, Hooks-based enforcement, and subagent isolation

- **Category**: optimizing-token-usage-practices

- **Canonical URL**: https://designpattern.fyi/optimizing-token-usage-practices/part-v-cursor/

---

## Description
Cursor-specific optimization including scoped .mdc rules, glob-based activation, Hooks-based enforcement, and subagent isolation








## Additional Notes

## Cursor Token Optimization

### Layer 1 — Platform Mechanics

This is the one tool where scoped loading is the *native* primitive rather than an add-on: `.mdc` rules carry `globs` and `description` frontmatter, so a rule for `src/api/**` or `drizzle/**` only enters context when the agent is actually touching those files, instead of sitting in every session's prefix like a flat file would. Use numbered filename prefixes (`000-project.mdc`, `100-typescript.mdc`, `200-api-security.mdc`...) to control concatenation order — earlier rules win on conflict. Delegate isolated or parallel work to subagents in `.cursor/agents/*.md` (review, verify, test personas), and reserve Skills (`.cursor/skills/`) for on-demand procedures — Cursor can even load Skills straight from `~/.claude/skills/` if you're already maintaining those for Claude Code.

**Key Strategies:**
- **Scoped Rules as Native Primitive**: `.mdc` rules with `globs` and `description`
  - Rules only load when matching files are touched
  - Eliminates always-loaded tax for irrelevant rules
  - Example: Rule for `src/api/**` only loads when working on API files
- **Filename Prefix Ordering**: Numbered prefixes control concatenation order
  - `000-project.mdc`, `100-typescript.mdc`, `200-api-security.mdc`
  - Earlier rules win on conflict
  - Predictable rule application
- **Subagent Delegation**: Isolated or parallel work to subagents
  - `.cursor/agents/*.md` for review/verify/test personas
  - Isolated contexts for parallel execution (Cursor 2.4+)
  - Different model tiers per subagent
- **Skills Integration**: Reserve Skills for on-demand procedures
  - `.cursor/skills/` for Cursor-specific skills
  - Can load from `~/.claude/skills/` for cross-tool compatibility
  - Progressive disclosure reduces token overhead

### Layer 2 — Agent Operation

There's no dedicated plan-mode artifact like Antigravity's; the equivalent operational control is Hooks, which can hard-block an expensive or destructive action (a force-push, a migration) before it runs rather than relying on the model to self-police. Team Rules → Project Rules → User Rules precedence means org-wide guardrails should live at the team level so individual projects can't silently loosen them.

**Operational Best Practices:**
- **Hooks for Operational Control**: Hooks replace plan-mode enforcement
  - Hard-block expensive/destructive actions before execution
  - Examples: force-push, database migrations
  - Don't rely on model self-policing
- **Rule Precedence Hierarchy**: Team Rules → Project Rules → User Rules
  - Org-wide guardrails at team level
  - Project-specific rules at project level
  - User personalizations at user level
  - Earlier wins on conflict
- **Guardrail Placement**: Org-wide guardrails at team level
  - Prevents individual projects from silently loosening constraints
  - Consistent enforcement across organization
  - Team-level rules override project/user rules

### Layer 3 — Codebase Architecture

Cursor's own guidance is explicit: put the broad, human-readable operating model (architecture map, ownership, "do not touch" zones — i.e. your Layer 3 conventions) in `AGENTS.md`, and reserve `.cursor/rules/` for instructions you want actively applied while the agent is editing or reviewing code. Don't duplicate one into the other.

**Architecture Rules:**
- **AGENTS.md for Operating Model**: Broad, human-readable architecture guidance
  - Architecture map, ownership, "do not touch" zones
  - Layer 3 conventions
  - Human-readable documentation
- **.cursor/rules/ for Active Instructions**: Instructions applied during editing/reviewing
  - Task-specific guidance
  - Code review standards
  - Active enforcement rules
- **No Duplication**: Don't duplicate between AGENTS.md and .cursor/rules/
  - Each file has distinct purpose
  - Avoid redundant token consumption
  - Clear separation of concerns

## Cursor-Specific Features

### Scoped .mdc Rules
Cursor's `.mdc` rule format with frontmatter provides sophisticated control:
- **Four Activation Modes**: Controlled by frontmatter keys
  - `alwaysApply`: Always loads
  - `globs`: Loads when matching files are touched
  - `description`: Agent-decided based on description
  - Manual `@mention`: Explicit user invocation
- **Glob-Based Activation**: Fine-grained file matching
  - `src/api/**` for API-specific rules
  - `drizzle/**` for database schema rules
  - Eliminates irrelevant context loading
- **Description-Based Activation**: Agent decides based on task description
  - Intelligent rule selection
  - Reduces manual management
  - Agent-aware context loading

### Practical .mdc Examples

#### 000-project.mdc - Always-Apply Entry Point
```markdown
---
description: Project overview and pointer to canonical rules
alwaysApply: true
---

# Project Rules — Entry Point

<!--
  Cursor loads this on every request (alwaysApply: true), so keep it
  minimal. Broad, human-readable operating context (architecture map,
  ownership, "do not touch" zones, conventions) belongs in AGENTS.md —
  don't duplicate it here. This file exists only to point at it and to
  hold the handful of things that genuinely apply to every single
  request regardless of which files are touched.
-->

See `AGENTS.md` at the project root for conventions, commands, and
guardrails.

## Always true, regardless of task

- [Package manager] only — never fall back to another one even if a
  lockfile for it appears.
- Stop and report on the first failing test or build error rather than
  attempting speculative fixes.

For anything file-specific or directory-specific, add a **scoped** rule
(with real `globs`) instead of adding another paragraph here — see
`200-high-risk-paths.mdc` for the pattern.
```

#### 200-high-risk-paths.mdc - Scoped Rule Example
```markdown
---
description: Guardrails for auth, billing, and migration code
globs:
  - "src/api/auth/**"
  - "src/billing/**"
  - "**/migrations/**"
alwaysApply: false
---

# High-risk paths

<!--
  This only enters context when the agent is actually editing a file
  matching one of the globs above — not on every request like
  000-project.mdc. That's the entire point of using a scoped rule
  instead of adding "oh, and be careful with billing code" to the
  always-apply file: the tax is paid only when it's relevant.
-->

- Never modify a migration file that has already been merged — create a
  new migration instead, even to fix a mistake in the previous one.
- Any change touching `src/billing/**` requires a corresponding test in
  the same PR; do not mark the task complete without one.
- Auth changes must not weaken an existing check (session validation,
  role checks, rate limiting) without an explicit instruction to do so.
- Flag, but do not silently fix, any hardcoded credential or API key you
  encounter in these paths — report it and stop.
```

**Key Pattern**: The scoped rule only loads when editing files matching the globs, eliminating the always-loaded token tax for irrelevant code paths.

### Hooks System
Cursor's Hooks provide operational control without plan mode:
- **Pre-Execution Blocking**: Hard-block operations before they run
  - Force-push protection
  - Migration guards
  - Destructive operation prevention
- **Hook Types**: Various hook points for different controls
  - Pre-execution hooks
  - Post-execution hooks
  - File-operation hooks
- **Model-Independent Enforcement**: Hard enforcement regardless of model behavior
  - Don't rely on model self-policing
  - Deterministic operational control
  - Reliable guardrails

### Subagent System
Cursor's subagent system (`.cursor/agents/*.md`) supports isolated parallel work:
- **Isolated Contexts**: Each subagent has separate context
- **Parallel Execution**: Multiple subagents can run in parallel (Cursor 2.4+)
- **Persona-Based Agents**: Review, verify, test personas
- **Independent Model Configuration**: Different models per subagent

### Skills Integration
Cursor's Skills system with cross-tool compatibility:
- **Native Skills**: `.cursor/skills/` for Cursor-specific procedures
- **Claude Skills Loading**: Can load from `~/.claude/skills/`
- **On-Demand Loading**: Skills only load when relevant
- **Progressive Disclosure**: Reduces always-loaded token overhead

### Rule Precedence
Cursor's hierarchical rule loading with conflict resolution:
- **Three-Tier Hierarchy**: Team Rules → Project Rules → User Rules
- **Merge Behavior**: Rules are merged, earlier wins on conflict
- **Org-Wide Enforcement**: Team rules ensure consistent standards
- **Project Flexibility**: Project rules can add, not remove, team constraints
- **User Personalization**: User rules for individual preferences