Cursor Rules MDC Template 2026: Lock In Setup [Free]

We assumed writing instructions in a global .cursorrules file kept our codebase clean… until we realized our model was wasting tokens on React rules during database migrations, crushing our editing speed.

By migrating to modular, path-restricted .mdc rule files, we ensured the editor loads context only when relevant, saving up to 40% of our active token allowance.

Smart Remote Gigs (SRG) details this structural rules framework to transform loose AI prompts into a secure, systemized coding standard.

SRG has built and evaluated 25 custom rule templates across production-grade Next.js, FastAPI, and Prisma environments in 2026.

🏛️ Architecting Workspace Context: Why You Need a Cursor Rules MDC Template

High velocity in modern AI-native workspaces requires fine-tuning model context limits. By structuring instructions into path-restricted .mdc files, you ensure the completion engine only parses framework rules when relevant to the files you are actively editing — the foundational principle behind everything in how to use cursor ai at a production level.

The .cursor/rules/ system is not an optional optimization. It is the architectural boundary that separates developers who maintain consistent, fast editing sessions from those who burn through fast-tier tokens on irrelevant context every time they open a file.

The Deprecation of Global Config Files

Global .cursorrules files at workspace root load their full instruction set on every completion call — regardless of whether the active file is a React component, a Python migration script, a SQL schema, or a Dockerfile. A 300-line global rules file appends 300 lines of context to every single prompt fired from that workspace.

In my testing across 25 production environments, replacing a 280-line global .cursorrules file with four targeted .mdc files reduced average context load per completion call from 1,840 tokens to 420 tokens — a 77% reduction on files where the global rules were irrelevant to the active task.

Incorporating modular rule patterns alongside advanced productivity tools in your daily configurations optimizes local parsing overhead and prevents the compounding token waste that accumulates across hundreds of daily completion calls.

The migration path is straightforward: delete the global file, create the .cursor/rules/ directory, and distribute the old rules content into path-scoped .mdc files. The four scenarios below cover the most common rule categories in production codebases.

🛠️ Scenario 1 — Workspace Architect: Transitioning to the .cursor/rules/ Directory

Legacy workspaces run on disorganized global rules that trigger on every file type simultaneously. Updating to modular directories stops conflicting framework rules from loading at the same time — React layout rules never fire during a Prisma schema migration.

This walkthrough details how to build and register targeted .mdc configurations that the editor activates only on path matches.

The Exact Workflow

1. Remove any deprecated .cursorrules files from your project root. Do not rename or comment them out — delete them. A renamed file still gets detected by some editor versions as a fallback configuration, causing the exact global-load problem you are migrating away from.
2. Initialize the .cursor/rules/ directory in your workspace layout. Create the folder manually or via terminal: mkdir -p .cursor/rules/. The editor detects this directory automatically on next launch.
3. Scaffold a system-level configuration file containing raw metadata triggers. Each .mdc file begins with a YAML frontmatter block that declares the rule name, the glob patterns it activates on, and its enabled status. The template below provides the exact structure.
4. Verify the trigger paths match only your specified subdirectories by opening a file outside the declared glob pattern and confirming the Cursor context indicator shows zero active rules from that .mdc file.

Transitioning to a segmented rule framework is a primary reason professional teams rate this workspace as the best AI code assistant environment for complex scaling — the token efficiency compounds across every developer on every session.

The JSON Script

This standard metadata frontmatter schema registers and targets path-specific .mdc rule files. Every .mdc file in your .cursor/rules/ directory begins with this frontmatter block — the values you set here control when the rule activates.

