Project Rules: Documented RULE.md folder format not working, only undocumented .mdc format works

Travis_Polland · December 11, 2025, 9:22am

Where does the bug appear (feature/product)?

Cursor IDE

Describe the Bug

Project Rules using the documented folder-based RULE.md format are not recognised by Cursor. The documentation at https://cursor.com/docs/context/rules shows rules should be created as folders containing a RULE.md file (e.g., .cursor/rules/my-rule/RULE.md), but this format does not work. Rules only appear in Settings when using flat .mdc files directly in .cursor/rules/ (e.g., .cursor/rules/my-rule.mdc).

Steps to Reproduce

Create .cursor/rules/test-rule/RULE.md with frontmatter (description, globs, alwaysApply)
Open Cursor Settings → Rules → Project Rules
Observe: No rules appear
Convert to .cursor/rules/test-rule.mdc (flat file, same content)
Observe: Rule now appears in Project Rules

Expected Behavior

Rules created using the documented folder-based format (.cursor/rules//RULE.md) should appear in Settings → Rules → Project Rules, matching the documentation at Rules | Cursor Docs

Operating System

MacOS

Current Cursor Version (Menu → About Cursor → Copy)

Version: 2.2.14
VSCode Version: 1.105.1
Commit: 1685afce45886aa5579025ac7e077fc3d4369c50
Date: 2025-12-11T01:12:35.790Z (8 hrs ago)
Electron: 37.7.0
Chromium: 138.0.7204.251
Node.js: 22.20.0
V8: 13.8.258.32-electron.0
OS: Darwin arm64 25.1.0

For AI issues: which model did you use?

N/A

For AI issues: add Request ID with privacy disabled

N/A

Additional Information

Verified .cursor/rules/ is not in .gitignore or .cursorignore
Verified .cursor/ is not excluded in .vscode/settings.json files.exclude
Files are tracked by Git
The .mdc format works but is not documented; the documented RULE.md format does not work
This caused significant debugging time before discovering the undocumented .mdc requirement

Does this stop you from using Cursor

No - Cursor works, but with this issue

deanrie · December 11, 2025, 11:30am

Hey, thanks for the report.

Right now, per the docs, Project Rules should be folders with a RULE.md file (see Rules | Cursor Docs). .mdc is considered legacy but still works, so it’s a good temporary workaround.

Let’s collect details for the bug:

Please show:
- the exact path and tree: .cursor/rules/<rule>/RULE.md
- the RULE.md frontmatter (description, globs, alwaysApply)
- a screenshot of Settings > Rules > Project Rules
- whether the rules were created via Settings > Rules > + Add Rule or manually
- a minimal repro (an archive or a test repo)
Please try:
- creating a rule via Settings > Rules > + Add Rule and check if it appears
- restarting or using Reload Window

Please let us know if the + Add Rule option helped.

Cody_Herriges · December 13, 2025, 12:14am

I can confirm. The new RULES.md format is not detected by Cursor 2.2.20 on macOS. The “Add Rule” button in the settings Cursor Settings UI still creates .mdc files.

TheDarkMist · December 14, 2025, 6:04pm

I also confirm this. The documented format is not working!

Travis_Polland · December 15, 2025, 11:45pm

Hi,

I can now confirm, after a recent update, the following:

Project A

Project Rules:
- Only AGENT.MD files are listed
- One MDC file is listed
- Add Rule created a MDC file (not a folder + RULE.MD)

Project B

Project Rules:
- List of the rules folders
- Click on a rule to open RULE.MD file
- Add rules creates a folder named after the rule and a RULE.MD file

oryband · December 16, 2025, 1:00pm

Confirmed on Mac.

KGF · December 17, 2025, 1:15pm

Where does the bug appear (feature/product)?

Cursor IDE

I’m running it on Window 11 and opening a project in WSL2 running Ubuntu.

Describe the Bug

I have cursor rules in the seemingly correct location and the rules are not loaded or show in the settings.

Steps to Reproduce

Create rules, check the rules section in the settings

Expected Behavior

The rules to appear there

Operating System

Windows 10/11

Current Cursor Version (Menu → About Cursor → Copy)

Version: 2.2.20 (user setup)
VSCode Version: 1.105.1
Commit: b3573281c4775bfc6bba466bf6563d3d498d1070
Date: 2025-12-12T06:29:26.017Z
Electron: 37.7.0
Chromium: 138.0.7204.251
Node.js: 22.20.0
V8: 13.8.258.32-electron.0
OS: Windows_NT x64 10.0.26100

Does this stop you from using Cursor

No - Cursor works, but with this issue

b-schmeling · December 19, 2025, 9:37pm

Also hitting this issue. Rules that are created under .cursor/rules/<rule>/RULE.md are not applied and new rules are created at .cursor/rules/<new_rule>.mdc when using the + Add Rule option

Version: 2.2.43 (Universal)
VSCode Version: 1.105.1
Commit: 32cfbe848b35d9eb320980195985450f244b3030
Date: 2025-12-19T06:06:44.644Z
Electron: 37.7.0
Chromium: 138.0.7204.251
Node.js: 22.20.0
V8: 13.8.258.32-electron.0
OS: Darwin arm64 25.2.0

Travis_Polland · December 23, 2025, 11:04am

Confirmed. The issue still is persistant:

Version: 2.2.43
VSCode Version: 1.105.1
Commit: 32cfbe848b35d9eb320980195985450f244b3030
Date: 2025-12-19T06:06:44.644Z
Electron: 37.7.0
Chromium: 138.0.7204.251
Node.js: 22.20.0
V8: 13.8.258.32-electron.0
OS: Darwin arm64 25.2.0

dataneek · December 27, 2025, 5:09pm

Confirmed. This is still an issue.

Version: 2.2.44 (Universal)
VSCode Version: 1.105.1
Commit: 20adc1003928b0f1b99305dbaf845656ff81f5d0
Date: 2025-12-24T21:41:47.598Z
Electron: 37.7.0
Chromium: 138.0.7204.251
Node.js: 22.20.0
V8: 13.8.258.32-electron.0
OS: Darwin arm64 24.6.0

user1624 · December 29, 2025, 11:12am

Where does the bug appear (feature/product)?

Cursor IDE

Describe the Bug

Project Rules with `RULE.md` folder format not working - Documentation issue or bug?

Summary

Project Rules using the folder-based RULE.md format (.cursor/rules/<folder>/RULE.md) are not recognized in Cursor 2.3.10, despite being documented as the recommended format since version 2.2.

Environment

Cursor Version:

Version: 2.3.10
VSCode Version: 1.105.1
Commit: af6d64e4848e6185e482a2de5bac040191c8d790
Date: 2025-12-29T03:56:22.219Z
Electron: 37.7.0
Chromium: 138.0.7204.251
Node.js: 22.20.0
V8: 13.8.258.32-electron.0

OS:

ProductName:            macOS
ProductVersion:         26.2
BuildVersion:           25C56
---
Darwin XIAOYUUYANG-MC0 25.2.0 Darwin Kernel Version 25.2.0: Tue Nov 18 21:09:45 PST 2025; root:xnu-12377.61.12~1/RELEASE_ARM64_T6030 arm64

Description

According to the official documentation, Project Rules should use the folder-based RULE.md format:

.cursor/rules/
  my-rule/
    RULE.md

The documentation states:

“Each rule corresponds to a folder containing a RULE.md file”

“Since version 2.2, .mdc rules are still available, but all new rules are created as folders in .cursor/rules”

However, my rule with this exact structure does not appear in Settings > Rules and is not applied to chat sessions(maybe).

My RULE.md

---
description: "HarmonyOS ArkTS 开发规范，包含组件库使用、UI开发范式、代码规范、工作流程和最佳实践"
globs: ["**/*.ets"]
alwaysApply: true
---
xxxxx
...

Question

Is the documentation outdated, or is this a bug in Cursor 2.3.10?

Workaround

Using RULES.mdc in the rules root works correctly.

Steps to Reproduce

see video
OR

Create folder structure in project root:
```
mkdir -p .cursor/rules/my-rule
```
Create RULE.md file with valid frontmatter:
```
touch .cursor/rules/my-rule/RULE.md
```

Add the following content to RULE.md:

---
description: "Test rule description"
globs: ["**/*.ts"]
alwaysApply: true
---

# Test Rule
This is a test instruction.

Restart Cursor completely (Cmd+Q, then reopen)
Open Cursor Settings → Rules
Expected: Rule “my-rule” should appear in Project Rules list
Actual: Rule does not appear, and is not applied to chat sessions

Expected Behavior

RULE.md work

Screenshots / Screen Recordings

Operating System

MacOS

Current Cursor Version (Menu → About Cursor → Copy)

Version: 2.3.10
VSCode Version: 1.105.1
Commit: af6d64e4848e6185e482a2de5bac040191c8d790
Date: 2025-12-29T03:56:22.219Z
Electron: 37.7.0
Chromium: 138.0.7204.251
Node.js: 22.20.0
V8: 13.8.258.32-electron.0
OS: Darwin arm64 25.2.0

Does this stop you from using Cursor

No - Cursor works, but with this issue

raythurnvoid · January 3, 2026, 10:38pm

Version: 2.3.21 (system setup)
VSCode Version: 1.105.1
Commit: 68e0a0385b87408d050869ea543e3778ad53f780
Date: 2026-01-02T23:46:13.381Z
Electron: 37.7.0
Chromium: 138.0.7204.251
Node.js: 22.20.0
V8: 13.8.258.32-electron.0
OS: Windows_NT x64 10.0.26200

I have the same issue

Travis_Polland · January 7, 2026, 10:05pm

I can reconfirm that no “fix” has been included in the most recent production release yet. I’ve tested the “create rule” and manually added the rules, and neither works. I can confirm that the MDC format does continue to work for the time being.

Keep us posted on the progress.

Yolo_Tan · January 8, 2026, 3:27pm

Same here

Robert_Zdanowski · January 10, 2026, 9:02pm

The same issue discovered today when I tried to migrate my “phasing out” mdc rules into new “correct” structure according to the docs
I even thought that it’s 2.3 bug so downgraded to 2.2 and guess what

shotag · January 12, 2026, 9:49am

same problem here

Version: 2.3.34 (system setup)
VSCode Version: 1.105.1
Commit: 643ba67cd252e2888e296dd0cf34a0c5d7625b90
Date: 2026-01-10T21:17:10.428Z
Electron: 37.7.0
Chromium: 138.0.7204.251
Node.js: 22.20.0
V8: 13.8.258.32-electron.0
OS: Windows_NT x64 10.0.26200

ross_monge · January 13, 2026, 9:20pm

Same issue, tried updating to nightly, no dice..

Version: 2.4.0-pre.29.patch.0 (user setup)
VSCode Version: 1.105.1
Commit: 31ba4eea39481b2e13065083d98cf92613175e00
Date: 2026-01-13T20:27:33.722Z
Build Type: Stable
Release Track: Nightly
Electron: 37.7.0
Chromium: 138.0.7204.251
Node.js: 22.20.0
V8: 13.8.258.32-electron.0
OS: Windows_NT x64 10.0.19045

Topic		Replies	Views
Cursor 2.3.23 Not Recognizing Folder-Based Project Rules Bug Reports	3	134	January 13, 2026
New Cursor Rules directory format not working Bug Reports	8	268	January 15, 2026
New project rules create .mdc instead of RULE.md Bug Reports	6	191	January 12, 2026
Project Rules no longer apply in version 1.0.0 Bug Reports	22	919	July 7, 2025
Rules are not loaded Bug Reports	5	94	January 10, 2026

Project Rules: Documented RULE.md folder format not working, only undocumented .mdc format works

Where does the bug appear (feature/product)?

Describe the Bug

Steps to Reproduce

Expected Behavior

Operating System

Current Cursor Version (Menu → About Cursor → Copy)

For AI issues: which model did you use?

For AI issues: add Request ID with privacy disabled

Additional Information

Does this stop you from using Cursor

Where does the bug appear (feature/product)?

Describe the Bug

Steps to Reproduce

Expected Behavior

Operating System

Current Cursor Version (Menu → About Cursor → Copy)

Does this stop you from using Cursor

Where does the bug appear (feature/product)?

Describe the Bug

Project Rules with RULE.md folder format not working - Documentation issue or bug?

Summary

Environment

Description

My RULE.md

Question

Workaround

Steps to Reproduce

Expected Behavior

Screenshots / Screen Recordings

Operating System

Current Cursor Version (Menu → About Cursor → Copy)

Does this stop you from using Cursor

Related topics

Project Rules with `RULE.md` folder format not working - Documentation issue or bug?