AGENTS.md Explained: The Standard Every AI Coding Agent

AGENTS.md is the one Markdown file, sitting quietly at the root of a repository, that has become the closest thing the AI industry has to a universal onboarding doc for AI coding agents — read natively by Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Google Jules, Gemini CLI, and 20+ other tools. It is now stewarded by the Agentic AI Foundation under the Linux Foundation and sits in more than 60,000 repositories worldwide.

Every AI agent starts each session blind — it doesn't know your team uses pnpm instead of npm, that your API client never throws raw exceptions, or that the /vendor folder must never be touched. The result: agents quietly reinvent your architecture, break your conventions, and generate PRs that bounce back in code review — the exact "individual-agent productivity stops compounding" wall that engineering leads keep hitting in 2026. AGENTS.md is the fix the industry converged on. 🛡️

Here's the deeper problem it solves, in plain terms. A large language model is trained on an enormous, general slice of the internet's code. That gives it broad competence — it knows Python, Java, Terraform, and a hundred frameworks — but it knows nothing specific about your repository the moment a session starts. It doesn't know your team migrated off Redux six months ago, that your linter enforces 2-space indentation instead of 4, or that a "quick fix" to the billing service actually requires a finance sign-off because of SOX compliance. Every one of those facts either has to be re-explained by a human in the prompt every single time (expensive, easy to forget, inconsistent across engineers) or written once, checked into version control, and automatically loaded by the agent before it writes a single line — which is exactly what AGENTS.md does. It converts tribal knowledge that used to live in Slack threads, onboarding docs, and one senior engineer's memory into a structured, machine-readable, git-tracked artifact that travels with the code itself.

📑 In This Post

• Quick Comparison
• 1. What Is AGENTS.md?
• 2. A Real Enterprise-Grade Example, Line by Line
• 3. The Anatomy of a Platinum-Grade AGENTS.md
• 4. Monorepos: Nested AGENTS.md & Precedence
• 5. AGENTS.md vs CLAUDE.md vs .cursorrules
• 6. Enterprise Rollout Playbook
• 7. Common Mistakes That Kill Its Value
• FAQ
• References
• Summary

🔀 Quick Comparison

File	Who Reads It	Scope
AGENTS.md	Codex, Cursor, Copilot, Jules, Gemini CLI, Aider, Windsurf, Zed, Devin, 20+ tools	Cross-vendor, open standard
CLAUDE.md	Claude Code only	Anthropic-specific, extra features (imports, hooks)
.cursorrules / .cursor/rules/	Cursor only	Vendor-specific, being phased toward AGENTS.md support
.github/copilot-instructions.md	GitHub Copilot only	Vendor-specific; Copilot now also reads AGENTS.md natively

📄 1. What Is AGENTS.md?

AGENTS.md is a plain-Markdown file placed at the root of a repository — no special syntax, no required schema, no proprietary tags. Think of it as a README, but written for the AI teammate instead of the human one. A README tells a new human hire "here's what this project does and how to get started." AGENTS.md tells an AI agent the things it genuinely cannot infer from reading the code alone: exact build commands with flags, which test suite to run before finishing a task, which directories are off-limits, and which conventions differ from the language's defaults.

Three facts that explain why it went from "one company's idea" to "industry standard" so fast:

• 🏛️ Vendor-neutral governance — it emerged from collaboration across OpenAI Codex, Cursor, Google Jules, Amp, and Factory, and is now formally stewarded by the Agentic AI Foundation under the Linux Foundation, not owned by any single AI vendor.
• 📈 Rapid, measurable adoption — over 60,000 public repositories now ship one, and GitHub Copilot added native support for it in August 2025, joining nearly every major coding-agent runtime.
• 🎯 It solves a real, expensive problem — without it, engineering teams were maintaining a separate instruction file per tool (.cursorrules, CLAUDE.md, .github/copilot-instructions.md) and manually keeping all of them in sync. AGENTS.md collapses that into one file most tools read directly.

For a beginner, the mental model is simple: your codebase is the "what," AGENTS.md is the "how we work here." For a senior architect, the more precise framing is that it's a standardized, version-controlled interface contract between human intent and agent execution — the same instructions travel with the repo regardless of which AI tool a given engineer prefers.