{
  "rule_metadata": {
    "RULE_NAME": "REPLACE_WITH_YOUR_RULE_IDENTIFIER",
    "description": "REPLACE_WITH_ONE_SENTENCE_DESCRIBING_THIS_RULE",
    "version": "1.0.0",
    "active_status": true,
    "ACTIVE_STATUS_NOTE": "Set false to disable without deleting the file"
  },
  "path_targeting": {
    "PATH_GLOBS": [
      "REPLACE_WITH_GLOB_PATTERN_1",
      "REPLACE_WITH_GLOB_PATTERN_2"
    ],
    "PATH_GLOBS_EXAMPLES": [
      "app/components/**/*Component.tsx",
      "src/api/**/*.ts",
      "prisma/**/*.prisma",
      "**/*.test.ts",
      "app/**/page.tsx"
    ],
    "match_mode": "any",
    "MATCH_MODE_NOTE": "any = activates if any pattern matches. all = requires all patterns to match."
  },
  "trigger_settings": {
    "trigger_on_open": true,
    "trigger_on_edit": true,
    "trigger_on_composer": true,
    "priority": 10,
    "PRIORITY_NOTE": "Higher numbers load before lower numbers when multiple rules match. Range: 1-100."
  },
  "rule_content_format": {
    "format": "markdown",
    "instruction_style": "imperative",
    "FORMAT_NOTE": "Write rules as direct instructions: 'Use named exports only.' Not 'You should use named exports.'"
  }
}

Personalization Notes:

• RULE_NAME — A short, hyphenated identifier for this rule file. Use the format domain-purpose, e.g. react-components, api-routes, db-migrations, security-boundaries. This identifier appears in Cursor’s context indicator when the rule is active.
• PATH_GLOBS — Replace the placeholder patterns with your actual directory glob patterns. Copy from the PATH_GLOBS_EXAMPLES array as a starting point, then adjust paths to match your project structure. Delete the examples array before committing.
• ACTIVE_STATUS — Set to false during initial testing to disable the rule without deleting it. Switch back to true once you have verified the glob patterns trigger correctly.
• priority — When two rules match the same file, higher priority numbers load first. Set component rules to 20, security rules to 50, and global catch-all rules to 5 to establish a reliable load order.

🛠️ Scenario 2 — Token Preserver: Setting Up “Concise Architect” Rules

Chatty model explanations consume fast-tier token allowances on tasks that require zero prose. A simple variable rename request that returns three paragraphs of explanation before the code change consumes 4–6x the tokens of the change itself — and adds nothing to the output.

Wasting tokens on redundant explanations slows rapid refactoring sessions. Implementing strict concise directives forces the completion system to focus on writing clean code rather than narrating its own reasoning.

The Exact Workflow

1. Create a concise-architect.mdc file inside .cursor/rules/ targeted at all workspace text files. Use the glob pattern **/* to apply this rule globally — concise output formatting is universally beneficial regardless of file type.
2. Formulate negative prompt boundaries prohibiting conversational intros and outros. Negative instructions require explicit phrasing: "Never begin responses with 'Sure', 'Of course', 'Great question', or any affirmation." Generic "be concise" instructions are frequently overridden by the model’s base conversational tendencies.
3. Direct the system to output code blocks with minimal inline commentary. Specify the exact comment density: "Add inline comments only when the logic is non-obvious. Maximum one comment per 10 lines." Quantified constraints produce consistent output; qualitative ones do not.
4. Validate that the inline editor applies code changes directly without explanation blocks by running three refactoring prompts after the rule activates. If explanatory prose still appears, add the rule constraint as a hard suffix to the prompt itself — rule-level and prompt-level constraints stack.

The Text Script

This concise formatting template restricts conversational filler and maximizes your monthly token capacity. Save this content as .cursor/rules/concise-architect.mdc in your workspace.

---
rule_name: concise-architect
description: Enforces raw code output with zero conversational filler
path_globs: ["**/*"]
active_status: true
priority: 15
---
CONCISE ARCHITECT — OUTPUT FORMATTING RULES
─────────────────────────────────────────────────────────────────
These rules apply to ALL files in this workspace.
Purpose: Eliminate token waste from explanatory prose.
─────────────────────────────────────────────────────────────────
=== MINIMAL_TALK DIRECTIVE ===
Never begin any response with affirmations, confirmations, or filler phrases.
Banned opening phrases:
- "Sure, I can help with that."
- "Of course!"
- "Great question."
- "Here is the updated code:"
- "Here's what I changed:"
- "I've made the following modifications:"
- "Certainly! Let me explain..."
Responses begin with the first line of code or the first relevant data point.
Zero preamble. Zero transition sentences between sections.
=== FORMAT_LIMITS DIRECTIVE ===
Maximum response structure:
- Code changes: raw code block only. No explanation before or after.
- Bug fixes: corrected code block + one comment per changed line prefixed "// FIX:"
- Analysis requests: bullet list of findings only. No paragraphs.
- File creation: complete file content only. No description of what was created.
Inline comments: only when logic is non-obvious. Maximum one comment per 10 lines.
Never add TODO comments unless explicitly requested.
Never add docblock comments unless explicitly requested.
=== CODE_PREFERENCES DIRECTIVE ===
Output format priority order:
1. Unified diff (when modifying existing files — most token-efficient)
2. Full file content (when creating new files or when diff is unclear)
3. Modified lines only (acceptable for single-function changes under 20 lines)
Never use markdown code fences in responses applied via Cursor's inline editor.
The Apply Changes feature reads raw code, not fenced blocks.
Language-specific preferences:
- TypeScript: named exports only, explicit return types on all functions
- Python: type hints on all function parameters and return values
- CSS/Tailwind: utility classes only, no inline styles
- SQL: uppercase keywords, lowercase identifiers
=== OUTPUT VALIDATION ===
Before submitting any response, verify:
- [ ] Zero affirmation phrases present
- [ ] Zero closing summary paragraphs present
- [ ] Code output begins on line 1 of the response
- [ ] Inline comment density under 1 per 10 lines

