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)
• 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 CLAUDE.md but can @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.