AI Coding · Rules Files

Which AI Rules File Does Your Tool Read?
AGENTS.md, CLAUDE.md, .cursorrules & copilot-instructions

Every AI coding tool has grown its own "rules file": a plain .md you drop in your repo to tell the agent how to work. The confusing part is that they all picked different names. Claude Code wants CLAUDE.md, Copilot wants copilot-instructions.md, Cursor wants .cursor/rules, and a shared standard called AGENTS.md is spreading across all of them.

This is the map: which file each tool actually reads, where it lives, and the one thing that ties them together (they are all just Markdown).

The quick answer, by tool

Tool Rules file it reads Where it lives
Claude Code CLAUDE.md (also reads AGENTS.md) Repo root, or ~/.claude/ for global rules
Cursor .cursor/rules/*.mdc (legacy: .cursorrules) .cursor/rules/ folder, or repo root for the legacy file
GitHub Copilot .github/copilot-instructions.md (also AGENTS.md) The .github folder at your repo root
OpenAI Codex AGENTS.md Repo root, or ~/.codex/ for global rules
Windsurf .windsurf/rules/ (legacy: .windsurfrules) .windsurf/rules/ folder, or repo root for the legacy file
Gemini CLI GEMINI.md (also AGENTS.md) Repo root

Mappings shift as tools add support for the shared standard, so when in doubt, check your tool’s current docs. The trend is clear though: more and more tools also read AGENTS.md.

AGENTS.md: the cross-tool standard

If there is a winner emerging, it is AGENTS.md. It is an open format, stewarded under the Linux Foundation, and it is read by a growing list of agents including Cursor, Codex, Claude Code, Copilot, Windsurf, and Gemini. Think of it as a README written for agents instead of humans: the build steps, tests, and conventions an AI needs, kept out of your human-facing README.md.

For the full walkthrough of what goes inside one, see What are AGENTS.md and CLAUDE.md?

The tool-specific ones

  • CLAUDE.md is Claude Code’s file. Same idea as AGENTS.md, just the Claude-specific name. Claude Code reads it from the repo root, and reads a global one from ~/.claude/.
  • .cursorrules and .cursor/rules/*.mdc are Cursor’s. The old format was a single .cursorrules file at the repo root; the modern format is one or more .mdc files in .cursor/rules/ (an .mdc file is Markdown with a small header block for scoping).
  • copilot-instructions.md is GitHub Copilot’s, and it goes in .github/. See What is copilot-instructions.md? for the specifics.

The thing they have in common: it is all Markdown

Strip away the different filenames and every one of these is a plain Markdown file. Headings, lists, and code blocks, nothing more. Here is a small AGENTS.md, and a CLAUDE.md or a .cursorrules looks the same:

# AGENTS.md

## Commands
- Build: npm run build
- Test: npm test

## Code style
- TypeScript, 2-space indent
- No default exports

## Boundaries
- Never edit files under /vendor

Because they are all Markdown, you open, read, and edit any of them the same way. No special tool per format, no plugin. If you are new to the syntax, start with How to Write Markdown.

When you have several of them at once

Real repos often end up with more than one: an AGENTS.md, a CLAUDE.md, a .cursor/rules/ folder, maybe a .github/copilot-instructions.md. Keeping them consistent (and knowing which is the source of truth) is its own small chore. For that, see How to manage AI coding rule files, which is about organizing the whole pile rather than picking one.

Reading and comparing them with NoteLoom

To actually read these files side by side (or clean up the one your tool ignored because it was in the wrong place), you need an editor that opens a repo folder and renders Markdown. NoteLoom does exactly that, right in the browser: mount the folder, and its reading view shows AGENTS.md, CLAUDE.md, and the other .md rules files as clean formatted text, while the source view lets you edit and save back to disk.

To be clear about the boundaries: NoteLoom has no AI. It will not make Cursor or Claude follow your rules, and it does not connect to any coding tool. It just opens, displays, and saves the Markdown file itself. The rules, and whether the agent honors them, stay entirely between you and your tool.

How you use it: open app.noteloom.cc in Chrome / Edge / Arc, mount your project folder, open any .md rules file such as AGENTS.md or CLAUDE.md, and read or edit it. Saved straight to your disk, no cloud, no account.

Related reading

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? Organizing a pile of AGENTS.md, CLAUDE.md, and .cursorrules. What is README.md? The human-facing file, and how AGENTS.md differs from it. Online Markdown Editor Open a repo folder and read or edit any .md in your browser.

FAQ

What is a rules file for an AI coding tool?
It is a plain Markdown file you keep in your repo that tells the AI agent how to work on your project: the stack, the commands to run, conventions, and boundaries. The tool reads it at the start of a session. Different tools look for different filenames, which is where the confusion comes from.
What is the difference between AGENTS.md and CLAUDE.md?
CLAUDE.md is Claude Code’s own rules file. AGENTS.md is a cross-tool open format that many agents now read (Cursor, Codex, Copilot, and others). Claude Code reads CLAUDE.md and increasingly also picks up AGENTS.md. If you want one file most tools understand, AGENTS.md is the safer bet; CLAUDE.md is the Claude-specific one.
Which rules file does Cursor read?
Modern Cursor reads Markdown-based .mdc files inside a .cursor/rules/ folder. The older single .cursorrules file in the repo root still works, but Cursor now recommends the .cursor/rules/ format. Cursor also understands AGENTS.md.
Where does copilot-instructions.md go?
GitHub Copilot reads .github/copilot-instructions.md, so it lives in the .github folder at your repo root. See the dedicated guide on copilot-instructions.md for what to put in it.
Are these files all just Markdown?
Yes. AGENTS.md, CLAUDE.md, .cursorrules, copilot-instructions.md, and Cursor’s .mdc files are all plain Markdown (an .mdc file is Markdown with a small header block on top). That means you can open, read, and edit any of them with the same Markdown editor, no special tool required.
Can NoteLoom help me read and compare these files?
NoteLoom opens your repo folder and renders any of these .md files in a clean reading view, and lets you edit them in the source view, saved straight back to disk. It has no AI: it will not make your coding tool follow the rules, it just helps you read and write the file 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.

Open your rules files and read them properly

Open NoteLoom in Chrome / Edge / Arc, mount your project folder, and read or edit any AGENTS.md, CLAUDE.md, or other .md rules file 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