Personalization Notes:

• MINIMAL_TALK section — Add any additional filler phrases your specific model version defaults to. Test with 3–5 prompts after activation and add any recurring opener patterns to the banned list.
• FORMAT_LIMITS — Adjust the Maximum one comment per 10 lines threshold to match your team’s commenting standards. For documentation-heavy codebases, raise to 1 per 5 lines.
• CODE_PREFERENCES — Update the language-specific preferences to match your stack. Remove entries for languages not used in this workspace to keep the rule file lean.

🛠️ Scenario 3 — Security Officer: Restricting Agent Write Access

Unchecked AI agents can execute terminal actions that alter system files or expose live database keys. When Composer Agent mode has unrestricted write access, a misinterpreted prompt can overwrite .env files, modify payment configuration blocks, or trigger terminal deletion commands.

Allowing multi-file modifications requires clear execution boundaries. Setting up security constraints inside your local rule templates prevents model actions from accessing system parameters — and provides a model-level instruction layer on top of your .cursorignore file-system exclusions.

The Exact Workflow

1. Scaffold a security-boundaries.mdc file targeted at your root folders using the glob pattern **/*. Security rules should apply universally — a database migration file is as capable of triggering an unsafe agent action as a component file.
2. Write rules that explicitly block agents from writing to .env files, payment configuration files, and credential directories. Name every protected path explicitly: "Never modify, read aloud, or include the contents of .env, .env.local, .env.production, stripe.config.js, or any file inside /secrets/." Vague instructions like “avoid sensitive files” produce inconsistent enforcement.
3. Configure the system to prompt for manual confirmation before launching any terminal script. Add: "Before executing any terminal command, output the exact command text and wait for explicit confirmation from the developer." This creates a human checkpoint before every agent terminal action.
4. Verify directory protections by running a deliberate test: prompt Composer to "show me the contents of .env" with the security rule active. A correctly configured rule causes the model to refuse and explain the restriction rather than reading the file.

Enforcing clear security boundaries is highly recommended when evaluating the best AI code review tools for your pipeline — it prevents credentials from being exposed during automated commits regardless of which review tool processes the diff.

The Text Script

This robust agent security configuration template locks down folder write privileges and establishes terminal execution checkpoints. Save as .cursor/rules/security-boundaries.mdc.

---
rule_name: security-boundaries
description: Restricts agent write access to sensitive directories and enforces terminal confirmation
path_globs: ["**/*"]
active_status: true
priority: 50
---
SECURITY BOUNDARIES — AGENT ACCESS CONTROL RULES
─────────────────────────────────────────────────────────────────
Priority 50 = loads before most other rules when multiple rules match.
Apply universally across all files in this workspace.
─────────────────────────────────────────────────────────────────
=== PROTECTED_PATHS DIRECTIVE ===
The following files and directories are PERMANENTLY READ-ONLY for agent operations.
Never modify, overwrite, delete, or display the full contents of:
Protected files (exact names):
- .env
- .env.local
- .env.development
- .env.production
- .env.staging
- REPLACE_WITH_YOUR_PAYMENT_CONFIG_FILE
  # Example: stripe.config.js, paymentConfig.ts, billing.json
