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

A developer published a free MIT-licensed starter repo, theodorecreatesco/vibe-coding-rules-starter, that consolidates AI coding-agent instructions into a single AGENTS.md as the cross-tool source of truth, with CLAUDE.md importing it via @AGENTS.md and Cursor-specific glob rules living in .cursor/rules/*.mdc. The writeup maps which tools read each file — AGENTS.md for Cursor, GitHub Copilot coding agent, Codex, Windsurf, Zed and Amp; .cursor/rules/*.mdc for Cursor only; CLAUDE.md for Claude Code — and notes the older single-file .cursorrules format still works but is superseded by Cursor's front-matter rules model. The author recommends keeping AGENTS.md short and verifying placement by asking a fresh chat to name the project's top rules.

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 https://github.com/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 https://www.etsy.com/uk/listing/4601953941 — 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.