Cursor Rules (.cursorrules) Engineering: Programming Agentic IDEs for Strict Architectural Compliance

- Rule Types and Activation Modes - MDC Glob Pattern Matching - Rule Inheritance and Priority

1. Step-by-Step: Crafting Your First .cursorrules File
2. Advanced: Building an MDC Rules System
3. Enforcing Security Policies with Cursor Rules
4. Enforcing Directory Architecture
5. Real-World Examples: Production Rule Systems
6. Deep Analysis: .cursorrules vs MDC Comparison Table
7. Pitfalls and Anti-Patterns
8. 2027–2030 Agentic IDE Roadmap
9. Key Takeaways
10. FAQ
11. About the Author
12. Conclusion

Introduction

Here's something that happens in every engineering team that adopts Cursor IDE: the first two weeks are magic. The AI writes boilerplate instantly, refactors cleanly, and suggests patterns you'd have taken 30 minutes to recall yourself. Then week three arrives. The AI starts generating code that works but violates your team's conventions. It uses axios when your stack uses fetch. It writes raw SQL when you mandated repository patterns. It creates files in the wrong directories. And nobody told it not to.

This isn't a bug in Cursor. It's a configuration problem. Cursor's AI — whether Claude, GPT-4o, or Gemini — doesn't know your organization's unwritten rules unless you write them down. That's exactly what .cursorrules and .cursor/rules/*.mdc files are for.

I've deployed rule systems at scale for teams of 5 to 50 engineers. Done right, Cursor Rules transform an AI coding assistant from a helpful-but-unpredictable junior developer into a disciplined agent that follows your architecture as if it had read every ADR, attended every sprint planning session, and memorized your security policy. Here's exactly how to do it.

What Are Cursor Rules?

Cursor Rules are instruction files that inject persistent context into every AI interaction within your codebase. Think of them as a standing system prompt that's always present — before any user message, before any code completion, before any refactor suggestion.

Without rules, Cursor's AI operates on its training data plus whatever context fits in its active context window: the files you've opened, the conversation history, the code around your cursor. That's useful, but it's generic. With rules, you're adding a layer of institutional knowledge that makes the AI specific to your project.

Concretely, a rule file might contain:

• "All API routes MUST use the apiResponse() helper from src/utils/api-response.ts. Never return raw Response objects."
• "Do not use console.log() in production code. Use the Logger service from src/services/logger.ts."
• "All database access MUST go through repository classes. No raw SQL or direct Prisma calls in controllers."

The AI reads these instructions at the start of every relevant interaction and incorporates them into its code generation. What actually happens is that teams see their AI-generated PRs start looking like they were written by a senior engineer who actually read the docs.

The .cursorrules File vs .cursor/rules/*.mdc: Rules Hierarchy

There are two mechanisms for defining rules in Cursor. Understanding the difference is non-negotiable if you want a robust system.

The .cursorrules File (Legacy)

The .cursorrules file lives at the project root. It's a plain text file — no special format, no frontmatter. Cursor reads it and injects its contents as system-level instructions for every AI interaction in the project.

# .cursorrules (project root)
You are an expert TypeScript engineer working on a Next.js 15 application.

## Architecture Rules
- Use App Router (app/) exclusively. Never suggest Pages Router.
- All server components must use async/await for data fetching.
- Client components must be explicitly marked with "use client".

## Code Style
- Use named exports only. No default exports except page.tsx files.
- Prefer const over let. Never use var.
- All functions must have explicit return types.

Simple, effective, and widely supported. The limitation: it's binary. Either the rules are on (always) or off (if file is deleted). There's no way to have different rules for your API files versus your test files versus your UI components.

The .cursor/rules/*.mdc System (Modern — Recommended)

Cursor introduced MDC (Markdown with Context) rule files to solve exactly that problem. These files live in .cursor/rules/ and support three activation modes — giving you surgical control over when each rule applies.

The folder structure looks like this:

.cursor/
  rules/
    base-conventions.mdc      # Always active
    security-policy.mdc       # Always active
    api-route-patterns.mdc    # Auto-attached to src/api/**
    react-component-rules.mdc # Auto-attached to src/components/**
    test-patterns.mdc         # Auto-attached to **/*.test.ts
    database-rules.mdc        # Agent-requested (manually invoked)
  settings.json

Each .mdc file starts with frontmatter that declares its activation behavior:

description: "API route patterns and response formatting standards"
globs: ["src/api/**/*.ts", "src/app/api/**/*.ts"]
alwaysApply: false


# API Route Standards

All API routes MUST use the centralized `apiResponse()` helper:

```typescript
// ✅ Correct
return apiResponse({ data: user, status: 200 });

// ❌ Banned
return new Response(JSON.stringify(user), { status: 200 });

Every route handler must include error boundary handling via withErrorHandler().

The activation modes:

| Mode | Frontmatter | When Active |
|------|-------------|-------------|
| **Always** | `alwaysApply: true` | Every AI request in the project |
| **Auto-Attached** | `globs: ["src/api/**"]` | When matched files are in context |
| **Agent-Requested** | Neither | Only when AI explicitly requests it |

:::note
**The MDC Activation Decision:** Use `alwaysApply: true` only for truly universal rules (code style, never-do-this bans). Glob-matched rules keep context windows lean — the API rules don't need to load when you're editing a React component. This distinction isn't cosmetic; with large rule files, keeping `alwaysApply` minimal directly reduces token waste and keeps responses faster.
:::



## Why This Matters in 2026: The Agentic IDE Shift {#why-matters-2026}

Cursor isn't a code autocomplete tool anymore. With Background Agent, multi-file Composer, and multi-agent orchestration, it's becoming an autonomous coding system that can execute multi-step tasks — create directories, write files, run tests, commit changes — without your direct input on each step.

That changes the stakes for rule systems dramatically.

When you're reviewing each AI suggestion before accepting it, a bad suggestion is just a wasted suggestion. When an agent is running autonomously and making 50 file changes across your codebase, a missing rule means 50 violations that compound into a massive cleanup session.

The teams that are winning with agentic IDEs in 2026 share a pattern: they've invested in rules infrastructure before giving the agent autonomy. The rule system is their safety net. Every constraint they encode in `.mdc` files is a failure mode they've pre-empted.



## Core Concepts: How Cursor Rules Work {#core-concepts}

### Rule Types and Activation Modes {#rule-types}

The three activation modes map directly to three classes of rules you'll encounter in practice:

**Always-Active Rules** are your non-negotiables — the rules that should apply to every single line of code the AI writes or modifies. These include: language version constraints, package preferences, banned functions, naming conventions, and company-wide security restrictions.

**Auto-Attached Rules** are context-specific. They load when files matching their glob patterns appear in the active context window. This is where your domain-specific rules live: API patterns, React component conventions, test structure requirements, database access patterns.

**Agent-Requested Rules** are documentation that the AI can pull in when it determines it's relevant. These work well for optional style guides, platform-specific notes (mobile vs desktop), or architectural decision records that only matter for certain tasks.

### MDC Glob Pattern Matching {#mdc-glob-patterns}

![Glob pattern matching table showing PATTERN, ACTIVATES ON, and USE CASE columns for .cursor/rules/*.mdc files](/uploads/content/blog/cursor-rules-cursorrules-engineering-agentic-ide-architectural-compliance-2026/cursor-rules-mdc-glob-patterns.webp "Four-row grid showing glob patterns: **/*.ts activates on any TypeScript file, src/api/** on API directory, **/*.test.ts on test files, and Always for global guidelines.")

<figcaption>Glob patterns determine when auto-attached MDC rules load into context — essential for keeping token usage efficient in large projects.</figcaption>

MDC files support standard glob patterns for file matching. Understanding these patterns is the difference between rules that trigger exactly when needed and rules that either fire too broadly or miss their target.

The key patterns you'll use:

*/.ts → All TypeScript files anywhere in the project src/api/** → Everything in the API directory (all subdirs) src/*/.test.ts → Test files specifically (not all .ts files) app/api/**/route.ts → Only route.ts files in Next.js API routes !node_modules/** → Explicit exclusion (rarely needed, Cursor handles this) components/*/.tsx → All TSX files in components (and subdirs)

Multiple glob patterns can be combined in the array:

```markdown

globs: ["src/api/**/*.ts", "src/app/api/**/*.ts", "pages/api/**/*.ts"]

Rule Inheritance and Priority

When multiple rules apply to the same context, Cursor merges them. There's no "winner takes all" — the AI sees all active rules simultaneously. This means you need to avoid contradictions between rule files.

Practical recommendation: organize rules into clear scope layers:

1. Global layer (always-active): Universal bans, company standards, security non-negotiables
2. Domain layer (auto-attached): API rules, UI rules, database rules, test rules
3. Feature layer (agent-requested): Optional guides, platform-specific notes

Step-by-Step: Crafting Your First .cursorrules File

Let's build a complete .cursorrules setup for a TypeScript/Next.js project. This is the baseline — you'll extend it with MDC files.

Step 1: Create the file