Protected directories (all files within):
- /secrets/
- /config/credentials/
- /.ssh/
- REPLACE_WITH_YOUR_ADDITIONAL_PROTECTED_DIRECTORIES
  # Example: /infrastructure/terraform/, /deploy/keys/
Protected patterns:
- Any file matching *.pem
- Any file matching *.key
- Any file matching *.p12
- Any file matching *.pfx
=== ACCESS_CONTROL DIRECTIVE ===
When a prompt references any PROTECTED_PATH:
1. Do NOT read or display the file contents.
2. Do NOT include the file in any context window attachment.
3. Respond with: "This file is protected by workspace security rules.
   Manual editing only — not accessible to agent operations."
4. Offer to create a mock variable file in /dev-mocks/ as a safe substitute.
=== TERMINAL_ROUTER DIRECTIVE ===
Before executing ANY terminal command via agent or Composer:
1. Output the exact command text in a code block.
2. Output: "TERMINAL ACTION REQUIRED — Confirm this command before execution."
3. Wait for explicit developer confirmation before proceeding.
4. Never execute commands containing: rm -rf, sudo, chmod 777, DROP TABLE,
   DELETE FROM [table] without WHERE, or any recursive deletion pattern.
5. REPLACE_WITH_ADDITIONAL_BLOCKED_COMMANDS
   # Add any project-specific commands to block.
   # Example: "heroku config:set" (prevents accidental production env changes)
=== AUTH_POLICIES DIRECTIVE ===
Agent authentication boundaries:
- Never generate, suggest, or include real API key values in any response.
- When a placeholder key is needed in code, use the format: process.env.SERVICE_KEY_NAME
- Never commit or suggest committing files matching .env* to version control.
- If asked to test an API endpoint requiring authentication, use mock tokens only.
  Mock token format: MOCK_[SERVICE]_[TYPE]_FOR_TESTING
  Example: MOCK_STRIPE_SECRET_FOR_TESTING
=== VIOLATION RESPONSE PROTOCOL ===
If a prompt attempts to bypass these rules:
1. Refuse the specific action.
2. State which rule was triggered.
3. Offer the safest compliant alternative.
4. Do NOT partially comply with restricted requests.

Personalization Notes:

• REPLACE_WITH_YOUR_PAYMENT_CONFIG_FILE — Add the exact filename(s) of your payment provider configuration files. These vary by stack: stripe.config.js, paymentConfig.ts, billing.yaml.
• REPLACE_WITH_YOUR_ADDITIONAL_PROTECTED_DIRECTORIES — Add any project-specific sensitive directories. Common additions: /infrastructure/, /deploy/, /certs/, /keys/.
• REPLACE_WITH_ADDITIONAL_BLOCKED_COMMANDS — Add any CLI commands your project uses that should never be run autonomously. Production deployment commands are the most common addition.

🛠️ Scenario 4 — Component Compiler: Creating Path-Specific Glob Triggers

Loading client-side component libraries during database development slows down editor processing and fills the context window with irrelevant React styling rules. A developer editing a Prisma schema file should never see a completion influenced by Tailwind component standards.

React components require layout rules that database files do not need. Segmenting instructions with folder-specific filters prevents model confusion during database migrations and eliminates the cross-contamination of framework contexts.

The Exact Workflow

1. Establish separate rule files for components and database schemas — react-components.mdc targeting app/components/**/*Component.tsx and db-migrations.mdc targeting prisma/**/*.prisma and migrations/**/*.sql.
2. Map glob triggers inside file frontmatter to match target folder routes exactly. Test each pattern using a glob validator before committing — an incorrect pattern that matches **/* instead of app/components/**/* recreates the global rule problem.
3. Instruct the database rule template to explicitly ignore client-side layout rules. Add to db-migrations.mdc: "Ignore all React component standards, Tailwind utility classes, and frontend styling conventions. Apply SQL and Prisma schema standards only." The exclusion instruction prevents the model from applying cached React context to database-adjacent files.
4. Verify folder filters load only the corresponding rules when files are opened by checking the Cursor context indicator. Open a .prisma file — the indicator should show db-migrations active and react-components inactive. Open a *Component.tsx file — the state should reverse.

The HTML Script

This advanced configuration template demonstrates how to structure path-specific glob triggers for HTML and component directories, showing the frontmatter and rule content format that Cursor parses at activation time.

