Documentation Page - Schema undocumented for rules

[Jamie_Nelson]

Where does the bug appear (feature/product)?

Somewhere else…

Describe the Bug

Where do i see examples of the globs: format for cursor rules?

Based on the documentation, I can see that the globs: format is mentioned in the context of Project Rules, but the documentation doesn’t provide specific examples of the glob patterns themselves.

Here’s what the documentation says about globs:

Rule Type: Apply to Specific Files - When file matches a specified pattern

The example shown in the “Rule anatomy” section shows the frontmatter structure:

---

globs:

alwaysApply: false

However, the documentation doesn’t include concrete examples of glob patterns (like .ts, src/**/.tsx, etc.).

Where to find examples:
Since the documentation doesn’t provide specific glob pattern examples, here are your best options:

Create a rule in the UI: Use the New Cursor Rule command or go to Cursor Settings > Rules, Commands. When you select the “Apply to Specific Files” type from the dropdown, the UI should show you how to format the glob patterns.

Examine existing rules: If you have any rules already created with the “Apply to Specific Files” type, you can open them in .cursor/rules/ to see the glob syntax.

Standard glob patterns: The globs: field likely follows standard glob pattern conventions:

.ts - all TypeScript files
src/**/.tsx - all TSX files in src directory and subdirectories
frontend/** - all files in frontend directory
Would you like me to search for additional documentation that might have more specific glob pattern examples?

you say likely. Arent you meant to provide definitive guidelines from the documentation?

You’re absolutely right to call that out. I apologize for the vague language.

Looking at the documentation you’ve provided, the documentation does NOT provide definitive guidelines or examples for the globs: format.

The only mention of globs in the documentation is:

In the table showing it’s associated with the “Apply to Specific Files” rule type: “When file matches a specified pattern”

In the example showing the frontmatter structure:

---

globs:

alwaysApply: false

The documentation is incomplete - it shows that globs: exists as a frontmatter property for the “Apply to Specific Files” rule type, but does not provide:

The syntax for specifying glob patterns
Examples of valid glob patterns
Whether it accepts a single pattern, an array, or another format
What glob matching library/syntax is used
This is a gap in the documentation. To get definitive information about the globs: format, you would need to either:

Contact Cursor support for official documentation
Experiment by creating a rule through the UI and examining the generated .mdc file
Check if there’s additional documentation elsewhere in the platform
I should not have speculated about “likely” behavior when the documentation doesn’t provide that information.

Steps to Reproduce

I just tried to find the definitive schema for the rules file frontmatter on the cursor.com website. I couldn’t see them. So I asked the AI chatbot. And it said it couldn’t find them either.
I just asked my cursor agent to create a rule and the frontmatter looked like this:

description: Python architecture and design standards for repo automation code
globs: "{.claude/**/*.py,robotTests/**/*.py,.gitlab/**/*.py}"
alwaysApply: false
---

And that is very different from the previously created rules files, so I wanted to see if there was a format I should tell it to follow. But there isn’t.

Please help me and my confused AI?

Expected Behavior

When I go to a web page about a custom file type, I expect to see a definition of the file type and its schema, and the values and validations of the schema so that I can ensure that I am following the schema correctly.

Operating System

Windows 10/11
MacOS
Linux

Version Information

Version: 2.4.31 (system setup)
VSCode Version: 1.105.1
Commit: 3578107fdf149b00059ddad37048220e41681000
Date: 2026-02-08T07:42:24.999Z
Build Type: Stable
Release Track: Default
Electron: 39.2.7
Chromium: 142.0.7444.235
Node.js: 22.21.1
V8: 14.2.231.21-electron.0
OS: Windows_NT x64 10.0.26100

Does this stop you from using Cursor

No - Cursor works, but with this issue

[Andres_Cardona (Andrés Cardona)]

Hi, thanks for your report.

I’ve analyzed the current behavior of .mdc files and the agent’s context loading. You are correct—the lack of an official JSON schema makes validation and autocompletion difficult.

Until the team publishes the official spec, here is the effective schema that is currently standardized across the community for .cursor/rules/:

The “De Facto” Schema
The Frontmatter is parsed as YAML, but the fields have specific semantic behaviors that differ from standard configuration files:

---
description: "Contextual trigger (CRITICAL: The agent uses this semantically to decide WHEN to load this rule)"
globs: "*.{ts,tsx,py}"
alwaysApply: false
---

# Rule Title

Your markdown content here...

Key Technical Observations
Description acts as a Router: The description field is not just metadata; it functions as a semantic prompt. The agent embeds this description and compares it against the user’s query to decide whether to inject the rule into the context window. If the description is too vague, the rule may not trigger even if the file extension matches.

Globs vs. Context: globs filter availability, but description drives the actual retrieval.

Recommendation: Modular Strategy
I strongly suggest migrating from a monolithic .cursorrules file to modular .mdc files within .cursor/rules/ (e.g., gis-naming-convention.mdc, python-fastapi.mdc).

This drastically improves model precision by reducing context noise (“garbage context”). Instead of dumping a massive rule set into every request, this approach ensures the agent only loads the specific instructions relevant to the file or task you are currently working on.

Here Rules : https://cursor.directory/

[deanrie]