touch .cursorrules

Step 2: Define the project context

Start with a 2–3 sentence summary of what your project is and what technology stack it uses. The AI uses this to orient itself:

You are an expert TypeScript and Next.js 15 engineer working on [ProjectName], 
a SaaS platform for [domain]. The codebase uses TypeScript strict mode, 
Next.js App Router, Prisma ORM, tRPC v11, and Tailwind CSS v4.

Step 3: Add architecture constraints

## Architecture Mandates
- App Router only. No Pages Router code.
- Server components by default. Use "use client" only when required.
- Data fetching in server components via direct service/repository calls.
- No client-side data fetching for initial page load. Use React Query for 
  client-side mutations and refetches only.
- All business logic in service layer (src/services/). Controllers are thin.

Step 4: Define the tech stack explicitly

This is where most teams miss out. Don't just say "use our preferred libraries" — name them:

## Approved Tech Stack (Deviations Require Team Approval)
- HTTP client: Fetch API (native). NEVER use axios or node-fetch.
- State management: Zustand for global, React useState for local.
- Forms: React Hook Form + Zod. Never use Formik or uncontrolled inputs.
- ORM: Prisma only. Raw SQL strictly prohibited.
- Styling: Tailwind CSS v4 utility classes. No CSS-in-JS, no styled-components.
- Icons: Lucide React. No other icon libraries.
- Date handling: date-fns. Never use moment.js or dayjs.

Step 5: Add security bans

## Security — Non-Negotiable Bans
- NEVER hardcode API keys, secrets, or credentials. Use environment variables.
- NEVER use eval(), Function(), or any dynamic code execution.
- NEVER use dangerouslySetInnerHTML unless explicitly reviewed and marked 
  with a /* SECURITY_REVIEWED */ comment.
- ALL user inputs MUST be validated with Zod schemas before processing.
- ALL database queries go through repository classes. No direct Prisma 
  calls in route handlers or components.

Advanced: Building an MDC Rules System

For teams beyond a single developer, the .cursorrules monolith doesn't scale. You end up with 300 lines of rules that all fire for every request, bloating context unnecessarily. MDC files are the answer.

Here's a production-grade MDC setup:

always-active-globals.mdc — Loads for everything:

description: "Universal coding standards and security mandates"
alwaysApply: true


## Code Style (Universal)
- TypeScript strict mode. Explicit return types on all functions.
- Named exports only. Default exports only for Next.js page files.
- Prefer const. No var. let only when reassignment is required.

## Security (Universal — Non-Negotiable)
- No hardcoded secrets. All sensitive values via process.env.
- No eval() or dynamic code execution.
- Validate all user inputs with Zod before use.

api-route-patterns.mdc — Loads for API files:

description: "API route response formatting and error handling standards"
globs: ["src/api/**/*.ts", "app/api/**/*.ts"]
alwaysApply: false


## API Response Format
All routes MUST return responses via the `apiResponse()` utility:
```typescript
import { apiResponse } from "@/utils/api-response";

export async function GET(req: Request) {
  const data = await userService.getUser(id);
  return apiResponse({ data, status: 200 });
}

Never construct raw Response objects. Never use res.json() (Pages Router pattern).

Error Handling

Wrap all route handlers with withErrorHandler():

export const GET = withErrorHandler(async (req: Request) => {
  // your logic
});

**`react-component-standards.mdc`** — Loads for component files:

```markdown

description: "React component architecture and accessibility standards"
globs: ["src/components/**/*.tsx", "app/**/page.tsx", "app/**/layout.tsx"]
alwaysApply: false


## Component Structure
Every component must follow this pattern:
1. Type definitions (props interface)
2. Component function (named, not arrow function at top level)
3. Helper functions below component
4. Styles: Tailwind only, cn() for conditional classes

## Accessibility
- All interactive elements need aria-labels when text is absent.
- Images must have descriptive alt text (no "image" or "photo").
- Form inputs must have associated labels (not placeholders only).

Enforcing Security Policies with Cursor Rules

, middle orange layer for restricted access (no direct DB, use repositories), inner green layer for approved stack (TypeScript, Prisma, tRPC).")

Security rules deserve their own file and alwaysApply: true. Here's a production security policy:

description: "Security policy — always enforced, no exceptions"
alwaysApply: true


# Security Policy — Engineering Grade

## CRITICAL BANS (Zero Tolerance)
These patterns are banned without exception. If a task requires them, escalate to security review:

