Every AI model hits the exact same wall: context window limits. A few million tokens sounds huge on paper. Until you actually start building real software with an AI agent.

Here's the catch that catches most developers off guard: LLMs have zero long-term memory.

Every single prompt in a chat session starts from scratch. The model doesn't "remember" what you worked on ten minutes ago. To maintain continuity, your coding assistant has to re-read the entire conversation history on every single request — every prompt, every snippet, every terminal log, from line one.

In a casual Q&A chat, you barely notice. In active software development, it's a disaster. Along with your instructions, the agent receives massive code dumps: entire files, multi-line diffs, terminal outputs, linter errors, and test suite logs.

Context snowballs fast. The larger the context payload, the more money you burn per query — and the less room remains for actual code generation.

Eventually, the teams building AI coding tools landed on two common-sense principles:

1. Keep context tight — Feed the model only what it strictly needs. Trim the noise, shorten the prompt payload, and cut down unnecessary reasoning cycles.
2. Give the agent a cheat sheet — A concise, structured file detailing your project's rules, stack, and boundaries. That way, the agent doesn't waste thousands of expensive tokens trying to "figure out" whether you use pnpm or npm, or which directories it's forbidden to touch.

Without this cheat sheet, AI agents are essentially coding blind. They don't know your team banned yarn. They don't know that src/generated/ is a CI-built sacred cow that must never be hand-edited. They don't know your API handlers return Result<T, E> instead of throwing exceptions. They're brilliant generalists, but completely clueless about your repository's unwritten rules.

That's why AGENTS.md exists — a lightweight Markdown file that hands AI agents the rules of the game for your codebase. It takes up negligible token space while giving the model maximum guidance.

---

The Backstory: Tearing Down the Vendor Tower of Babel

Before AGENTS.md, every AI tool vendor invented its own isolated solution to the context problem. Cursor gave us .cursorrules. Anthropic pushed CLAUDE.md. GitHub built .github/copilot-instructions.md. Windsurf introduced .windsurfrules.

By 2025, a standard project root looked completely absurd:

textCopy
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 an actual README for humans!

You ended up with five near-identical files that drifted out of sync within a week. You'd update a linting rule in .cursorrules, forget to touch CLAUDE.md, and suddenly Claude Code is generating outdated boilerplate. Classic version drift — except instead of code and tests diverging, your instructions for different AI tools were fighting each other.

It's like writing five separate onboarding guides for five new hires and giving each person slightly different rules. Chaos is guaranteed.

To kill off this fragmentation, major tech players rallied around an open, vendor-agnostic standard: AGENTS.md. Today, it's governed by the Agentic AI Foundation (AAIF) under the Linux Foundation, backed by AWS, Anthropic, Google, Microsoft, OpenAI, Block, and others.

---

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

The core idea is dead simple. Every serious project has a README.md explaining to humans what the project does, how to set it up, and how to contribute. AGENTS.md is the exact same concept, built specifically for AI agents.

Different audiences require fundamentally different writing styles:

	README.md	AGENTS.md
Reader	Human Developer	AI Agent (LLM)
Tone	Welcoming, descriptive	Imperative, strict
Goal	Explain, inspire, onboard	Direct, enforce, prevent mistakes
Example	"We use React 19 and TanStack Router for routing"	"ALWAYS use pnpm. NEVER run npm or yarn"
Optimization	Visual layout & scannability	Token efficiency & prompt budget

Pay close attention to tone. A human README uses polite, welcoming language ("We prefer..."). AGENTS.md uses hard imperatives ("ALWAYS...", "NEVER..."). Your AI agent isn't a colleague whose feelings you might hurt. It's a high-speed execution engine that needs direct orders, not diplomatic suggestions.

---

Ecosystem Support: Who Reads AGENTS.md?

The short answer: almost every major coding tool on the market. Today, native support for AGENTS.md includes:

• OpenAI Codex — automatically picks up AGENTS.md at session boot. Supports nested directory rules and global ~/.codex/AGENTS.md fallbacks for personal defaults across all repos.
• Cursor — parses AGENTS.md across project folders and injects relevant rules into prompt context (alongside .cursor/rules/*.mdc).
• GitHub Copilot Coding Agent — uses AGENTS.md as its primary project rules source.
• Claude Code — parses both AGENTS.md and CLAUDE.md, automatically giving precedence to AGENTS.md when both are present.
• Aider — loads AGENTS.md as project conventions on launch.
• OpenHands / SWE-bench agents — scan AGENTS.md to bootstrap baseline environment context.
• Gemini CLI / Antigravity — natively consumes AGENTS.md for project scoping.
• Goose (Block) — treats AGENTS.md as a core specification.
• Zed / JetBrains Junie / VS Code / Warp / Devin / Windsurf / Amp / RooCode — plus dozens of emerging tools.

One file, zero duplicate configs.

💡 Pro-tip for legacy tooling: If you're stuck on an older tool version expecting vendor-specific filenames, just symlink them:

bashCopy
1ln -s AGENTS.md CLAUDE.md
2ln -s AGENTS.md .cursorrules

One source of truth, zero maintenance overhead.

---

Monorepos: The "Closest File Wins" Rule

In a large monorepo, a single root-level AGENTS.md rarely cuts it. Your frontend team is running React with Vitest; your backend team is on Go with golangci-lint; your data team is writing Python with pytest. They use different test commands, different linters, and different conventions.

AGENTS.md solves this with Hierarchical Resolution using a "closest file wins" approach:

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

When an agent works on apps/api/main.go:

1. It reads the root AGENTS.md for baseline global policies.
2. It reads apps/api/AGENTS.md, applying local overrides and extensions.

Think of it like CSS specificity: specific local rules take priority over broad global ones.

---

Anatomy of a Great AGENTS.md: The 6 Core Sections

The AAIF spec intentionally chose plain Markdown — no YAML frontmatter, no JSON schemas, no weird templating. Just standard Markdown. If you can format a README, you already know how to write an AGENTS.md.

Across thousands of production repositories, effective AGENTS.md files focus on 6 key sections:

1. 🏗️ Architecture Overview

Give a brief (1–2 paragraphs max) breakdown of the codebase layout. Essential for monorepos.

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

2. 🔧 Tech Stack & Tooling

Be unambiguous about your tooling. Never let the agent guess package managers or formatters.

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

3. ⚡ CLI Recipes

Give exact terminal commands — ready-to-run recipes the agent can execute directly.

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

4. 📐 Coding Standards (Show, Don't Tell)

Use concrete code comparisons (❌ BAD vs. ✅ GOOD) instead of vague instructions.

markdownCopy
1# Standards
2All API handlers must return a `Result<T, E>` wrapper. Never throw raw 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 (Off-Limits Boundaries)

Spell out what the agent is strictly forbidden to touch or alter. This is your safety net.

markdownCopy
1# Red Lines
2- NEVER hand-edit files in `src/generated/`.
3- NEVER delete or disable existing tests.
4- DO NOT install new npm packages without user confirmation.
5- DO NOT touch CI/CD pipeline scripts (`.github/workflows/`).

6. ✅ Verification Checklist

Define exact criteria for when a task is considered "done."

markdownCopy
1# Verification
2Before marking any task complete, you MUST execute:
31. `pnpm typecheck` — zero TypeScript errors.
42. `pnpm test` for modified packages — all green.
53. `pnpm lint` — zero linter warnings.

---

Practical Rules for Writing AGENTS.md That Actually Work

Rule 1: Respect the Context Budget

The most common trap developers fall into is dumping their team's entire Notion wiki into AGENTS.md: 50 pages of code style, full API references, and architectural RFCs from 2022.

Aim for 50 to 200 lines.

Why does this matter? Every line in AGENTS.md is loaded into every single LLM request. A 2,000-line file doesn't just burn money on tokens — it actively degrades model performance. The LLM suffers from attention dilution and starts missing both your constraints and the actual code changes.

Think of it like giving a new developer a 300-page manual on their first morning and expecting them to remember every sentence. They won't, and neither will an LLM.

Rule 2: Code Snippets Beat Paragraphs

LLMs parse real code examples infinitely better than long descriptive prose.

❌ Vague instruction:

"Write clean, robust code with good error handling and modular React hooks."

What does "clean" mean in your project? The model has no idea.

✅ Actionable instruction:

Provide side-by-side ❌ BAD and ✅ GOOD code blocks. The agent will mirror the good pattern immediately.

Rule 3: Use Hard Imperatives

Save polite phrasing for code reviews. Vague suggestions ("preferably", "if possible", "we recommend") lead to inconsistent agent output.

❌ Weak & Vague	✅ Hard Imperative
"It would be nice to use TypeScript strict mode"	"Use TypeScript strict mode. Always."
"Try to add unit tests where appropriate"	"Write a unit test for every exported function."
"Preferably avoid modifying generated files"	"NEVER edit files in src/generated/."

Rule 4: Omit Default Knowledge

There's zero reason to instruct an agent to "Use descriptive variable names" or "Use async/await for asynchronous code." Modern LLMs (Claude Opus, Gemini 3.6 Flash, GPT-5.6) already know general language conventions.

Focus exclusively on what is unique to your codebase: non-standard patterns, custom wrappers, and local constraints.

---

Anti-Patterns: Common AGENTS.md Mistakes

❌ Prompt Bloat

Pasting full linter configs, 30-page coding standards, and outdated RFCs into AGENTS.md. The model gets overwhelmed and ignores your actual instructions.

❌ README Confusion

Including OS setup guides ("First, install Homebrew...") or links to HR wiki pages. The AI agent doesn't need developer onboarding — it needs execution constraints.

❌ Committing Secrets

Accidentally leaving staging passwords, Slack webhook tokens, or API keys in AGENTS.md. Since AGENTS.md lives in Git, those secrets are committed forever.

❌ Unresolved Monorepo Conflicts

Root AGENTS.md says "Use Jest", while apps/web/AGENTS.md says "Use Vitest". Without explicit scoping, the agent generates a broken hybrid setup that fails on both runners. (Fix: explicitly state "This directory overrides root test runner to Vitest").

❌ Stale Instructions

You migrated from REST to gRPC two months ago, but AGENTS.md still says "All endpoints must use Express Router." The agent will keep writing Express routes that break your build.

Rule of thumb: Treat AGENTS.md like live production code. After any major refactor, check whether your agent instructions need an update.

---

How to Bootstrap Your AGENTS.md Fast

You don't need to craft an AGENTS.md from a blank file. Here are two practical ways developers set up their initial file:

1. Let Your AI Agent Draft It (Most Popular)

The fastest path is asking your AI assistant (Cursor, Claude Code, Gemini CLI, ChatGPT) to analyze your repo:

Prompt: "Scan my repository structure, dependencies, and build/test scripts. Generate a concise, 100-line AGENTS.md following the AAIF standard. Include commands for building, testing, linting, and our main project conventions."

2. Lightweight CLI Tools

• agentseed — an open-source CLI scanner that inspects your repo structure to generate a starter AGENTS.md with detected build and test commands.

  bashCopy
  1npx agentseed init

⚠️ Remember: Auto-generated drafts are just a starting point. Always review the file manually to strip out noise and add your team's real, non-negotiable boundaries.

---

Summary Checklist for AGENTS.md

AGENTS.md isn't just another configuration file. It's an operational contract between you and your AI coding agent. It determines whether your assistant writes clean, team-aligned code on the first try — or generates alien boilerplate that wastes your time and token budget.

Before committing your AGENTS.md, check off these items:

• Length — Kept under 200 lines (split into nested files if larger).
• Tone — Uses hard imperatives ("ALWAYS", "NEVER"), avoiding weak suggestions.
• Commands — Contains exact CLI recipes for building, testing, and linting.
• Red Lines — Explicitly lists off-limits files, folders, and actions.
• Examples — Includes concrete ❌ BAD vs. ✅ GOOD code snippets.
• Security — Zero API keys, tokens, or credentials included.
• Relevance — Omits generic language rules that LLMs already know.
• Freshness — Accurately reflects your current codebase state.

Writing an AGENTS.md brings a surprising bonus: as you formalize rules for your AI agent, you crystalize your team's engineering culture. Those implicit conventions that used to live only in senior devs' heads suddenly become clear, written standards.

That's the true power of AGENTS.md — it makes your engineering rules explicit. For machines, and for human teammates alike.

---

Resources & Links

Resource	Link
🌐 AGENTS.md Official Site	agents.md
📦 AGENTS.md Specification Repo	github.com/agentsmd/agents.md
🏛️ Agentic AI Foundation (AAIF)	aaif.io
🔧 agentseed CLI Generator	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