📜 Where It Actually Came From

It's worth understanding the origin story, because it explains why the format is so deliberately unopinionated. AGENTS.md wasn't handed down by a single company as a proprietary feature — it grew out of independent, converging experiments at OpenAI (for Codex), Cursor, Google (for Jules), Amp, and Factory, all of whom had separately invented their own "give the agent project context" file and discovered they were solving the identical problem in slightly incompatible ways. Rather than let the ecosystem fragment into a dozen competing formats — the exact chaos that plagued CSS vendor prefixes or early JavaScript module systems — these teams converged on one shared spec. That convergence is also why governance was handed to the Agentic AI Foundation under the Linux Foundation rather than kept by any single vendor: it guarantees no single company can unilaterally change the format in a way that breaks everyone else's tooling, which is precisely the kind of neutrality a Fortune 500 procurement or security team wants to see before standardizing on something org-wide.

⚙️ What Actually Happens at Runtime

It helps to demystify the mechanics, because "the agent reads a file" undersells what's actually happening. When you start a task, most agent runtimes perform a specific sequence before your prompt is even processed:

1. Discovery — the agent walks the directory tree from the file(s) it's about to touch, upward toward the repository root, looking for every AGENTS.md file along that path.
2. Injection — the contents of the matching file(s) are prepended into the model's system prompt or context window, before your actual instruction, so the agent is "primed" with project rules before it reasons about your request.
3. Precedence resolution — if multiple AGENTS.md files apply (e.g. a root file plus a nested package file), the more specific, closer file takes priority on any conflicting instruction, while non-conflicting rules from both are typically retained.
4. Execution & self-check — for tools like Codex, once the agent believes it has finished the task, it re-reads the Testing Instructions section and actually attempts to run the listed commands, treating failures as blocking rather than optional.

The practical implication: AGENTS.md isn't documentation the agent might glance at — it's loaded context that directly shapes every token the model generates for that session, which is exactly why sloppy, bloated, or stale content in it doesn't just fail to help — it actively degrades output quality, since every irrelevant line still consumes attention and context budget the model could have spent reasoning about your actual request.

🏢 2. A Real Enterprise-Grade Example, Line by Line

Rather than a Java monorepo example that only makes sense once you already know Gradle, let's build this one from a small Python FastAPI project — simple enough to read in one pass, but structured using the exact section set that the official agents.md specification and its most-cited real-world examples converge on: Overview, Dev Environment, Build & Test Commands, Code Style, Testing Instructions, Security Considerations (a section many first-draft AGENTS.md files skip entirely), Commit Conventions, and Constraints. Once this shape feels natural, scaling it to a larger Java, Go, or TypeScript codebase is just a matter of swapping the commands.

# AGENTS.md

## Project Overview
Python 3.12 REST API for a task tracker. FastAPI + SQLite via SQLAlchemy.
Dependencies managed with `uv`, not pip directly.

## Dev Environment Setup
- Install dependencies: `uv sync`
- Copy `.env.example` to `.env` before running; never commit the real `.env`.
- Start the dev server: `uv run fastapi dev app/main.py`

## Build & Test Commands
- Run the full test suite: `uv run pytest`
- Run one test file: `uv run pytest tests/test_tasks.py`
- Run with coverage: `uv run pytest --cov=app`

## Code Style
- Format with `ruff format .` and lint with `ruff check . --fix` before finishing any task.
- Type hints are required on every function signature; checked with `mypy app/`.
- Use Pydantic models for request/response bodies — never return a raw dict from a route.

## Testing Instructions
- Every new route needs at least one passing test under `tests/`.
- Do not mark a failing test `@pytest.mark.skip` to force the suite green — fix it or ask first.
- Run `uv run pytest` before declaring any task complete; a red suite is blocking, not a warning.

## Security Considerations
- Never log or print the contents of the `Authorization` header.
- Database credentials come only from environment variables — never hardcode them, even in tests.
- Any change to `app/auth.py` requires a human review before merging, regardless of size.