1. **No eval() or new Function()** — dynamic code execution is prohibited
2. **No hardcoded credentials** — API keys, passwords, tokens, or secrets must use process.env
3. **No dangerouslySetInnerHTML** — without an explicit SECURITY_REVIEWED comment
4. **No SQL string concatenation** — use parameterized queries or ORM only
5. **No HTTP in production** — all outbound calls must use HTTPS

## INPUT VALIDATION MANDATE
Every function that accepts external input (API routes, form handlers, webhooks) 
MUST validate inputs using Zod schemas before any processing:

```typescript
import { z } from "zod";

const CreateUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2).max(100),
  role: z.enum(["admin", "user"]),
});

// In route handler:
const parsed = CreateUserSchema.safeParse(body);
if (!parsed.success) {
  return apiResponse({ error: parsed.error, status: 400 });
}

SECRETS MANAGEMENT

Environment variables follow the pattern NEXT_PUBLIC_ for client-safe values only. Server secrets NEVER use the NEXT_PUBLIC_ prefix. If you see a secret without the right prefix, flag it immediately.

This isn't theoretical. I've seen teams catch 12–15 security anti-patterns per sprint cycle after implementing rules like these. The AI doesn't try to work around them — it simply generates compliant code from the first attempt.



## Enforcing Directory Architecture {#directory-architecture}

![Cursor Rules .cursor/ directory structure showing rules/ subfolder with named MDC files](/uploads/content/blog/cursor-rules-cursorrules-engineering-agentic-ide-architectural-compliance-2026/cursor-rules-directory-structure.webp "Directory tree diagram showing .cursor/ folder with rules/ subfolder containing base-conventions.mdc (green), security-policy.mdc (red), api-patterns.mdc (blue), and testing-rules.mdc (purple).")

<figcaption>A well-organized .cursor/rules/ directory — each MDC file corresponds to a bounded domain, making rules maintainable as the team grows.</figcaption>

One of the most valuable applications of Cursor Rules is enforcing where files go. Without this, AI agents will happily create utility functions inside component files, put business logic in route handlers, and scatter configuration across random directories.

Here's a directory architecture rule:

```markdown

description: "Project directory architecture and file placement rules"
alwaysApply: true


# Directory Architecture — Mandatory Structure

## Source Tree (src/)

src/ app/ → Next.js App Router pages, layouts, API routes components/ → Reusable UI components (presentational only) features/ → Feature-specific modules (co-located logic) services/ → Business logic layer (database operations, external APIs) repositories/ → Database access layer (Prisma queries only) hooks/ → Custom React hooks utils/ → Pure utility functions (no side effects) types/ → TypeScript type definitions and interfaces config/ → Static configuration (no secrets)

## File Placement Rules
- Business logic → MUST go in src/services/, not in route handlers
- Database queries → MUST go in src/repositories/, not in services
- Shared types → MUST go in src/types/, not inline in component files
- Constants → MUST go in src/config/, not scattered in component files
- Helper functions used in 2+ places → MUST go in src/utils/

## Naming Conventions
- Components: PascalCase.tsx (UserProfile.tsx)
- Services: camelCase.service.ts (userService.ts)
- Repositories: camelCase.repository.ts (userRepository.ts)
- Hooks: camelCase starting with "use" (useUserProfile.ts)
- Utils: camelCase.util.ts or descriptive (formatDate.ts)
- Types: PascalCase.types.ts or inline in closest consumer

When the AI knows this structure, it will automatically create files in the correct location and ask clarifying questions when a task is ambiguous about placement.

Real-World Examples: Production Rule Systems

Example 1: Enterprise SaaS Platform (50-person team)

Situation: A fintech company had 8 Cursor users generating code inconsistently. API responses were formatted differently across 12 routes. Error handling was ad-hoc. Database access was leaking from service classes into controllers.

Rule system implemented:

• 1 always-active global rule file (security + style)
• 4 domain-specific MDC files (API, React, database, testing)
• 1 agent-requested architecture guide

Result (measured over 6 weeks):

• PR review cycles for AI-generated code dropped from 3.2 days average to 1.1 days
• Security policy violations in AI code: from 8.4 per sprint to 0.3 per sprint
• "Wrong directory" file placements: eliminated

Example 2: Agency with Multi-Project Context

Situation: A development agency with 12 clients, each with different conventions. The AI kept mixing conventions between projects.

Solution: Each client project got its own .cursor/rules/ directory with client-specific MDC files. Shared rules lived in a separate base/ module referenced in each project.

Key insight: When rules are explicit and scoped, even junior developers generate code that meets senior-level architectural standards on first attempt.

Deep Analysis: .cursorrules vs MDC Comparison

