AGENTS.md: One Rules File Every AI Coding Tool Reads

You’ve told Copilot “we use pnpm, not npm” a hundred times. Once per session. Maybe more if the session is long enough that it forgets.

The fix is older than agents themselves: write it down. In one file. Check it in. Let the tool read it.

Every major AI coding tool added this primitive in the same year - and they’re all essentially the same file under different names:

• GitHub Copilot - .github/copilot-instructions.md, and increasingly AGENTS.md (its coding agent, code review, and JetBrains support now read it natively)
• Cursor - .cursor/rules/*.mdc (scoped, current) plus AGENTS.md at the root; the old single-file .cursorrules is legacy
• Claude Code - CLAUDE.md (project root, with imports for @AGENTS.md); it also reads AGENTS.md directly when no CLAUDE.md exists (v2.1.277 and later)
• Codex - AGENTS.md (the open spec, agents.md)
• OpenCode - AGENTS.md (same open spec)

Same idea. Different filenames. Convergence on a pattern that should embarrass anyone who said this would never standardise.

What goes in it? Whatever the agent gets wrong twice. Real examples from real teams:

• “Tests live in __tests__/, not next to source.”
• “All DB calls go through db/repo/. Never direct queries from route handlers.”
• “Use pnpm validate before declaring done. Never push to main.”
• “The auth flow is in docs/auth.md - read it before touching anything under services/auth.”

The test: if you’ve corrected the agent on the same thing twice across two sessions, that’s a candidate for the file. The cost of writing one line of context now is much smaller than the cost of correcting the agent for the next year.

The portability move: the convergence runs deeper than a shared shape - most tools now read AGENTS.md itself. Codex and OpenCode always did. Cursor reads it from the repo root; Copilot now reads it too, across its coding agent, code review, and JetBrains support. Claude Code reads AGENTS.md directly only when there is no CLAUDE.md in the project (v2.1.277 and later); once a CLAUDE.md exists it reads that instead, so the CLAUDE.md should @import AGENTS.md. So the clean pattern, if you’re using multiple tools, is one canonical AGENTS.md at your repo root, plus a tool-specific file only where a tool insists on its own - Claude’s CLAUDE.md, Cursor’s scoped .cursor/rules/ overrides. One source of truth; every agent in your stack walks in already knowing.

For the per-tool mechanics, see Rules for layering, path-scoping, nested files, and how each tool merges multiple sources.