rules

Write it down once. Every AI coding tool reads the same kind of file.

May 20, 2026

Sanjay Kushwah

Software Engineer

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
Cursor — .cursorrules (single file) or .cursor/rules/*.mdc (multiple, scoped)
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: Codex and opencode read AGENTS.md natively. Claude Code reads CLAUDE.md but can @import AGENTS.md. Cursor and Copilot read their own files. The clean pattern, if you’re using multiple tools, is one canonical AGENTS.md at your repo root, then minimal tool-specific files that import or reference it. One source of truth; every agent in your stack walks in already knowing.

For the full mechanics — layering, path-scoping, nested files, the differences between how each tool merges multiple sources — see Rules.