Understanding AGENTS.md: The Universal Standard for AI Coding Agents

By Admin

Agents

Modern AI models have a crucial limitation — context window size. This is the amount of information from an external source that a model can hold in its "working memory" at any given time, typically capped at a few million tokens.

At first glance, millions of tokens seems like a massive number. But there is a major CATCH.

The model does not remember what you asked it in previous messages. Every new prompt in an AI chat is perceived as entirely new — as if it is seeing you for the first time. Therefore, to ensure the model always knows what it has done and what it plans to do next, it re-reads the entire conversation history every single time: all your prompts, all its responses, and the full context — right from the beginning of the session.

For a simple chat, this might not be a problem. But in software development, input data volumes grow exponentially. Alongside your text messages, the model receives huge amounts of code: files it reads, diffs it generates, terminal execution results, linter outputs, and test logs. This snowballs rapidly — the more input context provided, the more money is spent processing every single request, leaving less space for genuinely useful context.

At a certain point, AI coding agent developers realized two key architectural principles:

Filter Context — Only essential information should reach the model, not the entire repository. Reduce input and output tokens (including reasoning traces).
Provide a "Cheat Sheet" — A concise, structured file detailing rules and constraints for the specific project, so the agent doesn't waste expensive context window space "discovering" which package manager you use or which folders are off-limits.

These approaches solve another core problem: AI agents don't know your codebase requirements without extra investigation. They don't know your team uses pnpm instead of npm. They don't know that src/generated/ is a "sacred cow" generated by the CI pipeline. They don't know that all API responses are wrapped in Result<T, E> rather than thrown via try/catch. They are geniuses in general, but blind to your repository's local context.

This is precisely why AGENTS.md was created — a compact Markdown file that tells AI agents the rules of the game in your project. It consumes minimal space in the context window while providing the model with maximum actionable guidance.

Background: The Tool Fragmentation Problem

For a long time, every vendor solved the context problem in their own proprietary way. Cursor introduced .cursorrules. Anthropic created CLAUDE.md. GitHub built .github/copilot-instructions.md. Windsurf had .windsurfrules.

The result? A typical repository looked like this:

text
1my-project/
2├── .cursorrules              # Rules for Cursor
3├── CLAUDE.md                 # Rules for Claude Code
4├── .github/
5│   └── copilot-instructions.md   # Rules for GitHub Copilot
6├── .windsurfrules            # Rules for Windsurf
7├── .continue/
8│   └── config.json           # Rules for Continue
9└── README.md                 # And a README for humans!

Five different files with virtually identical content that drifted apart within weeks. You update a rule in .cursorrules, forget about CLAUDE.md, and the Anthropic agent keeps writing code in the old style. Classic version drift — not between code and tests, but between instructions for different AI agents.

It's like maintaining five separate onboarding cheat sheets for five new hires, each with slightly different rules. Chaos is guaranteed.

To stop this fragmentation, developers united around a single, vendor-agnostic standard — AGENTS.md, governed by the Agentic AI Foundation (AAIF) under the auspices of the Linux Foundation. Foundation founding members include AWS, Anthropic, Google, Microsoft, OpenAI, and Block.

What is AGENTS.md? Human README vs. Machine README

The concept is elegantly simple. Every project has a README.md — a file that explains to humans how the project is structured, how to run it, and why it exists. AGENTS.md is the exact same thing, but tailored for AI Agents.

mermaid
1flowchart TD
2    Repo["Code Repository"]
3    Repo --> README["README.md<br/>(For Humans)"]
4    Repo --> AGENTS["AGENTS.md<br/>(For AI Agents)"]
5
6    README --> R1["Why does this project exist?"]
7    README --> R2["How to install and run it?"]
8    README --> R3["Who is the author and what is the license?"]
9
10    AGENTS --> A1["Which files must NEVER be touched?"]
11    AGENTS --> A2["What commands build and test the project?"]
12    AGENTS --> A3["What are our coding conventions?"]

The difference in target audience dictates everything:

	`README.md`	`AGENTS.md`
Reader	Human Developer	AI Agent (LLM)
Tone	Welcoming, descriptive	Imperative, strict
Goal	Understand and get inspired	Don't break things and execute correctly
Example	"We use React 19 and TanStack Router for navigation"	"ALWAYS use `pnpm`. NEVER use `npm` or `yarn`"
Optimization	Visual scannability & readability	Token budget & context efficiency

