Cursor's Agent keeps ignoring conventions saved in `.cursor/rules/api-style.md` — where do project rules live, and why is this file never applied?
answer
- a folder under version control
- the extension matters, not the name
- frontmatter decides when it loads
- plain markdown has another home
- the old single file at the root
basics
~20 sCursor project rules are .mdc files in .cursor/rules, committed with the repository. A plain .md file there is ignored because it has no frontmatter saying when it applies; rename it to .mdc with frontmatter, or put plain markdown in AGENTS.md.
solid answer
~40 sProject rules live in `.cursor/rules` as `.mdc` files and are version-controlled, so the whole team gets them. The rules system only picks up `.mdc`: a plain `.md` file in that folder is ignored, because it has no frontmatter carrying `description`, `globs` and `alwaysApply` — the fields that decide when a rule is included. The fix is to rename it to `api-style.mdc` and give it frontmatter, for example `alwaysApply: true` if it should reach every Agent chat. If the team prefers plain markdown with no metadata, the text belongs in `AGENTS.md` instead. Two more checks when a rule still seems ignored: rules steer Agent (Chat), not Tab or Inline Edit, and a root `.cursorrules` file is legacy and should be migrated into `.cursor/rules`.
go deeper
Recall the path and the extension: project rules are .mdc files in .cursor/rules, committed to git. A plain .md file in that folder is silently ignored.
Explain why the extension matters: frontmatter with description, globs and alwaysApply decides when a rule loads, and the rules system reads only .mdc files for it. Know AGENTS.md as the plain-markdown alternative.
When a team says the agent ignores conventions, check the file type, which surface they tested and whether a legacy .cursorrules still holds the real text, before rewriting any rule.
Treat rules as shared, reviewed code: one concern per file, short, changed through pull requests, and backed by linters for anything that must hold on surfaces rules do not reach.
## Where Cursor looks for project rules Cursor's **Agent** builds its context from a system prompt, its tools and **rules** — persistent instructions that are included at the start of the model context when they apply. A language model keeps no memory between requests, so a rule is how a team's unwritten conventions reach every conversation without being retyped. Cursor documents several sources of rules. The one that lives with the code is the **project rule**: - **Location:** the `.cursor/rules` folder at the project root. Subfolders inside it work (`.cursor/rules/frontend/components.mdc`), although a flat folder is simpler to manage. - **Format:** one **`.mdc`** file per rule — markdown content with a YAML frontmatter block on top. You can name the file anything. - **Sharing:** the folder is version-controlled, so committing it gives every teammate the same rules. The other sources — User Rules, Team Rules and `AGENTS.md` — are configured elsewhere and do not depend on this folder. ## Why a .md file is skipped The rules system recognises a file by its extension. Cursor's rules reference is explicit: project rules **must** use the `.mdc` extension, and a plain `.md` file in `.cursor/rules` is ignored because it has no frontmatter to specify `description`, `globs` and `alwaysApply`. Those three fields tell Cursor *when* to include a rule, and only `.mdc` files are read as rules, so a `.md` file is never loaded — whatever its content says. | File | Picked up as a project rule? | | :-- | :-- | | `.cursor/rules/api-style.mdc` | Yes | | `.cursor/rules/frontend/components.mdc` | Yes — subfolders are scanned | | `.cursor/rules/api-style.md` | No — wrong extension | | `~/.cursor/rules/...` | No — that is a user rule file on one machine, not shared through the repo | That is why an Agent can keep "ignoring" a convention someone carefully wrote down: the file was never part of its context. ## Fixing the file 1. Rename `api-style.md` to `api-style.mdc`. 2. Add frontmatter. For a convention that should reach every chat: ```markdown --- alwaysApply: true --- - Every handler validates its input at the service boundary - Return structured errors with a `code` and a `message` ``` 3. Open **Customize** in the sidebar and go to **Rules**: it lists every rule and its status, so you can confirm the rule is now recognised. You can also let Cursor write the file: type `/create-rule` in Agent and describe the rule, use **Add Rule** under Customize → Rules, or run **New Cursor Rule** from the command palette. Each of these saves an `.mdc` file into `.cursor/rules` with proper frontmatter. If the team simply wants readable instructions with no metadata, `AGENTS.md` at the project root is Cursor's plain-markdown alternative. ## Where rules do not reach A correctly saved rule can still look ignored if it is judged on the wrong surface. Cursor's help pages state that rules apply to **Agent (Chat)** and do **not** apply to: - **Tab** completions; - **Inline Edit** (Cmd/Ctrl+K); - **Bugbot** pull-request reviews, which read their own rule sources instead. A developer who checks a Tab suggestion against the rule and concludes "rules are broken" is testing the wrong feature. The Cursor CLI's agent, by contrast, supports the same rules system as the editor and loads `.cursor/rules` according to each rule's configuration. ## What a good project rule contains Once the file loads, its content decides whether Agent's code actually changes. Cursor's own guidance: - **Focused and actionable** — one concern per file, written like clear internal documentation, not vague advice. - **Short** — under 500 lines; split a large rule into composable ones. - **Pointing, not copying** — reference a canonical file with `@filename` instead of pasting code that will go stale. - **Not a style guide** — formatting belongs to a linter; Agent already knows common conventions. - **Grown from mistakes** — add a rule when Agent repeats the same error, and update it when it errs again. ## The legacy .cursorrules file Older repositories often carry a single `.cursorrules` file at the root. Cursor's help page calls it **legacy** and says it **will be deprecated**. The documented migration: 1. Create a new rule with **New Cursor Rule** from the command palette. 2. Copy the `.cursorrules` content into it. 3. Set the rule type to **Always Apply**, which matches the old file's behaviour. 4. Delete `.cursorrules` from the project root. Splitting a long `.cursorrules` into several focused rules during the migration is worthwhile: Cursor recommends keeping each rule under 500 lines, one concern per file. ## Summary - Project rules: `.mdc` files in `.cursor/rules`, committed to the repository. - A `.md` file there is ignored; rename it and add frontmatter, or use `AGENTS.md`. - Rules steer Agent (Chat), not Tab, Inline Edit or Bugbot. - A root `.cursorrules` is legacy: migrate it into an Always Apply rule.
- A repository still has a root `.cursorrules` file — what should the team do with it?Migrate it. Cursor calls the root `.cursorrules` legacy and says it will be deprecated. Create a rule with **New Cursor Rule** from the command palette, paste the content in, set the type to **Always Apply** (that matches the old behaviour), and delete `.cursorrules`. Splitting it into focused `.mdc` files is a good moment to trim it below Cursor's suggested 500 lines per rule.
- Two rules called `conventions.mdc` sit in different subfolders of `.cursor/rules` — does one override the other?No. Cursor identifies a rule by its full file path, not its file name, so both rules apply whenever their conditions match. There is no override by name; if they contradict each other, merge them or scope each one with `globs`.
- Any markdown file dropped into .cursor/rules is picked up as a rule
- A root .cursorrules file is still the recommended place for project rules
- Project rules also steer Tab completions and Inline Edit
- Project rules are personal settings each developer recreates on their machine
- Two rule files with the same name override each other