Feature Request: Explicit Separation Between AI Rules and Cursor Tool Instructions

Ideas Feature Requests
,
1

Feature request for product/service

Cursor IDE

Describe the request

Feature Request: Explicit Separation Between AI Rules and Cursor Tool Instructions

Motivation

While working on a large, architecture-heavy, long-running project with Cursor, I encountered systematic confusion caused by the current naming and enforcement model of rule-related files.

The issue is not missing functionality, but a mismatch between file names,
implied responsibility, and actual enforcement behavior.

This makes it unnecessarily hard to build reliable, deterministic workflows
around Cursor and its AI integration.

Core Problem

1. .cursorrules behaves like AI law, but is named like tool configuration

In practice, .cursorrules functions as:

  • a rule set injected into every AI prompt
  • a hard behavioral constraint system for the model
  • effectively, a “law book” for the AI

However, the name .cursorrules strongly suggests:

  • rules for Cursor itself
  • editor or tool configuration
  • non-AI-specific behavior

This naming is misleading.

If a file defines mandatory and persistent constraints on model behavior,
its name should reflect that responsibility explicitly (e.g. AI rules,
model rules, or similar).

2. cursor-instructions.md sounds tool-enforced, but is not

The name cursor-instructions.md strongly implies:

“These are instructions that Cursor itself will follow deterministically.”

In practice, this file appears to be treated as:

  • optional or best-effort AI context
  • advisory guidance for the model
  • not reliably or deterministically enforced by Cursor

This creates a critical ambiguity:

  • users expect tool-level enforcement
  • they receive probabilistic model behavior instead

Concrete Use Case That Is Currently Not Possible

I would like to use cursor-instructions.md as actual instructions for Cursor itself, not for the AI model.

Example requirement:

If the user writes:

MODE: CODE_AUDIT

Then Cursor MUST:

  • include ai_rules_core.md
  • include ai_rules_audit.md
  • inject both files into the model context before sending the prompt

In other words:

  • cursor-instructions.md should define how Cursor orchestrates context
  • not just provide additional text that the AI may or may not follow

At the moment, this distinction is unclear and cannot be relied upon.

Why This Matters

For small or casual usage, this ambiguity may be tolerable.

For serious system design, architecture work, and long-lived projects, it is not.

Users need a clear and enforced distinction between:

  • tool-enforced behavior (Cursor)
  • model-enforced behavior (AI rules)
  • human-readable guidance and documentation

When naming and enforcement diverge:

  • mental models break
  • trust in the tooling erodes
  • users are forced into experimentation instead of configuration

Proposed Improvements

A1. Make responsibilities explicit through naming

Suggested separation:

  • Mandatory AI behavior (always injected into prompts)

    • currently: .cursorrules
    • suggested: ai-rules.md, model-rules.md, or similar

  • Cursor tool orchestration logic

    • currently: cursor-instructions.md
    • suggested: keep the name, but make it truly tool-enforced

  • Human documentation and examples

    • stored explicitly under /docs

A2. Make the separation explicit in the UI (optional but ideal)

Even with improved file naming, users still have to discover and infer
what gets injected into the model context versus what Cursor enforces deterministically.

A more robust solution would be to expose these responsibilities as first-class, named UI surfaces (e.g. in Settings or a Project Configuration panel), instead of only representing them as loosely interpreted files.

For example, Cursor could provide dedicated editors (or “panes”) with explicit labels:

  • AI Rules

    • clearly marked as: always injected into every model call

    • treated as mandatory behavioral constraints for the model

    • In addition, the AI Rules UI should not be limited to a single global rule set. It should explicitly support managing multiple, user-defined/named AI rule profiles (e.g. core, audit, architecture, security), which can be:

      • individually created, edited, named, and stored
      • selectively enabled or combined
      • deterministically included by Cursor based on orchestration logic
        (for example via cursor-instructions.md or explicit mode switches)

      This makes AI behavior modular, composable, and predictable, instead of monolithic.

  • Cursor Instructions (Tool-Orchestrated)

    • clearly marked as: deterministically enforced by Cursor
    • defines how Cursor assembles context and which rule-sets are included under which conditions
    • enables reliable mode switches like MODE: CODE_AUDIT → include ai_rules_core.md + ai_rules_audit.md

  • Documentation / Reference

    • clearly marked as: human-readable project docs
    • not implicitly injected unless explicitly requested or referenced by tool-orchestration logic

This turns “AI rules vs. tool instructions” from an implied convention into a visible, discoverable contract. It reduces trial-and-error, prevents false expectations, and makes advanced workflows reliable even for non-expert users.

If .cursorrules remains the AI’s “law”, its name should reflect that.

If cursor-instructions.md exists, it should always be genuinely interpreted, followed and enforced by Cursor itself.