Notice the tone shift: while a README uses a welcoming, descriptive tone ("We use..."), AGENTS.md uses strict imperatives ("ALWAYS...", "NEVER..."). An AI agent is not a human colleague who needs gentle framing. It is a high-performance automaton that requires precise commands, not inspiration.

Who Supports AGENTS.md?

Short answer: virtually everyone. As of 2026, the AGENTS.md standard is natively read by:

mermaid
1flowchart LR
2    subgraph Spec["Single Source of Truth"]
3        AGMD["📄 AGENTS.md"]
4    end
5
6    subgraph Agents["AI Agents and IDEs"]
7        Cursor["Cursor"]
8        OpenAI["Codex"]
9        Copilot["GitHub Copilot"]
10        ClaudeCode["Claude Code"]
11        Aider["Aider"]
12        OpenHands["OpenHands"]
13        Windsurf["Windsurf / Devin"]
14        GeminiCLI["Gemini CLI / Antigravity"]
15        Goose["Goose"]
16    end
17
18    AGMD ==> Cursor
19    AGMD ==> OpenAI
20    AGMD ==> Copilot
21    AGMD ==> ClaudeCode
22    AGMD ==> Aider
23    AGMD ==> OpenHands
24    AGMD ==> Windsurf
25    AGMD ==> GeminiCLI
26    AGMD ==> Goose

