How to Write an AGENTS.md File for Cursor, Copilot & Codex

Your AGENTS.md is already bloated, and it’s hurting every tool that reads it. The frontier models your agents rely on reliably follow roughly 150 to 200 instructions per session, and Claude Code’s system prompt already burns about 50 of them — leaving you a real budget of approximately 100 to 150 user instructions before adherence rots. Yet most teams are stuffing 300+ lines into a single file, then wondering why Copilot ignores half the rules and Claude Code drifts off-convention by turn three.

The fix isn’t writing better instructions. It’s architecting them correctly.

The Layered Configuration Model

The pattern I’ve observed across high-performing teams is what I call a layered configuration architecture: a canonical AGENTS.md serving as the portable base, with thin tool-specific adapters handling specialized capabilities. This isn’t theoretical — it’s the mid-2026 default for any team running more than one agent.

Here’s the core split:

AGENTS.md — universal conventions every tool should know (build commands, code style, security boundaries, testing instructions)
CLAUDE.md — Claude Code’s authoritative memory layer with enforceable permissions
.cursor/rules/*.mdc — Cursor’s glob-scoped activation for file-pattern-specific behavior (AGENTS.md vs CLAUDE.md vs Cursor rules)
.github/copilot-instructions.md — Copilot-specific guidance for modes AGENTS.md doesn’t cover (general Copilot integration guide)

The canonical AGENTS.md should stay focused and concise. Every line you add beyond what’s necessary is borrowed from the agent’s capacity to actually do your work.

What AGENTS.md Actually Is

AGENTS.md is plain Markdown with no required fields, schema, or special syntax. It’s stewarded by the Linux Foundation’s Agentic AI Foundation and read natively by Codex, Cursor, Copilot, and 30+ other tools. Think of it as a README for machines — not a configuration spec.

The format’s simplicity is its strength and its trap. Because there’s no schema enforcement, teams treat it as a dumping ground. A study of 2,500+ repositories by GitHub’s engineering team found that effective files prioritize copy-pasteable commands over vague tool names, real code snippets over descriptive prose, and explicit boundaries over implicit assumptions.

Here’s what belongs in your root AGENTS.md:

Project overview — what the project is, primary language and framework with versions
Build and test commands — exact commands with flags, not vague tool names
Code style guidelines — only rules that differ from language defaults
Testing instructions — how to run the suite, a single test, and what to mock
Security considerations — secrets handling, files to never read or commit
Commit and PR guidelines — branch naming, commit format, merge strategy

That’s it. If you’re writing more than six sections, you’re probably writing documentation that belongs in your README or wiki.

How Each Tool Reads Your File

This is where most multi-tool strategies break down. AGENTS.md is not consumed uniformly.

GitHub Copilot reads AGENTS.md from the repository root and docs/ directory, but treats it as a strong system prompt rather than authoritative configuration. Copilot code review added support for repository-level AGENTS.md files on June 18, 2026. Copilot CLI does not read AGENTS.md at all. The practical implication: rules you write for Copilot need a companion .github/copilot-instructions.md for full coverage.

Claude Code reads CLAUDE.md as authoritative and only falls back to AGENTS.md when CLAUDE.md is absent. If both exist, Claude Code takes CLAUDE.md and ignores AGENTS.md entirely. This is the one place where the “single source of truth” dream breaks — Claude Code’s native format is strictly richer, with a 3-layer memory model and enforceable permission rules via settings.json.

Cursor uses .cursor/rules/*.mdc with YAML frontmatter for glob-scoped activation, replacing the legacy .cursorrules format. This is genuinely powerful — you can activate rules based on file patterns, which AGENTS.md can’t do. If your team relies on Cursor, thin adapter files in .cursor/rules/ are non-negotiable.

OpenAI Codex reads AGENTS.md natively and enforces a 32 KiB default size cap. That cap is a signal. Vendors already recognize the instruction budget constraint and are building guardrails around it.

The Instruction Budget Problem

HumanLayer ran Claude Code on a 1M-token context window and deliberately went back to a smaller one, citing “dramatically degraded” instruction adherence at full context. The same team’s research puts a hard number on the ceiling: frontier LLMs reliably follow roughly 150 to 200 instructions per session, and Claude Code’s system prompt consumes about 50 of those. That leaves you approximately 100 to 150 instructions of real budget for your rules. Every line in your AGENTS.md, every rule in your .cursor/rules/ files, and every instruction in CLAUDE.md spends from that same budget every single turn.

This is why monolithic configuration fails. A 400-line AGENTS.md doesn’t give the agent 400 instructions worth of guidance — it gives the agent 400 instructions worth of noise, and the model’s adherence to any single one of them degrades proportionally.

The canonical-plus-adapters architecture works because it respects this constraint. Your AGENTS.md carries the 80-100 instructions every tool needs. Your CLAUDE.md and .cursor/rules/ files carry the 20-30 instructions specific to those tools. The agent never sees all 400 at once — it sees the relevant subset.

Monorepos Need Multiple Files

In monorepos, the nearest AGENTS.md to the edited file takes precedence. OpenAI’s own repository uses 88 AGENTS.md files across its directory tree. This isn’t a workaround — it’s the intended discovery mechanism.

Place an AGENTS.md in each package or subproject that has distinct conventions. The root file carries org-wide defaults. Subdirectory files override with package-specific build commands, test patterns, and architectural constraints.

The same logic applies to CLAUDE.md — Claude Code walks up the tree and concatenates nested files. But remember: Claude Code reads CLAUDE.md as authoritative and only falls back to AGENTS.md when CLAUDE.md is absent. If you’re running Claude Code in a monorepo, you need CLAUDE.md files at each level where you want Claude-specific behavior.

The Comparison You Need

Dimension	AGENTS.md	CLAUDE.md	.cursor/rules/*.mdc	.github/copilot-instructions.md
Owner	Agentic AI Foundation (Linux Foundation)	Anthropic	Cursor	Microsoft
Format	Plain Markdown	Markdown + `@import`	Markdown + YAML frontmatter	Markdown
Permission model	None built-in (prose only)	`allow`/`ask`/`deny` in settings.json	Four activation modes + per-rule ask/never	None
Read by	30+ tools natively	Claude Code (authoritative)	Cursor	Copilot
Best for	Cross-tool conventions	Claude Code memory & permissions	Glob-scoped editor behavior	Copilot-specific guidance
Size guidance	Keep it focused	Under ~800 words	As needed per rule	Concise

A Concrete Layout

Here’s the directory structure I’d ship on any multi-tool repo:

your-project/
├── AGENTS.md                          # Universal, tool-agnostic ground truth
├── CLAUDE.md                          # Claude Code additions (hooks, permissions, workflow)
├── .github/
│   └── copilot-instructions.md        # Copilot-specific guidance
├── .cursor/
│   └── rules/
│       ├── conventions.mdc            # Cursor-scoped style rules
│       └── security.mdc               # Cursor-scoped security boundaries
└── packages/
    ├── api/
    │   └── AGENTS.md                  # API-specific build/test/architecture
    └── web/
        └── AGENTS.md                  # Web-specific build/test/architecture

The key discipline: AGENTS.md carries only what every tool needs. Tool-specific files carry only what that tool needs. If a rule appears in both AGENTS.md and CLAUDE.md, it’s redundant — pick one source.

Where This Architecture Breaks

Skills and slash commands don’t port. Claude Code Skills live in .claude/skills/ and .claude/commands/. They don’t automatically work in Codex, Copilot, or Cursor. If your team relies on Skills for reusable workflows, you’ll need to maintain parallel implementations or accept the lock-in.

MCP server configuration is still per-tool. The same GitHub MCP server needs entries in .mcp.json (Claude Code), .codex/config.toml (Codex), .vscode/mcp.json (VS Code), and .cursor/mcp.json (Cursor). Same URL, same auth, four formats.

Windows contributors break symlinks. If you use symlinks to share a canonical file across tools, Windows clones them as plain text files reading “AGENTS.md” — and the agent loads nothing. Use file copies or @import patterns instead.

The Recommendation

Start with a hard audit of your current AGENTS.md. Count the instructions — not the lines, the discrete directives. If you’re over 150, you’re already in the degradation zone. Move tool-specific rules to their native adapter files. Keep AGENTS.md as the portable base layer that any of the 30+ tools reading it can consume without waste.

The teams getting the best results from multi-agent setups in 2026 aren’t writing better instructions. They’re writing fewer of them, in the right places, for the right tools. Your agent’s context window is a finite resource — treat your configuration like you’d treat that budget.