AGENTS.md vs .cursorrules vs CLAUDE.md: what goes where

If you use more than one AI coding tool, you have probably ended up with three nearly identical...

If you use more than one AI coding tool, you have probably ended up with three nearly identical instruction files and no idea which one actually loaded. Here is the short version of what each file is for, and a setup that stops the drift.

The three files in one table

.cursorrules (single file at the repo root) is the older Cursor format. It still works in many setups, but Cursor's current project-rules model is .cursor/rules/*.mdc with front matter for description, globs and alwaysApply.

AGENTS.md is intentionally boring Markdown. There is no special schema. Agents just read the text. That is why it works as the cross-tool home for rules you do not want to rewrite three times.

A setup that actually holds

1. Put the real rules in AGENTS.md at the repo root: rule priority, security guardrails, how to make changes, which commands to run, what to report when finished.
2. Make CLAUDE.md thin. Start it with @AGENTS.md, then add only Claude-specific notes if you need them.
3. Add .cursor/rules/ only for things that should attach to certain files (for example a Next.js App Router rule with globs: ["app/**/*.tsx"]), plus one short always-on security rule if you want the guardrails in every Cursor chat even when AGENTS.md is long.

Do not paste the same 200-line manifesto into all three. One source of truth beats three copies that disagree by Thursday.

What belongs in the shared file

Keep AGENTS.md short enough that a model will still follow it:

• Rule priority when instructions clash (security beats "just make it work").
• Hard security lines: secrets stay in server env, auth checks on every sensitive path, no destructive git or force-push unless asked.
• Working style: read before editing, smallest change, stay in scope, run the real tests.
• Project commands: install, test, lint, start — the ones a new teammate would need.

Leave stack fashion tips and long architecture essays for docs humans read, or for glob-scoped .mdc files.

A free starter you can copy

I keep a free MIT starter with a ready AGENTS.md, a CLAUDE.md that imports it, an always-on Cursor security rule, a 10-point pre-launch checklist and three copy-paste prompts:

theodorecreatesco/vibe-coding-rules-starter

Clone it, copy the three files into your project, and ask a fresh chat: "What are the top rules in this project?" If it cannot name the priority and the security lines, the files are not where the tool expects them.

If you later want stack packs, more prompts and a one-command installer for several tools, that is the paid Vibe Coding Rules Kit on Etsy — same brand, optional upgrade. The starter on GitHub stays free either way.

Quick decision guide

• One tool, Cursor only, path-specific rules: .cursor/rules/*.mdc is enough.
• One tool, Claude Code only: CLAUDE.md is enough.
• Mixed tools, open source repo, or you are tired of syncing: AGENTS.md as the source of truth, thin pointers elsewhere.

That is the whole map. Pick the shared file once, keep it short, and stop rewriting the same rules under three names.