OpenAI Codex — automatically reads AGENTS.md at session start. Supports multi-level hierarchies (from project root to current directory) and a global file ~/.codex/AGENTS.md for personal rules applied across all repositories.
Cursor — automatically loads AGENTS.md from root and subdirectories, injecting it into every model request. Also supports its proprietary .cursor/rules/*.mdc format for granular control.
GitHub Copilot Coding Agent — supports AGENTS.md as a primary source of project rules.
Claude Code — reads both AGENTS.md and CLAUDE.md, prioritizing AGENTS.md when both exist.
Aider — loads AGENTS.md as project conventions upon startup.
OpenHands / SWE-bench agents — scan AGENTS.md to establish baseline project context.
Gemini CLI / Antigravity — accept AGENTS.md as context rules.
Goose (Block) — reads AGENTS.md as one of the three core AAIF projects.
Zed / JetBrains Junie / VS Code / Warp / Devin / Windsurf / Amp / RooCode — and dozens of others.

This means one single file — AGENTS.md — works seamlessly across all your tools. No more fragmentation.

💡 Backward Compatibility Tip: If an older tool version still expects its vendor-specific file, create a symbolic link:
bash
1ln -s AGENTS.md CLAUDE.md
2ln -s AGENTS.md .cursorrules
One single source of truth, zero duplication.

Monorepo Hierarchy: "Closest File Wins"

In large monorepos, a single AGENTS.md at the root is often insufficient. The frontend team uses React with Vitest, the backend team uses Go with golangci-lint, and the ML team uses Python with pytest. They have different coding standards, build commands, and off-limits directories.

AGENTS.md handles this via Hierarchical Resolution using the "closest file wins" rule:

text
1my-monorepo/
2├── AGENTS.md                 ← Global team rules
3├── apps/
4│   ├── web/
5│   │   ├── AGENTS.md         ← Rules for React / Next.js frontend
6│   │   └── src/
7│   └── api/
8│       ├── AGENTS.md         ← Rules for Go / gRPC backend
9│       └── main.go
10├── packages/
11│   └── shared/
12│       └── AGENTS.md         ← Rules for shared library

When an agent edits apps/api/main.go, it:

Reads the root AGENTS.md (baseline rules for everyone).
Reads apps/api/AGENTS.md — extending or overriding global rules with local ones.

This operates like CSS specificity: the more specific local rule always overrides the general one.

Anatomy of a Great AGENTS.md: 6 Essential Sections

The standard intentionally chose pure Markdown — no YAML metadata, JSON schemas, or custom syntax. Just plain Markdown. This makes onboarding effortless: if you can write a README, you can write an AGENTS.md.

Based on an analysis of thousands of repositories, 6 core sections make an AGENTS.md truly effective:

1. 🏗️ Architecture Overview

Briefly (1–2 paragraphs!) explain how the codebase is structured. Crucial for monorepos.

markdown
1# Architecture
2TypeScript monorepo.
3- `packages/core` — core business logic (no DOM dependencies).
4- `apps/web` — Next.js 15 App Router (UI layer only).
5- `apps/api` — Express + tRPC (API Gateway).

2. 🔧 Tech Stack & Tooling

State tools explicitly. The agent should never guess which package manager to use.

markdown
1# Stack & Tooling
2- Package Manager: ONLY `pnpm`. DO NOT use `npm` or `yarn`.
3- Formatter: Biome (NOT Prettier, NOT ESLint).
4- State Management: Zustand for client state, TanStack Query for server state.

3. ⚡ Development Commands

Provide exact CLI commands — recipes that the agent can execute directly in the terminal.

markdown
1# Commands
2- Install: `pnpm install`
3- Build: `pnpm build`
4- Run Tests: `pnpm test`
5- Single Test: `pnpm test -- path/to/file.test.ts`
6- Linting: `pnpm lint && pnpm format:check`

4. 📐 Coding Standards

Concrete code snippets (Good vs. Bad) work far better than abstract descriptions.

markdown
1# Standards
2All API handlers return `Result<T, E>` instead of throwing exceptions.
3
4❌ BAD:
5try { await fetchUser(); } catch (e) { console.log(e); }
6
7✅ GOOD:
8const result = await fetchUser();
9if (!result.ok) { logger.error('Fetch failed', { err: result.error }); return null; }

5. 🚫 Red Lines (Constraints)

Actions that the agent is strictly forbidden from taking. This is arguably the most critical section.

markdown
1# Red Lines
2- NEVER edit files in `src/generated/`.
3- NEVER delete existing unit tests.
4- DO NOT add new npm dependencies without explicit user permission.
5- DO NOT modify CI/CD pipeline configuration files.

6. ✅ Verification Steps

How the agent must verify its work before declaring a task completed.

markdown
1# Verification
2Before completing any task, you MUST:
31. Run `pnpm typecheck` — zero TypeScript errors.
42. Run `pnpm test` for affected modules — all tests passing.
53. Run `pnpm lint` — zero linter violations.

Best Practices: How to Write AGENTS.md That Actually Works

Tip 1: Respect the Context Budget

The most common mistake is dumping your team's entire wiki into AGENTS.md: a 50-page style guide, complete API documentation, and three years of architectural decision records.

The ideal size is between 50 and 200 lines.

Why is this critical? Every line of AGENTS.md enters every single request to the LLM. A 2,000-line file isn't just a waste of token costs. It actively degrades generation quality: the model suffers from attention dilution and begins ignoring both your instructions and the actual code.

It's equivalent to handing a new employee a 200-page manual on day one and expecting them to memorize every word. Spoiler: they won't.

Tip 2: Show, Don't Just Tell

AI models absorb concrete code examples much better than abstract prose.

❌ Doesn't work well:

"Always write clean code with proper error handling and use custom React hooks."

This is too vague. The model cannot infer what your specific project considers "clean code."

✅ Works effectively:

Provide two code blocks labeled ❌ BAD and ✅ GOOD. The model will reliably follow the good pattern.

Tip 3: Use Imperative Language, Not Suggestions

An AI agent is not a colleague needing polite diplomatic phrasing. Vague terms ("preferably", "if possible", "would be nice to") are your enemy.

❌ Vague	✅ Imperative
"It would be nice to use TypeScript strict mode"	"Use TypeScript strict mode. Always."
"If possible, write unit tests"	"Create a unit test for every new function"
"Preferably don't touch generated files"	"NEVER edit files in `src/generated/`"

Tip 4: Document Only What the Model Doesn't Already Know

There is no need to tell the agent "Use meaningful variable names" or "Use async/await in JavaScript." Modern models (Claude Opus, Gemini 3.6 Flash, GPT-5.6) already know standard language best practices.

Document ONLY what is unique to your repository: custom conventions, local constraints, and project-specific CLI workflows.

Anti-Patterns: How NOT to Write AGENTS.md

mermaid
1flowchart TD
2    Anti["AGENTS.md Anti-Patterns"]
3    Anti --> B["Prompt Bloat<br/>(2000+ lines)"]
4    Anti --> M["README Confusion<br/>(Marketing + HR content)"]
5    Anti --> S["Exposing Secrets<br/>(API keys committed to Git)"]
6    Anti --> V["Vague Rules<br/>('write high-quality code')"]
7    Anti --> St["Stale Instructions<br/>(outdated rules)"]

❌ Prompt Bloat

Pasting a 500-line eslint.config.js, a 30-page style guide, and a 3-year-old RFC into AGENTS.md. The model drowns in text and ignores your instructions.

❌ README Confusion

Adding instructions like "To install Homebrew on macOS..." or links to HR policies. The AI agent is not undergoing employee onboarding. Every extra line wastes your context budget.

❌ Exposing Secrets

Adding API keys, database credentials, or Slack tokens to AGENTS.md. Since AGENTS.md is committed to Git, your secrets are now permanently exposed in repository history.

❌ Conflicting Hierarchical Rules

The root AGENTS.md says "All tests use Jest", while apps/web/AGENTS.md says "Use Vitest". Without explicit clarification that the local rule overrides the global one, the agent hallucinates a broken hybrid of Jest and Vitest. (Best practice: explicitly state "This directory uses Vitest").

❌ Stale Instructions

The project migrated from REST to gRPC two months ago, but AGENTS.md still reads "All endpoints are RESTful, use Express Router." The agent stubbornly generates obsolete Express handlers.

Golden Rule: Treat AGENTS.md as a living document. After every major refactoring, verify that your AI instructions remain up to date.

Generating AGENTS.md: How to Get Started Fast

In real-world development, there are two primary ways to create an initial AGENTS.md:

1. Direct LLM Prompts (Most Popular Approach)

The simplest and most effective method is asking your AI tool (Cursor, Claude Code, Gemini CLI, or ChatGPT) to generate a draft based on your repository:

AI Prompt: "Analyze my project structure, dependencies, build/test scripts, and generate a concise draft AGENTS.md following the AAIF standard. Include commands for building, testing, linting, and key project conventions."

2. Open-Source CLI Generators

agentseed — a lightweight open-source CLI tool that performs static analysis of your project to generate a baseline AGENTS.md with auto-detected build and test commands.
```
bash
1npx agentseed init
```

⚠️ Important: Generators and LLM prompts are merely starting points. An auto-generated file must always be reviewed and refined manually: remove unnecessary noise and add your team's real "red lines."

Conclusion: AGENTS.md Checklist

AGENTS.md is not just another bureaucratic file in your repository. It is a contract between you and your AI agent. It determines whether the agent produces production-ready code aligned with your team's style — or generates technically correct but completely alien code that you'll have to rewrite manually while burning thousands of tokens.

Before committing, verify:

Size — Under 200 lines (if larger, split into hierarchical sub-files).
Tone — Imperative ("Always...", "NEVER..."), avoiding "preferably" or "if possible".
Commands — Exact CLI recipes for building, testing, and linting.
Red Lines — Explicitly listed files and folders the agent must never touch.
Examples — Concrete ❌ BAD / ✅ GOOD code blocks for key patterns.
Security — Zero API keys, passwords, or confidential data.
Specificity — Omitted standard rules that LLMs already know by default.
Accuracy — Instructions reflect the current state of the codebase.

Maintaining an AGENTS.md has a valuable byproduct: when you sit down to write clear rules for an AI agent, you simultaneously formalize your team's engineering standards. Those unwritten conventions that lived only in the heads of senior devs and were passed down verbally during code reviews suddenly materialize in a single document that anyone can read, discuss, and update.

And that is perhaps the greatest value of AGENTS.md — it makes the invisible visible. Not just for machines, but for humans too.

Resources and Useful Links

Resource	Link
🌐 AGENTS.md Official Site	agents.md
📦 Standard GitHub Repository	github.com/agentsmd/agents.md
🏛️ Agentic AI Foundation (AAIF)	aaif.io
🔧 agentseed Generator (CLI)	github.com/avinshe/agentseed
📖 OpenAI Platform Docs	platform.openai.com/docs
📖 Cursor AI Rules Docs	cursor.com
📖 Aider Conventions Docs	aider.chat/docs/usage/conventions
📖 Zed AI Docs	zed.dev/docs/assistant
📖 GitHub Copilot Coding Agent	gh.io/coding-agent-docs
📖 Gemini CLI Configuration	github.com/google-gemini/gemini-cli
📖 Goose (Block / AAIF)	github.com/aaif-goose/goose
🔍 Search Repositories using AGENTS.md	GitHub Search: AGENTS.md