Project Rules in Cursor

Cursor project rules make architecture, style, and security conventions available during agent work. This guide shows how to create .mdc files in .cursor/rules/, choose a scope, combine rules with Agent Skills, and verify activation. For the surrounding lifecycle, see Design.

Project rules are Markdown files stored in .cursor/rules/ that inject persistent instructions into Cursor’s context automatically. They eliminate repetitive prompting by teaching the agent your team’s established decisions once.

---

What project rules provide

A structured rules configuration provides four advantages:

• Eliminates repetitive prompting by encoding stack choices, file patterns, and architectural conventions into repository context.
• Targets context efficiently using glob matching and agent-decided activation, avoiding prompt budget exhaustion.
• Enforces non-negotiable boundaries, such as prohibiting direct edits to configuration files or unapproved dependencies.
• Standardizes team practices through shared version control in .cursor/rules/.

---

Rule types and execution triggers

Cursor supports .mdc files with YAML frontmatter to control when rules enter the agent’s context window.

The following table details the four rule types available in Cursor:

Rule Type	Frontmatter Configuration	Trigger Condition
Always Apply	alwaysApply: true	Injected into every chat, Composer session, and agent invocation.
Auto-attached	globs: ["src/components/**/*.tsx"]	Activates automatically when the agent reads or modifies matching files.
Agent-decided	alwaysApply: false + description	Injected when the agent determines relevance based on the description.
Manual	alwaysApply: false (no globs)	Injected only when you explicitly reference @RULE_NAME in chat.

---

Configure project rules

Follow these steps to establish your repository rules structure.

1. Create the rules directory

Create the .cursor/rules/ directory in your repository root:

mkdir -p .cursor/rules

2. Add an always-apply core rule

Create .cursor/rules/core.mdc for non-negotiable standards that must govern every session:

---
description: Core repository standards and boundaries
alwaysApply: true
---

# Project Standards: PROJECT_NAME

## Tech Stack
- Runtime: Node.js 22 with TypeScript 5.x (strict mode)
- Framework: Astro 5 with React 19 components
- Database: Cloudflare D1 with parameterized queries
- Testing: Vitest for unit tests, Playwright for E2E
- Styling: Tailwind CSS

## Code Conventions
- Prefer `const` over `let`; never use `var`.
- Use named exports instead of default exports.
- Error handling: throw custom typed error classes; never throw raw strings.
- File naming: kebab-case for utilities, PascalCase for React components.

## Boundaries & Prohibitions
- Do not install new dependencies without explicit confirmation.
- Do not modify configuration files (`tsconfig.json`, `package.json`, `.dev.vars`) without an approved plan.
- Never modify or delete assertions in existing test files.
- Never write database queries without tenant isolation (`organization_id`).

Replace PROJECT_NAME with the name of your application.

3. Add scoped file-pattern rules

Create targeted rules that activate only when touching specific subsystems:

React Components

---
description: React and Tailwind component standards
globs: ["src/components/**/*.tsx", "src/pages/**/*.astro"]
alwaysApply: false
---

# Component Guidelines

- Author functional components with typed props interfaces.
- Extract stateful hooks into companion files in the same directory.
- Ensure all interactive elements include explicit `aria-label` attributes.
- Use Tailwind utility classes; do not write custom inline styles.

API Routes

---
description: API route patterns, validation, and error response formats
globs: ["src/pages/api/**/*.ts", "src/services/**/*.ts"]
alwaysApply: false
---

# API Route Standards

- Validate all request payloads using Zod schemas before processing.
- Return standardized response payloads: `{ success: boolean, data?: unknown, error?: unknown }`.
- Apply tenant isolation filters on every database query.
- Never expose raw database errors or stack traces to client callers.

Database Operations

---
description: Cloudflare D1 and SQL query conventions
globs: ["src/db/**/*.ts", "migrations/**/*.sql"]
alwaysApply: false
---

# Database Guidelines

- All queries must be parameterized: `db.prepare(QUERY).bind(PARAM_1)`.
- Migrations must reside in `migrations/` with timestamp prefixes: `YYYYMMDD_HHMMSS_DESCRIPTION.sql`.
- Never write migrations that drop columns without a multi-phase transition plan.

---

Agent Skills integration

Cursor discovers modular skills located in .cursor/skills/, .agents/skills/, and .claude/skills/.

While rules (.cursor/rules/*.mdc) act as persistent constraints, skills provide procedural playbooks for complex, multi-step workflows.

To enable Agent Skills in Cursor:

1. Open Cursor Settings (Cmd+, or Ctrl+,).
2. Navigate to Features > Rules for AI.
3. Under Agent Skills, confirm that skills discovery is toggled on.

---

Verify the rules configuration

To confirm that your project rules are active and loaded correctly:

1. Confirm that .cursor/rules/ contains valid .mdc files:

   ls -la .cursor/rules/*.mdc

2. In Cursor, open Chat (Cmd+L or Ctrl+L).
3. Hover over the active context indicator in the chat prompt bar.
4. Confirm that core.mdc appears under the active rules list.
5. Open a file matching src/components/**/*.tsx and verify that the component rule activates automatically.

---

Apply rules to a planned change

PRD Workflow Convert product requirements into structured implementation plans using Cursor Plan mode.