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
4 Likes