Two years ago this question did not exist. Now most working developers maintain somewhere between two and four agent instruction files per repo, and the files disagree with each other more often than they agree. This is the current state of each format, what it actually does, and a setup that avoids maintaining four copies by hand.
The four formats
| AGENTS.md | CLAUDE.md | .cursor/rules/*.mdc | .github/copilot-instructions.md | |
|---|---|---|---|---|
| Primary reader | Codex, Zed, Jules, Cursor (partially), many others | Claude Code | Cursor | GitHub Copilot (code review + workspace chat) |
| Origin | OpenAgentsConfig community standard, 2024 | Anthropic, 2024 | Cursor, 2024 (replaced global .cursorrules) | GitHub, 2024 |
| Activation model | Loaded when agent works in a directory tree containing the file | Loaded at session start from repo root and ~/.claude/; subdirectory CLAUDE.md files load on demand |
Per-rule: always-on, glob-scoped, or model-requested | Loaded into workspace context for Copilot Chat and reviews |
| Scope convention | Root file plus nested files per package | Root plus subdirectories plus imports via @path
|
Directory-scoped via globs | Single repo-wide file |
| Versioning | You version it (plain markdown) | Plain markdown, plus ~/.claude memory lives outside the repo |
Plain markdown with YAML frontmatter | Plain markdown |
| Community drift risk | Low, the format is a plain convention | Low | Medium, frontmatter schema still evolving | Low but feature-poor |
The important column is activation. AGENTS.md, CLAUDE.md, and copilot-instructions.md are loaded wholesale: whatever you write is in context whenever the agent works. Cursor rules are the only format with per-rule activation control, which makes them both the most powerful and the easiest to break.
What each format is good at
AGENTS.md won the "common denominator" role. It is deliberately boring: a plain markdown file with no schema, discovered by walking up the directory tree. Because the content is unstructured, every tool interprets it slightly differently, but the format itself is stable. If you only maintain one file for cross-tool compatibility, maintain this one.
CLAUDE.md is read at session start and supports imports (@path/to/file.md), which makes it the best of the three single-file formats for splitting large configs. Claude Code also reads subdirectory CLAUDE.md files when working in those directories, so monorepos can scope instructions per package without any special syntax:
# CLAUDE.md (repo root)
- Run `pnpm test --filter <package>` before declaring anything done
- Never edit generated files in `packages/api/src/generated/`
@docs/adr/0004-auth-architecture.md
.cursor/rules/*.mdc is the only format where a rule can say "only apply to files matching src/api/**/*.ts". The frontmatter controls activation:
---
description: API route error handling for the payments service
globs: ["src/api/payments/**/*.ts"]
alwaysApply: false
---
- Every route handler wraps errors in `ApiError` with a machine-readable code
- Return `ProblemDetails` JSON, never raw strings
- Log with `logger.child({ route })`, not console
copilot-instructions.md is the weakest format in raw capability (one file, always on, no scoping) but it is the only one GitHub Copilot honors for code review, which matters if your team uses Copilot's PR review features.
The actual problem in 2026
The problem is not that any format is bad. It is arithmetic. A typical team ends up with:
- one CLAUDE.md, grown to 400+ lines because everyone added their pet rule
- eight Cursor rules, of which three have broken globs that match nothing
- one copilot-instructions.md written once at adoption, never touched
- no AGENTS.md, so Codex and Zed users on the team improvise
Four files, three of them stale, describing the same project to four different agents that then propose three different error-handling styles in the same PR. The cost is not writing config. The cost is the disagreements.
The setup that works
Maintain one source of truth per stack, and treat the four formats as build targets:
- Write instructions once, tagged by scope: always-on, or file-scoped.
- Generate all four formats from it. The always-on content becomes your AGENTS.md and CLAUDE.md core; file-scoped content becomes glob-scoped
.mdcrules; a short distillation becomes copilot-instructions.md. - Keep the always-on portion under a hard budget (300 lines is a good ceiling; see our piece on the instruction budget for why).
- Version the whole thing and pin which tool versions you validated against, so a Cursor or Claude Code update does not silently change how your rules resolve.
Generating formats is simple enough to script yourself; the four output shapes are all plain markdown. The harder parts, which is where teams actually lose time, are holding the line budget, keeping globs correct as the repo evolves, and noticing when a tool update breaks rule resolution.
A word on .cursorrules
The single-file .cursorrules at the repo root is deprecated. Cursor still reads it for backwards compatibility, but it lacks scoping entirely, and new Cursor features (rule selection, agent-requested rules) only work with .cursor/rules/*.mdc. If you still have one, migrate it: split always-on content into AGENTS.md, and everything else into glob-scoped rules. Do not start new repos on it.
If you want the four-format problem solved for you rather than scripted by you: AgentConfig Studio ships version-pinned config kits for 12 stacks that keep AGENTS.md, CLAUDE.md, Cursor rules, and copilot-instructions.md consistent from one source of truth, each passing the shipped validation harness before release. See the product page for what is in the pack and the free sample rules.
Top comments (0)