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.
| File | Who reads it | Best use |
|---|---|---|
AGENTS.md |
Cursor, GitHub Copilot coding agent, Codex, Windsurf, Zed, Amp and a growing list of others | Shared project brief: how to work, security, commands, what "done" means |
.cursor/rules/*.mdc |
Cursor only | Narrow rules that should load for certain globs (or always) |
CLAUDE.md |
Claude Code | Claude-specific extras; can import AGENTS.md with@AGENTS.md |
.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.
AGENTS.md`` CLAUDE.md``@AGENTS.md, then add only Claude-specific notes if you need them..cursor/rules/`` globs: ["app/**/*.tsx"]), plus one short always-on security rule if you want the guardrails in every Cursor chat even when Do not paste the same 200-line manifesto into all three. One source of truth beats three copies that disagree by Thursday.
Keep AGENTS.md short enough that a model will still follow it:
Leave stack fashion tips and long architecture essays for docs humans read, or for glob-scoped .mdc files.
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.
.cursor/rules/*.mdc is enough.
That is the whole map. Pick the shared file once, keep it short, and stop rewriting the same rules under three names.