## Commit Conventions
- Branch names: `feature/<short-description>` or `fix/<short-description>`.
- Commit messages: imperative mood, under 72 characters — e.g. `Add pagination to /tasks route`.
- Reference the issue number in the PR description, not in the commit message.

## Constraints (Always / Ask First / Never)
- Always: run `ruff check` and `pytest` before finishing a task.
- Ask first: before adding a new third-party dependency to `pyproject.toml`.
- Never: hand-edit files under `/migrations/` — generate them with `alembic revision --autogenerate`.

Now let's walk through why each block exists — not just what it says, but the reasoning behind it and what breaks in production if it's missing:

## Project Overview

What it does: States language, framework, and dependency manager in one line. Why it matters: An LLM has seen pip, poetry, and uv projects in roughly equal measure in training — without a pin, it may reach for pip install out of habit. What breaks without it: A wasted tool call discovering the actual package manager, or a dependency installed with the wrong tool entirely.

## Dev Environment Setup

What it does: Exact, copy-paste-able setup commands, including the easy-to-miss step of creating a local .env. Why it matters: A missing .env is one of the most common reasons a "should just work" project fails to start. What breaks without it: The agent runs the server, hits a missing environment variable, and burns a cycle debugging what looks like a code problem but is a setup problem.

## Build & Test Commands

What it does: The precise test invocation, including how to run just one file. Why it matters: "Run the tests" is ambiguous the moment a project has more than one test config. What breaks without it: The agent guesses python -m pytest, which may miss the project's actual pytest config or coverage settings.

## Code Style

What it does: Concrete, checkable rules — a required tool, a required pattern — not a philosophy statement. Why it matters: "Return a raw dict" is a completely idiomatic FastAPI shortcut the model has seen thousands of times; nothing about the code itself signals it's forbidden here. What breaks without it: Inconsistent response shapes across routes that a human reviewer then has to catch and normalize by hand.

## Testing Instructions

What it does: Defines what counts as "tested" and bans the shortcut of skipping a failing test to force green. Why it matters: Agents are implicitly optimizing for "the check passed" — without a rule against it, skipping is the path of least resistance. What breaks without it: A silently skipped test ships in a merged PR, and a real regression goes undetected.

## Security Considerations

What it does: Names the specific things that must never end up in a log, a commit, or a test file. Why it matters: This is the section most beginner AGENTS.md files skip — and the one with the highest downside if skipped. An agent debugging an auth issue will reach for a print() statement unless told not to. What breaks without it: A credential or auth header ends up in a log file, a test fixture, or — worse — a commit.

## Commit Conventions

What it does: Branch naming, commit message format, and where the issue number actually belongs. Why it matters: A human absorbs these conventions from team culture over weeks; an agent has no exposure to that culture unless it's written down. What breaks without it: Inconsistent branch names and commit messages that make the git history harder to search and audit later.

## Constraints (Always / Ask First / Never)

What it does: A three-tier permission system for exactly the actions that carry real risk if done wrong. Why it matters: This is the highest-leverage section in the whole file — it's the difference between an agent that hand-edits a generated migration file (silently breaking schema history) and one that regenerates it correctly. What breaks without it: The agent "helpfully" does something irreversible because nothing told it that directory was special.

🧬 3. The Anatomy of a Platinum-Grade AGENTS.md

Research across thousands of production repositories converges on a consistent finding: more is not better. Files over roughly 150 lines show diminishing returns and can measurably increase inference cost without improving task success — every extra line competes for the agent's limited attention budget, and OpenAI's Codex silently truncates anything past a 32 KiB hard limit. The highest-performing files are short, high-signal, and contain zero information the agent could already get from reading the code or the README.

