AI Coding · Rules Files

What Is a .cursorrules File?
And .cursor/rules/*.mdc, explained

You opened a repo and found a .cursorrules file, or a .cursor/rules/ folder full of .mdc files, and wondered what they are. Short answer: they are Cursor’s rules files, plain Markdown that tells the Cursor editor how to work on your project.

The only real confusion is that Cursor has two formats, an old one and a new one. Here is what each is, where it lives, and what an .mdc file actually is.

The two formats

File Where What it is
Legacy .cursorrules A single file at the repo root Plain Markdown. Still works; Cursor now recommends the newer format.
Modern .cursor/rules/*.mdc One or more files in a .cursor/rules/ folder Markdown with a small header block for scoping.

If a repo has both, Cursor leans on the .cursor/rules/ folder. The old .cursorrules is not broken, it is just the previous generation of the same idea.

What is an .mdc file?

An .mdc file is Markdown with a small header block on top. That header (frontmatter) scopes the rule: a short description, and often file globs that say which files the rule applies to. Everything below the header is ordinary Markdown, the same headings and lists you would write anywhere.

So an .mdc is not a new language to learn. It is a Markdown file with a bit of metadata at the top. If you are new to the syntax underneath, see How to Write Markdown.

Where they go

  • .cursorrules sits at the root of your repo, next to package.json or whatever your project’s root config is.
  • .cursor/rules/ is a folder at the root, holding one or more .mdc files. Splitting rules across several files (one per framework or concern) is the point of the newer format.

What goes inside (and how it relates to the others)

The content is the same kind of thing every AI rules file holds: your stack, conventions, the commands to run, and boundaries. If your repo also has an AGENTS.md or CLAUDE.md, they cover the same ground for other tools. For the full map of which tool reads which file, see Which AI rules file does your tool read?, and for what to actually put in one, What are AGENTS.md and CLAUDE.md?

Reading your repo’s Markdown with NoteLoom

Once you see that these are all Markdown, reading them is just reading Markdown. Your repo’s rules and docs, the AGENTS.md, the CLAUDE.md, the README.md, are Markdown files, and NoteLoom opens the folder right in the browser and renders them in a clean reading view, with a source view for editing and saving back to disk.

To be clear about the boundaries: NoteLoom has no AI. It will not make Cursor follow your rules, and it does not connect to Cursor or any coding tool. It opens, renders, and saves your Markdown files. The rules stay between you and your editor.

How you use it: open app.noteloom.cc in Chrome / Edge / Arc, mount your project folder, and read or edit the Markdown docs in it. Saved straight to your disk, no cloud, no account.

Related reading

Which AI rules file does your tool read? AGENTS.md, CLAUDE.md, .cursorrules, copilot-instructions, mapped by tool. What are AGENTS.md / CLAUDE.md? What goes inside the rules files, and how to write one. What is copilot-instructions.md? GitHub Copilot’s rules file: where it goes and what to write. How do you manage AI coding rule files? Keeping a pile of rules files organized and consistent. Online Markdown Editor Open a repo folder and read or edit its Markdown in your browser.

FAQ

What is a .cursorrules file?
It is the rules file for the Cursor editor: plain Markdown at your repo root that describes your project (stack, conventions, boundaries) so Cursor has that context while it works. It is the older, single-file format. The newer approach is one or more .mdc files in a .cursor/rules/ folder.
What is an .mdc file?
An .mdc file is Markdown with a small header block on top (frontmatter) that scopes the rule, for example a short description and file globs that say when it applies. Below the header it is ordinary Markdown. So it is still a text file you can read in any editor.
Where does the .cursorrules file go?
At the root of your repo, next to package.json or your project’s equivalent root config. The newer .mdc files go inside a .cursor/rules/ folder at the root, and you can have several of them, one per concern or framework.
.cursorrules or .cursor/rules, which should I use?
Cursor now recommends the .cursor/rules/*.mdc format, because it supports scoping and multiple files. The single .cursorrules file still works and is fine for simple projects. Which one Cursor reads is up to Cursor; both are just Markdown you write.
Is a .cursorrules file just Markdown?
Yes. The legacy .cursorrules is plain Markdown, and an .mdc is Markdown with a header block. That is the same underlying format as AGENTS.md and CLAUDE.md, which is why all of these rules files read alike.
Can I read these files in a Markdown editor like NoteLoom?
The content is Markdown, so it reads like any .md. NoteLoom opens your repo folder and renders the Markdown files in it (AGENTS.md, CLAUDE.md, README.md) in a clean view, saved locally. It has no AI: it will not make Cursor follow the rules, it just helps you read and write the Markdown itself.
Can I do this with NoteLoom on my phone or in Safari?
Not for now. NoteLoom relies on the browser’s File System Access API, which currently works in Chromium-based desktop browsers like Chrome, Edge, and Arc. Firefox, Safari, and mobile are not supported yet.

Read the rules files in your repo

Open NoteLoom in Chrome / Edge / Arc, mount your project folder, and read or edit its Markdown docs in a clean view. Saved straight back to your disk, no software to install and no account to sign up for.

Open NoteLoom and try it