Subdirectory-Specific .cursorrules Support

Feature Requests
1

Description:
Enable multiple .cursorrules files at different directory levels, allowing context-specific AI configurations within projects.

Similar Patterns:
Follows established per-directory config patterns like .gitignore and .eslintrc.

Benefits:

  • Different rules for frontend/backend code, per module, or even per subdir.
  • Team-specific configurations in monorepos
  • Better organization of prompts and rules

–

Why This Matters:
Context management is the core challenge when working with AI coding assistants. The .cursorrules file is a critical part of this context management, but currently limited by its project-wide scope.

Real-World Scenarios:

  1. Monorepos:

    • Frontend team needs React-specific guidelines
    • Backend team needs different security/architecture rules
    • Shared modules need their own conventions

  2. Multi-Technology Projects:

    • Different frameworks require different best practices
    • Package-specific dependencies need targeted documentation
    • Architecture boundaries require specific patterns

Current Issues:

  • Project-wide rules often contain irrelevant or conflicting information
  • Multi-module projects struggle with context separation
  • Large monorepos need different rules for different areas

Current Workarounds:
Developers struggle with context management in different ways:

  • Creating scattered .md files and manually including them in chat/composer sessions
  • Adding file references in global .cursorrules, hoping the composer agent will read them (unreliable and only works in agent mode, not in chat or cmd+K)
  • Repeatedly pasting context in conversations

–

Technical Implementation:

  1. Chat/Compose Sessions:
project/
  .cursorrules                    # global: "Be concise, focus on TypeScript best practices"
  frontend/
    .cursorrules                 # frontend: "Use React patterns, follow Material-UI guidelines"
    components/
      Button.tsx               # inherits frontend + global rules
  backend/
    .cursorrules               # backend: "Follow NestJS patterns, focus on security"
    services/
      auth.ts                 # inherits backend + global rules

When a session includes multiple files, the AI needs to:

  • Identify applicable .cursorrules for each file based on path
  • Apply relevant rules when discussing/modifying specific files
  • Merge rules with closest ones taking precedence
  1. Cmd+K Quick Actions:
  • Scan upward from current file location
  • Apply merged rules based on directory hierarchy

Key Challenge:
Proper prompt engineering to make the AI understand rule context-switching when dealing with multiple files in the same session.

–

V1 Simple Implementation:
Starting with “first-file-stops” rule provides immediate value while keeping implementation simple:

  • Clear, predictable behavior
  • No complex merging logic
  • Matches how developers mentally segment their projects

This foundation can later expand to support more sophisticated features like merging and cross-references.

–

Future Enhancements - Advanced Rule Control

After implementing the basic directory-specific rules with “first-file-stops” behavior, we can imagine adding powerful control mechanisms through what may be called “Cursor Specific Instructions”. These are special directives that control how Cursor itself handles .cursorrules files, as opposed to instructions meant for the AI model. They are meta-instructions that affect rule processing behavior. They would help prevent overwhelming the AI model with irrelevant context while ensuring it gets precisely targeted instructions.

  1. Stop Directive:
[CURSOR_INSTRUCTION_STOP]
# Prevents climbing up directory tree

Critical for:

  • Independent modules in monorepos
  • Preventing rule pollution from parent directories
  • Clear context boundaries
  1. Import Directive:
[CURSOR_INSTRUCTION_IMPORT(../shared/archi-rules)]
# Imports rules from specific paths

Enables:

  • Rule reuse across similar modules
  • Shared base rules with specific overrides
  • Complex rule composition without hierarchy limitations

These directives would provide fine-grained control over rule inheritance, especially valuable in:

  • Microservices architectures
  • Feature-based project organization
  • Cross-module shared conventions
10 Likes
2

This is very much a needed feature. We all sort of fake it with extensive .md file breadcrumbs and in-document jsdoc (or pick your codebase) but it would sure be nice if Cursor could pick up on rules every time it enters a subdirectory.

1 Like
3

Our new project rules feature in 0.45.x should help with this, hoping to add a detailed writeup to our documentation this week!

1 Like
4

is anyone tracking .cursorrules best practices, or even some examples that people have seen success with?