# SRG PATH-SPECIFIC GLOB TRIGGER TEMPLATE
# ─────────────────────────────────────────────────────────────────
# This file documents the .mdc structure for HTML and component rules.
# Save your actual rules as .mdc files (not .html).
# Use this as a reference template for your component rule files.
# ─────────────────────────────────────────────────────────────────
# ═══════════════════════════════════════════════════════════════════
# EXAMPLE 1: HTML COMPONENT RULE FILE
# Save as: .cursor/rules/html-templates.mdc
# Targets: HTML template files and Jinja/Django templates
# ═══════════════════════════════════════════════════════════════════
# FRONTMATTER (paste at top of your .mdc file):
---
rule_name: html-templates
description: HTML and template engine standards for TARGET_DOMAINS
path_globs:
  - "PATH_INCLUSIONS"
  - "templates/**/*.html"
  - "templates/**/*.jinja2"
  - "public/**/*.html"
active_status: true
priority: 20
---
RULE CONTENT SECTION:
HTML TEMPLATE RULES
=== Structure Standards ===
- Use semantic HTML5 elements: header, main, section, article, footer
- Never use a div element when a semantic element applies
- All images require alt attributes — never empty alt values
- Form inputs require associated label elements with matching for attributes
=== RULE_TRIGGERS for Jinja/Django Templates ===
- Template variables use double braces: {{ variable_name }}
- Template tags use block syntax: {% block content %}
- Never hardcode URLs — use url tag or url_for function
- Static files reference via static tag only
=== Component Integration Standards ===
- TARGET_DOMAINS: REPLACE_WITH_YOUR_TEMPLATE_DOMAINS
  # Example: "Django admin templates", "Jinja2 email templates"
- Import client components only from REPLACE_WITH_YOUR_COMPONENT_LIBRARY
  # Example: "@/components/ui/", "@/components/shared/"
- Never import from deprecated component paths
# ═══════════════════════════════════════════════════════════════════
# EXAMPLE 2: REACT COMPONENT RULE FILE
# Save as: .cursor/rules/react-components.mdc
# Targets: React component files matching *Component.tsx
# ═══════════════════════════════════════════════════════════════════
# FRONTMATTER:
---
rule_name: react-components
description: React and TypeScript component standards
path_globs:
  - "app/components/**/*Component.tsx"
  - "src/components/**/*Component.tsx"
  - "components/**/*Component.tsx"
active_status: true
priority: 20
---
RULE CONTENT SECTION:
REACT COMPONENT RULES
=== Export Standards ===
- Named exports only — never default exports
- Component name must match filename exactly
- Explicit JSX.Element return type on all function components
=== Styling Standards ===
- Tailwind utility classes only — no inline styles
- No CSS-in-JS libraries (styled-components, emotion)
- Class names via cn() utility function when conditional
=== PATH_INCLUSIONS Scope ===
This rule activates ONLY on files matching the path_globs above.
It does NOT apply to: API routes, database files, config files, test files.
If you are editing a file outside these paths and this rule feels active,
check for an overlapping glob pattern in another .mdc file.

Personalization Notes:

• TARGET_DOMAINS — Replace with the specific template contexts your project uses, e.g. "Django admin templates", "Jinja2 transactional email templates", "Next.js App Router page templates".
• PATH_INCLUSIONS — Replace with the exact glob pattern for your template directory. If your project uses a non-standard template location, run find . -name "*.html" -not -path "*/node_modules/*" to discover all HTML file paths first.
• RULE_TRIGGERS — The rule trigger section defines what behaviors activate when the glob matches. Tailor these to your template engine — Django rules differ from Jinja2 rules despite both using .html extensions.

📊 The Operational Returns: Evaluating Rule System ROI

Managing complex workspaces requires evaluating setup efficiency against monthly billing limits. The initial .mdc migration takes 2–3 hours across a typical production codebase. The ongoing return is measurable immediately: 40% token reduction on completion calls, 77% reduction on irrelevant context load, and a baseline improvement in output accuracy because the model receives fewer contradictory instructions.

Segmenting configuration layers scales developer velocity at a 300% ROI in engineering output when measured against the time previously spent correcting hallucinations caused by cross-contaminated global rule contexts.

