Photo by Bernd 📷 Dittrich on Unsplash
Photo by Roman Synkevych on Unsplash
- AGENTS.md is a cross-tool standard, formalized in August 2025, that gives AI coding agents explicit, machine-readable project instructions — adopted by over 60,000 open-source repositories as of July 6, 2026.
- Well-written human-authored files (100–150 lines) reduce median agent runtime by 28.64% and cut output token consumption by 16.58%, per published arXiv research.
- LLM-generated AGENTS.md files are a net negative: they reduce task success in 5 out of 8 tested settings and add 2.45–3.92 unnecessary steps per task.
- Codex silently truncates files beyond 32 KiB — a real production failure mode that GitHub's analysis of 2,500+ repositories confirmed is common.
What's on the Table
28.64%. That is the median runtime reduction researchers documented when AI coding agents operated with a well-structured AGENTS.md file in place, according to arXiv research (2601.20404) current as of July 6, 2026. The output token savings — 16.58% — matter even more in production environments where API costs accumulate across hundreds of daily tasks.
According to Google News, with original reporting from H2S Media, AGENTS.md emerged in August 2025 through a collaborative effort between OpenAI, Google, Cursor, Factory, and Sourcegraph to solve a fragmentation problem that had quietly become painful: developers were maintaining separate instruction files for every AI coding tool they used. .cursorrules for Cursor. CLAUDE.md for Claude Code. copilot-instructions.md for GitHub Copilot. The result was a maintenance overhead that scaled with adoption.
The AGENTS.md format functions as a "README for machines" — a structured, machine-readable file at the project root that tells AI coding agents what the project is, how it's organized, what conventions it follows, and what constraints must not be violated. As of July 6, 2026, it has been adopted by over 60,000 open-source repositories and is natively supported by more than 30 AI coding tools, including OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Google Jules, Factory, Aider, Zed, and Windsurf. Claude Code reads it alongside its native CLAUDE.md file via a compatibility layer.
The backdrop is a market in full acceleration. As of July 6, 2026, the AI coding assistant sector reached $12.8 billion and is projected to hit $30.1 billion by 2032 at a 27% compound annual growth rate, per market research. Among developers, 85% use AI coding tools, 62% rely on at least one assistant regularly, and 51% use AI tools daily.
The Pattern — Context Fragmentation as the Core Agent Failure Mode
AI agents fail for a specific structural reason: they get dropped into repositories designed exclusively for humans and have no persistent memory between sessions. They must infer structure, conventions, workflows, and constraints from scattered documentation — READMEs written for onboarding developers, not for machines executing tasks in a loop. AGENTS.md addresses this by making project instructions explicit and machine-readable before the agent takes its first action.
This is the ReAct pattern's hidden dependency. Any agent running a cycle of Reason → Act → Observe needs a stable context layer to reason from. Without explicit project instructions, the agent burns tokens inferring what should have been stated — and often infers wrong. The result is tool-call loops where an agent repeatedly tries approaches that violate project conventions it had no way to know about. AGENTS.md is infrastructure, not documentation. That framing distinction matters for how teams treat it.
Market share data from JetBrains (January 2026) illustrates why a shared standard is valuable: as of July 6, 2026, GitHub Copilot, Cursor, and Claude Code together control over 70% of the AI coding market, with Copilot at 29% workplace adoption and both Cursor and Claude Code tied at 18% each. A developer using all three was, until August 2025, maintaining three separate instruction files with no guarantee of consistent behavior across tools.
Chart: GitHub Copilot, Cursor, and Claude Code market share among AI coding tools, per JetBrains January 2026 data.
Photo by Daniil Komov on Unsplash
Side-by-Side: How AGENTS.md Behaves Across Major Tools
The standard supports hierarchical scoping: AGENTS.md files can exist at the repository root, in subdirectories, and within personal profile folders. A monorepo can carry project-wide instructions at the root and package-specific overrides at the module level. Each tool interprets this hierarchy with slight differences, which is where the "universal standard" framing gets complicated in practice.
OpenAI Codex was the original anchor. Launched in August 2025 as a cloud-based software engineering agent powered by codex-1 (an optimized variant of o3), Codex supports parallel task execution including writing features, answering codebase questions, and proposing pull requests. It also enforces a 32 KiB default size limit — anything beyond that is silently truncated. GitHub's analysis of over 2,500 AGENTS.md files in public repositories identified this as a common silent failure: developers write comprehensive files that get cut off mid-instruction with no warning.
GitHub Copilot added native AGENTS.md support in August 2025, reading the file automatically in supported contexts. It treats the file as a first-class instruction layer alongside its existing copilot-instructions.md format, respecting hierarchical scope.
Cursor became arguably the fastest-growing SaaS company ever recorded, reaching $1M to $2B ARR in approximately 28 months. Its AGENTS.md support reads the file as an extension of its existing .cursorrules workflow, allowing teams to consolidate instruction maintenance into a single file rather than maintaining two.
Claude Code reads AGENTS.md alongside its native CLAUDE.md format. The practical distinction: CLAUDE.md handles Claude-specific behavior — memory management, tool permissions, session context — while AGENTS.md carries the shared project-layer conventions any agent should know. Teams using Claude Code alongside Copilot or Cursor typically maintain both, using AGENTS.md for shared conventions and CLAUDE.md only for Claude-specific overrides. (This mirrors a broader pattern that AI Tools explored when comparing Claude against other AI assistants — Claude's native instruction formats give it a context depth edge, but cross-tool standardization demands the shared layer.)
GitHub's analysis of 2,500+ repositories found a consistent pattern among top performers: 100 to 150 lines, focused reference documents rather than exhaustive prose, and procedural workflows rather than abstract descriptions. Procedural workflow sections specifically — the "run tests with pytest -x" and "never modify config/prod.yml directly" type of instruction — showed 25% higher correctness and 20% higher completeness compared to files containing only general project descriptions. Mid-size module improvements across coding metrics landed in the 10–15% range.
Where This Breaks in Production
Here is the failure mode most tutorials skip: LLM-generated AGENTS.md files actively hurt performance. Research from Augment Code found that auto-generated files reduce task success in 5 out of 8 tested settings and add between 2.45 and 3.92 extra steps per task. The mechanism is predictable — language models generate generic, verbose instructions that state the obvious, consuming context window space without adding signal. A context window blowup caused by a bloated AGENTS.md is a real, measurable production failure mode, not a theoretical edge case.
The cost story is also more divided than the headline numbers suggest. arXiv study 2601.20404 documents the 28.64% runtime reduction and 16.58% token savings. A separate arXiv study (2602.11988) found that context files can increase inference costs by over 20% without improving task success rates at all. The difference is file quality: human-written, focused files deliver the savings; auto-generated, verbose files deliver the cost spike without the benefit. These two studies are not in conflict — they describe different ends of the quality spectrum.
The Codex 32 KiB truncation limit creates a specific and hard-to-catch production bug: a developer adds detailed CI/CD instructions at the bottom of a long AGENTS.md, tests locally with a tool that reads the full file, then watches Codex silently ignore those instructions in cloud execution because the file was truncated. No error. No warning. Just missing behavior that surfaces as incorrect agent output.
My read on the data: the "model upgrade" framing for AGENTS.md is accurate only when the file is written by a developer who deeply understands the project and actively maintains it. Treating AGENTS.md as documentation you generate once and forget — or auto-generate with an LLM — is the fastest path to context debt. The file needs versioning, periodic pruning, and PR reviews just like any other infrastructure config. A 100-line AGENTS.md that's current is more valuable than a 300-line one that describes a codebase from six months ago.
Which Fits Your Situation
The right question is not whether to create an AGENTS.md. As of July 6, 2026, with 80% of enterprises having at least one production AI agent (up from 33% in 2024), and 85% of developers already using AI coding tools, the file has become effectively standard infrastructure. The question is what to put in it and how to avoid the failure modes.
Project overview (what it does and why it exists), directory structure (where things live, what's off-limits), coding conventions (language version, style rules, test frameworks and commands), and procedural workflows (specific terminal commands to run before committing, files to never modify directly, CI patterns to follow). GitHub's research shows these sections move the correctness needle. Keep each to 2–5 lines. Under 150 lines total. If you find yourself exceeding that, you are writing documentation for humans, not instructions for machines.
Codex enforces a 32 KiB default size limit and silently truncates beyond it. Place your highest-priority instructions — the ones an agent absolutely must not miss — near the top of the file. For monorepos, use subdirectory-level AGENTS.md files to scope instructions to specific packages rather than stuffing everything into one root file. Test your file by checking character count: 32 KiB is approximately 32,768 characters. Most well-scoped files land well under 10,000 characters, which keeps them safe across all major tools.
Add an AGENTS.md review step to your PR template for changes that affect project structure, conventions, or tooling. For teams using multiple AI coding tools — Copilot plus Claude Code is the most common combination per JetBrains January 2026 data — use AGENTS.md as the shared layer and maintain tool-specific files (CLAUDE.md, copilot-instructions.md) only for behavior that genuinely differs between tools. When a convention changes in the codebase, update AGENTS.md in the same commit. Stale instructions cause confident wrong behavior, which is worse than no instructions at all.
Frequently Asked Questions
How does AGENTS.md work with AI coding assistants like Claude Code and Copilot?
AGENTS.md is read at the start of an agent session as a project-level context layer, before any task is executed. The AI coding assistant parses the file to understand project structure, conventions, and constraints. Claude Code reads it alongside its native CLAUDE.md file; GitHub Copilot reads it natively as of August 2025. The file's placement at the repository root determines its project-wide scope, while subdirectory-level AGENTS.md files can override or extend root instructions for specific modules — useful for monorepos where different packages have different conventions.
What is the difference between AGENTS.md and CLAUDE.md?
AGENTS.md is a cross-tool standard designed to be read by any AI coding agent — Codex, Copilot, Cursor, Claude Code, and 25+ others. CLAUDE.md is Claude-specific and can contain Claude-native syntax, memory management directives, and tool permission settings that other agents would not understand or would interpret incorrectly. Teams using Claude Code alongside other tools typically maintain both: AGENTS.md for shared project conventions that should apply to every agent, and CLAUDE.md only for behavior specific to Claude sessions. Using AGENTS.md alone gives the widest cross-tool coverage; using only CLAUDE.md means non-Claude agents miss your conventions entirely.
What should I put in my AGENTS.md file to improve AI agent performance?
GitHub's analysis of 2,500+ repositories identified four highest-impact sections: project overview, directory structure with notes on what to avoid, coding conventions (language version, style rules, test commands), and procedural workflows — specific, actionable instructions like which commands to run, which files are off-limits, and what patterns CI enforces. Files between 100 and 150 lines with focused procedural instructions outperformed both shorter files (insufficient context) and longer files (context noise). Procedural workflow sections specifically showed 25% higher correctness and 20% higher completeness compared to abstract project descriptions. Do not auto-generate the file — Augment Code's research shows this reduces task success in the majority of tested settings.
Is AGENTS.md worth creating for solo developers or small teams?
For developers using multiple AI coding tools on any project with consistent conventions, yes. The 28.64% runtime reduction and 16.58% token savings documented in arXiv research apply regardless of team size. The caveat is quality: a neglected or auto-generated file can increase inference costs by over 20% without improving results, per a separate arXiv study. Solo developers with a simple, single-tool setup may find their existing tool-specific config — .cursorrules or CLAUDE.md — sufficient. The strongest case for AGENTS.md is cross-tool consistency: if you use two or more AI coding agents on the same project, the maintenance math clearly favors a single shared file.
Why is AGENTS.md important for AI agents in enterprise workflows?
AGENTS.md represents a broader architectural principle: AI agents need explicit, machine-readable context to function reliably in production. Without structured project context, agents burn tokens on inference that should be resolved by stated conventions, violate project constraints they had no way to know, and require retry logic that inflates costs. As of Q1 2026, 80% of enterprises have at least one production AI agent — up from 33% in 2024 — and the challenge of giving agents reliable project context applies well beyond code. AGENTS.md is the coding ecosystem's answer to a universal problem: how to make repositories and systems legible to machines that have no memory between sessions.
Disclaimer: This article is editorial commentary based on publicly available information and does not constitute professional or technical advice. The views expressed are the author's analytical interpretation of published research and reporting. Research based on publicly available sources current as of July 6, 2026.