1 Like
5

I really appreciate the addition of this feature in version 0.45.x! I imagine many users would be thrilled to make use of it.

However, unfortunately, I couldn’t find detailed documentation explaining how to use it. The only reference I came across was in the changelog:

.cursor/rules: Users can write several repository-level rules to disk in the .cursor/rules directory. The Agent will automatically choose which rule to follow.

Could you kindly provide more details on how the agent determines which rule to follow, along with some practical examples?

6

Where is the documentation?

7

I’ve started experimenting with this feature, and while the initial results show potential, they remain somewhat unclear.

There’s still significant ambiguity around how the agent selects the correct file. Understanding this mechanism is essential to use the feature effectively. My assumption is that the agent might choose files based on their names, through semantic search, or perhaps via pre-generated summaries of the files.

To test, I moved my old .cursorrules file into .cursor/rules and renamed it COMMON_RULES.md. This file referenced other documentation files, which I also moved into .cursor/rules. When I asked the chat some questions, it only seemed to recognize the files explicitly referenced in COMMON_RULES.md, ignoring the others in the .cursor/rules directory. Under these conditions, the agent performed better and seemed more consistent.

However, after restarting, neither the agent nor the chat seemed able to access any files in .cursor/rules. It looked as if the directory had become completely invisible to them. Could you provide more clarity on how the agent processes and utilizes files in .cursor/rules? A better understanding of this behavior would help users leverage this feature to its full potential.

2 Likes
8

docs.cursor.com although there’s a big revamp coming soon hopefully

9

The AI picks which rules to use based on your description, so I’d swap the description to be more like a instruction for when to follow those rules

We’ll have better docs on this soon to help you get going better!

10

I meant on this feature. It would be great to get tips directly from the team on the first class basis in the documentation rather than via Twitter threads: x.com

In the link above, Michael Fedlstein, who’s apparently on the Cursor team, provides some useful context and practical ways to use the new feature

11
1 Like
12

This is much needed feature for larger teams. At my workspace we have 40+ teams working on the same repo and keeping all the rules from various team in a single folder is going to be really crowded.
At the very least we should add support for nested directories in the rules directory if the original feature request is not possible due to technical reasons including performance.

13

The newest versions use cursor/rules and each rule can have specific globs referenced for when that rule should be utilized. I am not clear if it always notifies you when a rule is referenced but theoretically this replaces the original posters suggestion.

14

Yes, I am now using the new feature introduced in the latest versions.

Originally, my feature request for hierarchical rules was meant to provide better control over which rules the agent selects, based on the referenced files.

The new approach with transversal rules is indeed a better solution in many ways, as it allows rules to be defined independently of the project structure and linked to specific folders when needed.

However, this has introduced an odd behavior. I’m not sure if I’m the only one experiencing this, but the agent doesn’t always pick up the rules it should. I often have to explicitly remind it which rules to use. One of the main objectives of my original request was to ensure that the agent reliably applies the appropriate rules, but this isn’t always happening in the current implementation.

While the new rule system is a great improvement, I believe the Cursor team should refine it further to ensure the agent systematically checks for and applies the relevant rules for every task, without requiring manual intervention.

15

Yeah this seems to have been my experience as well

16

I can confirm what @melbarra just said. If I prompt it in a sub-package that does not have any rules attached the agent will still use rules from other projects. Afterwards I tell the agent is should not have used those rules for this directory and it corrects itself. So it has the capability to do the right thing, it just chooses not to.

If I initially prompt with “Use only the rules that apply to this file” then it does do what I expect it to.

17

It turns out that there is an @cursor rules mention to select and reference the rules to follow, but this actually makes the feature lose much of its value.

The primary objective of this feature should be to ensure that users rarely, if ever, need to manually specify which rules to apply. The agent should be capable of autonomously selecting the appropriate rules based on the context. It looks like the Cursor team simply needs to instruct or program the agent to do this systematically.

Right now, the need for manual intervention significantly undermines what should be an automated process. If the agent consistently selected the relevant rules on its own, this feature would truly reach its full potential.

2 Likes