1. Project Overview — language, framework, and versions, in one or two lines. No prose paragraphs. The test here is precision, not completeness: "Next.js 15 App Router, React 19, TypeScript 5.4, Bun" gives the model an exact syntax target; "a modern web application built with React" gives it nothing it couldn't already guess, and guessing is where version-mismatched code comes from.
2. Build & Test Commands — exact executable commands with flags, never "use the usual build tool." This section exists because "usual" is doing enormous, invisible work in that sentence — usual to whom? A model trained broadly has seen dozens of "usual" ways to build a Java project. Writing ./gradlew :temporal-sdk:test instead of "run the tests" removes every possible ambiguity in one line.
3. Code Style — snippets and concrete rules, not general philosophy paragraphs. A rule like "write clean, maintainable code" is unfalsifiable — the model already believes it's doing that. A rule like "use Preconditions.checkArgument, not manual if/throw blocks" is checkable, specific, and immediately actionable.
4. Security Considerations — the specific secrets, files, and directories the agent must never expose, log, or touch. This section earns its place separately from Constraints because it's about what must never leak, not just what must never change — an agent can follow every "never edit this file" rule perfectly and still paste a credential into a debug log unless this is spelled out on its own.
5. Boundaries / Constraints — the Always / Ask First / Never three-tier structure covered in the walkthrough above. This is arguably the most consequential section in the entire file because it's the one section that directly manages risk rather than just code quality — it's where an organization encodes what it is and isn't comfortable letting an autonomous process do unsupervised.
6. Project Structure — a flat map of key directories with one-line purpose notes. Worth a caveat here: research on agent navigation behavior has found that directory maps don't meaningfully speed up an agent finding the right file during implementation work — agents are generally good at exploring a repo on their own. Where this section earns its place instead is orientation for higher-level work: a new session doing architecture review, writing a spec, or triaging an incident benefits from a map; an agent about to edit one specific file mostly doesn't need it. Include it for the former use case, not as a substitute for a well-organized repo.
7. Commit Conventions / Git Workflow — branch, commit, and PR conventions. Small in line-count, outsized in impact: this is the section that keeps an agent's commits traceable, auditable, and mergeable without a human having to manually rewrite the commit message or branch name after the fact.

💡 The Redundancy Trap:

A recurring finding across 2,500+ audited repositories: auto-generated AGENTS.md files that simply repeat README content actually reduced task success compared to having no file at all. The theory holds up in practice — every line in the file is competing for the agent's limited attention, so a line that says "this project uses React" (which the agent can see instantly from package.json) is worse than no line, because it dilutes the signal of the lines that actually matter. Write only what the agent cannot infer from the code itself.

🗂️ 4. Monorepos: Nested AGENTS.md & Precedence

Enterprise codebases are rarely a single flat project — they're monorepos with dozens of packages, each with its own conventions. AGENTS.md supports this natively: you can place a separate AGENTS.md inside every subdirectory, and agents walk the tree hierarchically, using the nearest AGENTS.md to the file actually being edited. This is precisely why OpenAI's own Codex repository ships 88 separate AGENTS.md files instead of one giant one — each package gets tailored, low-noise instructions instead of a bloated root file trying to cover every case.

✅ Practical Example:

A large e-commerce platform has one monorepo containing /packages/web (Next.js frontend), /packages/api (Node.js backend), and /packages/infra (Terraform). The root AGENTS.md holds only truly global rules — "always run the linked ticket through ./scripts/link-check.sh before opening a PR." Each package then adds its own file: /packages/web/AGENTS.md says "use Tailwind utility classes only, never inline styles," while /packages/infra/AGENTS.md says "never run terraform apply directly — always output a plan for human review." An agent editing a Terraform file automatically picks up the stricter infra-specific rule, without the frontend package's instructions ever cluttering its context. OpenAI's own Codex extends this further with an AGENTS.override.md variant for cases needing a hard override rather than an additive nested file. 🏗️

🎯 Use nested AGENTS.md files when: your monorepo has packages with genuinely different tech stacks, risk profiles, or conventions — don't create nested files just to split up one file that would have fit fine at the root.

⚖️ 5. AGENTS.md vs CLAUDE.md vs .cursorrules

A question every beginner asks once they've seen a few repos: if AGENTS.md is universal, why does Claude Code specifically read CLAUDE.md instead? The honest, documented answer: Claude Code reads CLAUDE.md, not AGENTS.md — Anthropic's file format predates the cross-vendor standard and includes Claude Code–specific features (like @import file references and hook integration) that a vendor-neutral spec can't assume every tool supports.

