Cursor Ignores Your Rule Because It Is .md, Not .mdc

Bottom line

• Cursor project rules use .mdc, not .md.
• A file named .cursor/rules/api-guidelines.md is ignored.
• Rename it to .mdc, then set its activation mode in frontmatter.
• Use AGENTS.md when you want plain Markdown without Cursor-specific metadata.

The official Cursor Rules documentation says project rules live in .cursor/rules as .mdc files. It also states that a plain .md file in that folder is ignored. The page was checked on August 20, 2026.

The symptom

Your repository contains this file:

.cursor/
└── rules/
    └── api-guidelines.md

The file contains clear instructions. You restart Cursor, open an API file, and ask the agent to make a change. The agent does not follow the rule.

The content is not the first problem. Cursor never registered the file as a project rule.

The cause

Cursor’s project-rule format is MDC. The .mdc suffix tells Cursor to parse the frontmatter that controls when the rule applies.

A Markdown file can sit in the same directory and remain visible in the file tree. That does not make it active context.

This creates a silent failure. Nothing is malformed from the editor’s point of view, so you get no syntax error.

The fix

Rename the file:

mv .cursor/rules/api-guidelines.md .cursor/rules/api-guidelines.mdc

Then give it an explicit activation rule.

For a rule that must apply to every Agent chat:

---
description: API rules for this repository
globs:
alwaysApply: true
---

- Validate every request body before database access.
- Run the API test suite after changing a route.

For a rule that applies only when TypeScript API files enter context:

---
description: API rules for TypeScript routes
globs: src/api/**/*.ts
alwaysApply: false
---

- Validate every request body before database access.
- Run the API test suite after changing a route.

Do not set a narrow glob if you expect the rule to apply to unrelated files. An auto-attached rule only loads when a matching file is referenced.

Verify it in Cursor

Open Cursor Settings, then Rules. Confirm that the project rule appears and shows the intended type.

Start a new Agent chat with a matching file in context. Ask:

List the active project rules for this request before you edit anything.

The rule should appear by name. If it does not, check the glob and activation type next.

When to use AGENTS.md instead

Use AGENTS.md for simple repository instructions that should remain readable across tools. Cursor supports root and nested AGENTS.md files.

Use .mdc when you need Cursor-specific activation, such as globs or an always-apply flag.

Do not maintain the same rule in both places. Duplicate copies drift and can conflict.

Related agent-rule guides

• Your Agent Is Ignoring CLAUDE.md
• OpenClaw vs Cursor
• Claude Code Hooks That Cut Token Burn