B. Enforce the promise implied by the name

If a file is called “instructions”:

  • Cursor should guarantee that they are applied deterministically
  • or the file should be renamed to avoid false expectations

At the moment, the name implies authority that the mechanism does not provide.

Summary

This request is not about adding new AI capabilities.

It is about:

  • semantic clarity
  • correct responsibility separation
  • deterministic workflows for advanced users

Clear naming and strict enforcement boundaries would significantly improve Cursor’s usability for architecture-heavy and long-running projects.

Thank you for considering this feature request.

Best Regards,
Ilker

3

I’m with you that the rule/instruction enforcement can be confusing and unreliable.

But I don’t fully understand how your issue (and proposed solution) relates to large, architecture-heavy projects being difficult to manage.

Perhaps what you’re looking for is something like this: GitHub - github/spec-kit: 💫 Toolkit to help you get started with Spec-Driven Development

There seem to be prompting and context-management strategies that get the agent to be more reliable at reading and following rules, double checking that they followed them, and even running commands to update their own context or fetch a set of md files.

4

Hi Oliver,

Thank you for your response!

In my introductory sentence, I was merely providing some context regarding my specific application environment. It wasn’t intended to imply that the request is strictly limited to large-scale architectures. These naming conventions are inherently imprecise and can lead to confusion for any user, regardless of project size.

Also, thanks a lot for the link to the tool! I’ve had a quick look, and it definitely seems to head in the right direction; I’ll be sure to explore it further.

That being said, it would be great if Cursor could provide this kind of functionality natively as a built-in feature in the near future.

Best regards

1 Like
5

this is a good distinction. I’ve been running into the same thing where I have rules that are clearly “tell the AI how to write code” mixed in with rules that are more like “configure how cursor the tool behaves.” splitting .cursorrules into behavioral vs structural would make a lot of sense. right now I just use comments to separate the sections but that’s obviously just for my own sanity, cursor doesn’t care about the comments.

6

Hi Ned,

the rule names are nonsensical and don’t deliver what they promise. Furthermore, a single file for model instructions isn’t enough when dealing with a large set of rules for different aspects. To prevent the AI from becoming inaccurate, the instruction files should stay compact. We need individual, smaller rule files that can be toggled on or off depending on the task, for example, audit rules for code, documentation standards, or specific project requirements with distinct sets of rules.

Regards

7

@Ilker_Savas good points. you might already know this but the newer project rules system actually does what you’re describing. instead of one big .cursorrules file, you create individual .mdc files under .cursor/rules/ and each one handles a specific concern.

for example you could have:

  • .cursor/rules/audit.mdc (code audit standards)
  • .cursor/rules/docs.mdc (documentation rules)
  • .cursor/rules/architecture.mdc (project structure)

each file has frontmatter that controls when it applies:

---
description: Code audit standards
globs: "**/*.ts"
alwaysApply: false
---
your rules here

alwaysApply: false with a glob means it only activates when you’re working on matching files. alwaysApply: true means it’s always injected. and if both are false/empty, the AI can pull it in based on the description when it thinks it’s relevant.

so the toggling you want is built in, just at the file/glob level rather than a UI toggle. the official docs cover this: Cursor Docs

the naming issue you raised is fair though. “project rules” vs “.cursorrules” vs “user rules” is confusing, and the docs could do a better job explaining which one does what.

1 Like
9

Hi Ned,

this is very good news. Thank you for the information, no I didn’t look that up.
But the confusion regarding the names remains.

It would also be cool if we can manage those files in GUI elements checkboxing them in and out as needed, but this is of course not strictly necessary.

The confusion regarding the name cursor-instructions.md remains. It should be a file that Cursor follows implicitly but strictly, rather than in an arbitrary manner.

10

glad it helped! re: the GUI toggle, there’s actually already a feature request for that: Temporarily disable all Cursor rules — a /rules disable command to turn them on/off per session. might be worth adding your vote there.

in the meantime, the closest thing to a toggle is the alwaysApply frontmatter field. if you set alwaysApply: false and don’t add a glob, the rule becomes “agent-decided” meaning cursor only pulls it in when it thinks the description is relevant. so you get some selective behavior without manually toggling. not the same as a real checkbox UI but it’s something.

the naming confusion is a real problem though. .cursorrules (legacy), .cursor/rules/*.mdc (project rules), user rules in settings, team rules on dashboard, and now AGENTS.md too. five different mechanisms for essentially the same concept. the docs page tries to cover all of them but it’s not great at explaining when to use which: Rules | Cursor Docs

1 Like
11

yes that is the BIG problem with the filenames in Cursor
they do not fulfill what their names promise

interestingly it is one of the core principles of what I try to achieve in my project: self describing function names that promise exactly what they do :slight_smile:

thanks for your input

1 Like