The pragmatic, enterprise-recommended approach architects actually use:

• 🔹 If your team standardizes on one tool — use that tool's native format directly.
• 🔹 If your team uses multiple tools — put shared, tool-agnostic instructions in AGENTS.md, and keep only genuinely tool-specific configuration in the native file (e.g. CLAUDE.md, .cursorrules).
• 🔹 Many teams simply make CLAUDE.md a one-line symlink or import pointing at AGENTS.md, so there's still only one source of truth to maintain.

🏭 6. Rolling AGENTS.md Out Across an Enterprise Org

Writing one good AGENTS.md for one repository is a weekend project. Making it work consistently across an organization with hundreds of repositories, dozens of teams, and multiple AI tool vendors is a genuine engineering-governance problem — and it's where most "we adopted AI agents" initiatives quietly stall. Here's how platform and DevEx teams at larger organizations approach it:

1. Treat it like code, because it is code. AGENTS.md lives in version control, goes through pull requests, and gets code-reviewed — never edited directly on a long-lived branch by whoever happens to notice it's out of date. Many platform teams require a second approver on any AGENTS.md change specifically, since a bad edit here silently degrades every future agent session on that repo, not just the current PR.
2. Assign explicit ownership. Just like a README or a CODEOWNERS file, an AGENTS.md needs a named owner — usually the tech lead of that service — responsible for keeping it accurate as the stack evolves. Without an owner, it drifts within a few months and becomes actively misleading, which, as covered above, is worse than having no file at all.
3. Start from a template, not a blank page. Mature organizations maintain an internal "golden template" AGENTS.md with the Overview / Commands / Style / Boundaries / Git Workflow skeleton pre-filled with org-wide defaults (shared CI commands, shared branch-naming convention, shared security boundaries like "never commit secrets, never modify /infra/prod/"). New services fork that template and fill in only what's genuinely project-specific, which keeps files short and consistent instead of every team reinventing the structure from scratch.
4. Enforce it with CI, not just convention. Some teams add a lightweight CI check that fails a PR if AGENTS.md references a command, file path, or dependency that no longer exists in the repo — catching staleness automatically instead of relying on someone noticing.
5. Measure it. The organizations getting real value track metrics before and after rollout: PR rejection/rework rate on agent-authored code, time-to-first-green-CI on agent PRs, and the ratio of agent-generated code that merges without a convention-related review comment. Anthropic's internal benchmarking on CLAUDE.md / AGENTS.md-style context files found reductions of 40–60% in "wrong-pattern" rewrites — that's the order of magnitude a rollout should be aiming to demonstrate to justify the governance overhead.
6. Revisit it on a cadence, not just when something breaks. A recommended practice from the standard's own guidance is to periodically review each AGENTS.md for content that has since migrated into the toolchain itself (a rule that used to need spelling out but is now enforced by a linter, for instance) — and delete it. The file should only ever contain what the tooling doesn't already guarantee.

✅ Practical Example:

A regulated financial-services company with 400+ internal repositories rolls out AGENTS.md org-wide. The platform team ships a golden template with a mandatory ## Compliance section pre-filled: "Never commit code that logs full credit card numbers; always route PII fields through the tokenize() helper; any change to /services/payments/ requires a second human reviewer regardless of what the agent proposes." Every new service repo starts from that template via a scaffolding CLI, so the compliance boundary exists from day one instead of depending on each team remembering to add it — and a quarterly audit script checks that no AGENTS.md in the org has silently lost that section during an edit. 🏦

🚫 7. Common Mistakes That Kill Its Value