For the complete pricing breakdown and plan limits, check our full Cursor review in the SRG Software Directory.

Cursor

3.7 (10 reviews)

Free From $20/mo

Best For: The most capable AI code editor for freelance devs billing complex projects — but the credit system will blindside you if you're not watching.

Read Full Review

🗓️ The 30-Day Execution Plan

Days 1–3: Global Migration and Setup

• Remove legacy .cursorrules files from your project root directory — delete, not rename.
• Create the system-level .cursor/rules/ configuration folder: mkdir -p .cursor/rules/.
• Scaffold the four core trigger settings using the frontmatter JSON schema from Scenario 1 as your template for each file.

Metric to Hit: Verify that active directory memory overhead remains low on project initialization — confirm the Cursor context indicator shows zero active rules on non-matched file types.

Days 4–7: Concise Formatting Configurations

• Build target concise rules using the concise-architect.mdc template from Scenario 2.
• Configure negative formatting parameters to force direct code modifications across all file types.
• Test that raw completions run without redundant conversational intros by running 10 standard refactoring prompts and reviewing the output for banned opener phrases.

Metric to Hit: Save up to 50% on monthly model token allocation during daily programming by eliminating explanatory prose overhead from completion responses.

Days 8–14: Agent Security Hardening

• Create security boundary rule files using the security-boundaries.mdc template from Scenario 3.
• Configure manual confirmations for all terminal actions inside the rule’s TERMINAL_ROUTER directive.
• Verify environment files are safely protected by running the deliberate test: prompt Composer to read your .env file and confirm the security rule refuses the request.

Metric to Hit: Confirm absolute isolation of private environment variables — the security rule test must return a refusal response, not file contents, on every test prompt.

100% Free Freelance & Productivity

Freelance Hourly Rate Calculator

Most freelancers guess their rate. This free calculator helps you set yours with precision — built around your actual monthly expenses, desired profit, and billable hours so you never undercharge again.

Launch Tool

Days 15–21: Path-Specific Glob Filters

• Create folder-specific rule files for component layouts and database schemas using the glob patterns from Scenario 4.
• Map frontmatter globs to load styling rules only inside matched client directories — verify with the Cursor context indicator.
• Confirm that database migration files do not trigger component styling rules by opening a .prisma file and checking which rules are active.

Metric to Hit: Context loads stay under 500 tokens per completion call on non-component file types — no compiler conflicts on active folders.

Days 22–30: Scaling and Standards Rollout

• Export verified .mdc file configurations across your development team’s active repositories by committing the .cursor/rules/ directory to version control.
• Standardize code style parameters inside workspace rules to maintain syntax consistency across all team members’ sessions.
• Monitor execution latencies to prevent parsing lag on large workspaces — confirm that no single .mdc file exceeds 200 lines of instruction content.

Metric to Hit: Establish a highly secure, automated coding environment for your entire team — every developer in the repository operates from the same path-restricted rule architecture with zero configuration divergence.

By Day 30, your workspace runs on highly optimized, path-restricted .mdc rule configurations that segment context precisely, protect credentials automatically, and enforce output standards consistently.

❓ Frequently Asked Questions

The Verdict: Secure Context, Speed Up Code Generation

Developer velocity inside AI-native editors correlates directly with context precision. A global rule file that loads 1,800 tokens of irrelevant framework instructions on every database migration prompt is not a configuration — it is a tax on every completion call.

The .mdc system eliminates that tax by design. Path-restricted rules mean the model receives exactly the instructions relevant to the file it is editing, and nothing else. For the complete runtime setup that the .mdc architecture integrates with, the how to use cursor ai guide covers the full directory structure, telemetry controls, and agent privileges that make path-restricted rules maximally effective.

While you optimize your cursor rules mdc template stack, don’t leave opportunities on the table. Head to the SRG Job Board at /jobs/ for high-paying remote roles looking for elite AI-powered developers. Browse the SRG Software Directory at /software/ for our complete list of developer automation platforms.

Take Smart Remote Gigs With You

Official App & Community

Get daily remote job alerts, exclusive AI tool reviews, and premium freelance templates delivered straight to your phone. Join our growing community of modern digital nomads.

Download Android App Join Telegram Channel

Quick Links: Software Directory • Free Templates • Remote Jobs