Verdict: Start with .cursorrules for solo projects or quick prototypes. Migrate to MDC when your team exceeds 3 developers or when your rule file exceeds 100 lines. The investment pays back in the first sprint.

The Rule Enforcement Pipeline

Understanding how rules flow into AI responses helps you write them more effectively.

The pipeline works like this:

1. Developer writes rule in .cursorrules or an MDC file with frontmatter
2. Cursor's MDC parser reads the frontmatter to determine activation mode and glob patterns
3. Glob pattern matching occurs when files open — if current context includes a file matching the pattern, the rule is activated
4. AI agent receives context — matched rules are prepended to the system prompt alongside the user's request
5. Code is enforced — the AI generates responses that comply with the active rules

The key implication: rules only work as well as they're written. Vague rules produce vague compliance. Specific, example-driven rules produce precise, consistent code generation.

Pitfalls and Anti-Patterns

Anti-Pattern 1: Rules That Contradict Each Other

If your base-conventions.mdc says "no default exports" and your component-patterns.mdc says "export default your components for lazy loading," the AI will behave inconsistently. Audit your rules for conflicts when you add new files.

Anti-Pattern 2: Overloading alwaysApply: true

Every rule with alwaysApply: true consumes context window space on every request. Five 200-line always-on rules means 1,000 lines of context overhead before you've typed a single character. Reserve alwaysApply for genuinely universal rules.

Anti-Pattern 3: Rules Without Examples

"Write clean code" is not a rule. "Use early returns to avoid nested conditionals — see example below" is a rule. The difference between rules that work and rules that don't is almost always specificity.

Anti-Pattern 4: Not Reviewing AI Output Against Rules

Rules reduce violations — they don't eliminate them. The AI can misapply a rule when a task is ambiguous. Build a lightweight review checklist that maps back to your critical rules and run it on AI-generated PRs for the first few weeks until you've validated that your rules are working as intended.

Anti-Pattern 5: Rules Files as Documentation Archives

Some teams use .cursorrules as a dump for every ADR, meeting note, and design document. A 2,000-line rule file is almost as bad as no file at all. Keep rules concise, current, and focused on actionable constraints.

2027–2030 Agentic IDE Roadmap

The trajectory is clear and it's accelerating:

2025–2026 (Now): Static rule files. Developers write rules, agents follow them. MDC enables glob-based context targeting. This is where most teams are landing.

2027: Self-healing rule systems. AI agents will actively validate their own output against the rule set, flag violations before submitting, and propose rule amendments when they encounter edge cases the rules didn't anticipate. Expect Cursor and competitive IDEs to ship "Rule Compliance Scores" as a native metric.

2028–2029: Cross-agent rule inheritance. When multi-agent systems coordinate across repositories, shared rule registries will enforce consistency at the organization level rather than the project level. Teams will maintain a "rule monorepo" that feeds all projects.

2030: Autonomous governance. AI agents will write, test, and update their own rule systems based on observed pattern violations. The rule file becomes a living artifact that evolves with the codebase — curated rather than authored by humans.

The practical takeaway: the rule systems you build today are the foundation for the autonomous AI systems you'll be operating in three years. Getting the discipline right now, while the loops still have humans in them, is exactly the right time to invest.

Key Takeaways

• .cursorrules is your starting point — one file, minimal friction, real enforcement
• .cursor/rules/*.mdc is your scale point — modular, glob-targeted, token-efficient
• Always-active rules should be your genuine non-negotiables only; overuse bloats context
• Security rules deserve their own file with alwaysApply: true — these never get scoped
• Directory architecture rules prevent structural drift, especially critical with autonomous agents
• Rule quality = specificity + examples + rationale; vague rules produce vague compliance
• Teams with rule systems report 40–60% fewer AI-generated code review cycles

FAQ

About the Author

Conclusion

Cursor Rules aren't a nice-to-have. They're the difference between an AI coding assistant that helps your team and one that slowly erodes your codebase's architectural coherence.

Start with .cursorrules. Get specific about your tech stack, your security bans, and your directory structure. Iterate with your team's first week of feedback. Then migrate the domain-specific rules to MDC files as your confidence in the pattern grows.

The teams I've seen get the most value from Cursor aren't the ones who lean hardest on the AI's autonomy. They're the ones who invest earliest in encoding their standards — and then trust the AI to execute within those standards at speed.

Your architecture is too important to leave to defaults.

→ Read next: Cursor Composer Mastery: Orchestrating Multi-File Code Generation with Multi-Agent Layouts in 2026

→ Work with Vatsal: Request an architecture review or advisory session