1. Duplicating the README. If a line is already obvious from package.json, pom.xml, or the code itself, it's actively hurting signal-to-noise, not helping. Remember the earlier finding: redundant, README-mirroring AGENTS.md files measured worse task success than having no file at all, because every wasted line dilutes the model's limited attention on the lines that actually carry new information.
2. Writing prose instead of directives. "We try to keep things clean and well-tested" tells an agent nothing actionable — it's a value statement, not an instruction. "Run npm test before finishing; coverage must stay above 80%" is checkable and concrete. A useful self-test while drafting: could a strict, literal-minded reader follow this line exactly and produce the right behavior? If not, rewrite it as a command or rule.
3. Letting it go stale. An AGENTS.md referencing a deprecated build tool, a renamed directory, or a retired testing framework is genuinely worse than no file — the agent doesn't know the instruction is wrong, so it follows it confidently, fails, and burns a debugging cycle diagnosing what looks like a code problem but is actually a documentation problem. This is exactly why the ownership and CI-enforcement practices in the rollout section above matter so much.
4. No boundaries section. Without explicit Always/Ask First/Never rules, an agent has no signal about which of its many "helpful" instincts are actually welcome in this codebase — and coding agents, by design, default toward taking action rather than asking permission unless told otherwise.
5. One giant file for a sprawling monorepo. Forcing every package's conventions into a single root file bloats every agent's context window regardless of which package it's actually touching — a frontend-only task still pays the token cost of reading infrastructure rules it will never use.
6. Treating it as a one-time setup task. Teams that write an excellent AGENTS.md once and never revisit it end up, eighteen months later, with a file that actively works against them — the single most common root cause, according to practitioner postmortems, isn't bad architecture in the agent harness at all; it's stale instructions in the context file itself.

❓ Frequently Asked Questions

What is AGENTS.md and why do Fortune 500 engineering teams use it?

AGENTS.md is an open, vendor-neutral Markdown file at the root of a repository that gives AI coding agents the operational context they can't infer from code alone — build commands, test procedures, style rules, and boundaries. Large engineering organizations adopt it because it replaces a fragmented set of tool-specific instruction files with one standard that every major agent runtime reads, reducing wrong-pattern rewrites and shrinking code review cycles.

Does Claude Code read AGENTS.md?

No — Claude Code reads its own CLAUDE.md file, not AGENTS.md. Teams using both Claude Code and other agent tools typically keep shared instructions in AGENTS.md and use a short CLAUDE.md that imports or points to it, so there remains a single source of truth.

How long should an AGENTS.md file be?

Research across thousands of repositories shows files over roughly 150 lines see diminishing returns and can increase inference cost without improving results. OpenAI Codex also silently truncates content past a 32 KiB technical limit. Aim for short, high-signal files, and split large monorepos into nested, package-specific AGENTS.md files instead of one long root file.

Can I have multiple AGENTS.md files in one repository?

Yes, and this is standard practice in large monorepos — OpenAI's own Codex repository ships 88 of them. Agents read the AGENTS.md nearest to the file they're editing, so each package or service can carry tailored, low-noise instructions instead of one bloated global file.

What's the single biggest mistake teams make with AGENTS.md?

Duplicating information the agent could already get from the code or the README. Studies of auto-generated files that mirrored existing documentation found they actually reduced task success versus having no file, since every redundant line dilutes the agent's limited attention budget on the lines that actually matter.

🔗 References & Further Reading

• AGENTS.md — Official Specification & Site — agents.md
• OpenAI Codex — Official AGENTS.md (88-file monorepo example) — github.com/openai/codex/blob/main/AGENTS.md
• Agents.md Best Practices — GitHub Copilot Adoption Timeline — gist.github.com/0xfauzi

📝 Summary

• AGENTS.md → the open, Linux Foundation–stewarded standard read by Codex, Cursor, Copilot, Jules, Gemini CLI, and 20+ agent runtimes
• It's loaded context, not passive documentation → discovered, injected into the system prompt, and precedence-resolved before the agent reasons about your actual request
• Real enterprise files → short, directive, and organized around Overview → Dev Environment → Build & Test → Code Style → Testing → Security Considerations → Commit Conventions → Constraints, as the pattern shown in the Python example above
• Less is more → files over ~150 lines or duplicating the README measurably reduce agent performance
• Monorepos → use nested AGENTS.md files; the closest one to the edited file always wins
• Claude Code is the one exception → it reads CLAUDE.md natively, not AGENTS.md, so multi-tool teams bridge the two
• Org-wide rollout → treat it as version-controlled, owned, templated, CI-enforced, and periodically audited — not a one-time setup task

Happy building! ✨