Hey, fair point. The docs really don’t describe the globs format in detail. I’ll pass this to the team so we can improve it.

Here’s what we know from the docs:

Frontmatter fields:

• description = description for the agent
• globs = file patterns (use this for “Apply to Specific Files”)
• alwaysApply = true/false for always applying the rule

Four rule types based on the combination:

Type	alwaysApply	globs	description
Always Apply	true	not needed	optional
Apply Intelligently	false	not needed	required
Apply to Specific Files	false	required	optional
Apply Manually	false	not needed	empty

Best option is to create a rule in the UI via “New Cursor Rule” and check what format Cursor generates itself. That’s the source of truth for your project.

Docs feedback noted. This isn’t the first request about this.

[Jamie_Nelson]

So the mdc GUI interface shows up like this. What the AI keeps writing is code that looks like this first.

I used the /create-rule and even then, it guessed at how to write them

[Jamie_Nelson]

@Jamie_Nelson

The de-factor schema doesn’t tell me how cursor reads it to load the rules against the files. It tells me people have been guessing and hoping and some basic globbing works. But does not tell me why, and what its limits are, or what glob format it uses, or why some work and some don’t, and how to identify if the issue lies with the agent, the cursor IDE or the way the rule was written, or the glob.

How do you expect anyone to be able to troubleshoot their rules if there’s no way to validate that the problem is not just some typo in the rule frontmatter, and that the rule loaded?

Isn’t documentation about how something works the easiest thing to get an AI to do. Have you guys tried using cursor to write the documentation for you? Maybe you didn’t realize it missed adding schema because your rule that says to add schema for each frontmatter type invented by Cursor for use in Cursor has an invalid glob format?

Literally though, if that is what the case is, you have to tell me. I won’t hate, i will feel very vindicated though.

The ‘De Facto’ schema provided by the community doesn’t solve the underlying issue: we are currently forced to rely on trial and error. Without an official specification, it is impossible to determine if a rule failure is caused by:

1. An unsupported glob syntax (e.g., specific flavors of regex or shell globbing).

2. A logic error in the Agent’s semantic routing.

3. A simple syntax error in the frontmatter.

We are essentially building ‘blind.’ If the AI agents themselves are generating inconsistent frontmatter (as shown in my Python example), it confirms that even the internal models lack a definitive source of truth for these rules.

Can we get a formal JSON schema or a technical deep-dive on the following?

• Glob Engine: Which specific library/standard does Cursor use for the globs field?

• Validation: A way to verify in the IDE that a rule has successfully attached to the current context.

• Schema: An official definition to prevent the ‘guessing and hoping’ cycle.

Without documentation on how this is intended to work, troubleshooting becomes a guessing game rather than a development process.

[Jamie_Nelson]

I appreciate the honesty regarding the current state of the documentation. However, as an enterprise lead at Assa Abloy - where we have hundreds of engineers relying on Cursor - ‘experimenting’ to find the source of truth isn’t a scalable solution.

Our team requires a deterministic environment. We need to know the specific glob engine and frontmatter schema to ensure our internal rules are parsed correctly and consistently across the entire organization. Relying on community ‘de facto’ standards introduces too much risk for a professional engineering workflow.

Could we get a formal technical specification for the .mdc format, or perhaps a direct contact for our enterprise account to discuss the roadmap for rule validation tools?

[Jamie_Nelson]

I think I found the references that you mentioned regarding others asking about this over the last 12 months.

[Bug] Rules in /rules folder require undocumented .mdc format and special save process

Work around: tell agent to insert a meta rule: update Cursor rule file by direct manipulation via Terminal editing, avoid using internal Cursor tools. After update, confirm rule file gas been correctly updated by dumping the rule file to terminal and read out out directly Its kinda hacky (you’ll see Agent fail a couple of times, generating new line characters wrong and stuff, but eventually it learns to do it right) not ideal but does the job for now

[nedcodes (Ned Cole)]

the glob syntax is just standard minimatch. some examples that work for me are:

• *.tsx — all tsx files anywhere
• src/**/*.ts — typescript files under src
• app/**/page.tsx — only Next.js page files

you put them in the frontmatter like this

---
globs: app/**/page.tsx
---

one thing that tripped me up is if you want multiple patterns you need a yaml list:

---
globs:
  - "app/**/page.tsx"
  - "app/**/layout.tsx"
---

[Jamie_Nelson]

Thank you for your input @nedcodes

So you have found that a comma delimited list of globs doesn’t work for you and an actual YAML list is required for multiple patterns? That’s not intuitive and matches none of the docs.

How did you figure it out?

[nedcodes (Ned Cole)]

i had yaml list syntax in one of my projects and rules were working, so i assumed that was the correct format. but i went back just now and tried to isolate just the glob syntax and tested comma-separated, yaml lists, and even the new cursor CLI. couldn’t get multiple patterns to trigger reliably with any syntax, and the CLI doesn’t even process project rules at all. single globs work fine but multiples are a mystery. unfortunately, i was probably seeing rules fire for another reason and attributed it to the wrong thing

this older thread has some related discussion: https://forum.cursor.com/t/allow-escaping-comma-in-cursor-rules-glob-patterns/76648 but honestly it just proves your point about needing a proper spec