The Problem It Solves
AI coding assistants need to know how your project works—what commands to run, how to test, what conventions to follow. Without clear instructions, every AI tool guesses differently and often gets it wrong.
Every AI coding tool guesses how your project works. Cursor might format code differently than Copilot. Claude Code doesn't know your test commands. Each tool has its own config file—.cursorrules, CLAUDE.md, copilot-instructions.md.
Update one, forget the others. The AI suggests patterns you've deprecated. It runs the wrong build command. It commits directly to main because nobody told it not to.
Five tools, five config files, five chances to get out of sync.
One Markdown file in your project root. Every AI tool reads it. Your coding standards, your test commands, your project structure, your boundaries—written once, followed by 25+ tools.
Like an employee handbook for AI assistants. They know how to build, how to test, what's off limits, and who to ask before making certain changes.
One file. Every tool. Same instructions.
How It Works in Practice
- Drop an AGENTS.md file in your project root. It's plain Markdown—no special syntax, no dependencies, no build step. Write your build commands, code style, and boundaries in a format any developer (or AI) can read.
- A developer opens the project in an AI-powered editor—Cursor, VS Code with Copilot, Claude Code, Windsurf, or any of the 25+ supported tools.
- The AI tool discovers the file automatically. It looks for AGENTS.md in the project root and any parent directories. No configuration needed—just the file's presence is enough.
- The AI reads your instructions. Build commands, test commands, code conventions, security boundaries—everything you wrote becomes the AI's operating context for this project.
- Developer asks the AI for help. "Write a new API endpoint," "Fix this failing test," "Refactor this component"—normal AI-assisted development.
- The AI follows your rules. It uses your specified build commands, follows your coding conventions, runs your test suite, and respects your "never do" boundaries—because you told it to, in one file.
- In monorepos, nested files refine the instructions. A subdirectory's AGENTS.md adds package-specific rules on top of the root file. The closest file to the code being edited takes precedence.
Where AGENTS.md Shows Up
AGENTS.md is just a Markdown file—but its impact is real. Here's where it makes the biggest difference.
Team Development
Everyone on the team uses AI assistants, but each person uses a different tool. AGENTS.md ensures every tool follows the same project conventions, no matter which AI is being used.
Monorepo Management
Nested AGENTS.md files give each package its own instructions. The frontend package knows about React conventions; the backend knows about Express patterns; the shared library follows its own rules.
Open Source Projects
Contributors using AI assistants automatically get project context. Apache Airflow, with 4,000+ contributors, uses AGENTS.md to communicate complex testing and contribution requirements to AI tools.
Security Boundaries
The three-tier boundary system tells AI what to always do, what to ask about first, and what to never touch. Critical for protecting production configs, secrets, and sensitive paths.
Onboarding New Developers
New team members' AI assistants get instant context about the project. Commands, conventions, and boundaries are all in one place—no more asking teammates how to run tests.
Enterprise Standardization
OpenAI has 88 AGENTS.md files across their repositories. Large organizations use it to enforce consistent AI behavior across dozens of projects and hundreds of developers.
Why It Matters
Zero dependencies. It's just a Markdown file. Drop it in your repo and it works. No packages to install, no services to configure, no schemas to validate.
60,000+ repositories have already adopted AGENTS.md. It works with Cursor, Copilot, Claude Code, Aider, VS Code, Windsurf, Gemini CLI, and 20+ more tools. Every major AI coding assistant reads it.
Developed collaboratively by OpenAI, Google, Cursor, Sourcegraph, and Factory, then donated to the Linux Foundation's Agentic AI Foundation under the MIT license for vendor-neutral governance. No single company controls the standard.
An analysis of 2,500+ repositories found that the best AGENTS.md files share six characteristics: clear commands, testing procedures, project structure, code style with examples, git workflow, and explicit boundaries. Keep it under 150 lines and iterate based on what you see the AI getting wrong.
Key Concepts in Plain Language
- Three-Tier Boundaries: Tell AI what to always do (run tests before committing), what to ask about first (modifying auth flows), and what to never do (commit secrets). Clear guardrails that any AI tool can follow.
- Hierarchical Files: Place AGENTS.md files at different levels of your project. The root file sets global rules; nested files in subdirectories add package-specific instructions. The closest file to the edited code takes precedence.
- Vendor-Neutral: One file replaces .cursorrules, CLAUDE.md, copilot-instructions.md, and other tool-specific configs. Write your instructions once, and every AI tool reads the same file.
- Commands Section: Put your build, test, and lint commands in backticks so AI tools can extract and run them directly. Include file-scoped commands for faster feedback loops.
- Iterate, Don't Plan: Start with 20 lines of essential commands. Add rules when you see the AI making repeated mistakes. The best AGENTS.md files grow through iteration, not upfront planning.
- Override Files: AGENTS.override.md files let you make one-off adjustments without changing the shared file. Useful for personal preferences or sensitive service-specific rules.
The Standard
AGENTS.md is the simplest standard here—a single Markdown file that gives AI coding assistants explicit instructions. What to do, what not to do, how your project works. One file, every tool.
What It Looks Like
Here's a starter AGENTS.md you can copy into your project root and adapt:
# My Project ## Build & Test Commands - Type-check and lint: `pnpm check` - Run full test suite: `pnpm test --run` - Run single test file: `pnpm test --run path/to/file.test.ts` - Start dev server: `pnpm dev` ## Code Style - Prefer functional components with hooks - Use `zod` for request validation - Follow existing patterns in `src/components/` ## Security Boundaries - ALWAYS run tests before committing - NEVER commit `.env` files or hardcode API keys - NEVER modify files in `config/production/` - ASK before changing authentication flows
That's a complete, working AGENTS.md in 15 lines. Every AI coding tool that reads this file will follow these instructions. Start here, then add rules when you see the AI making repeated mistakes.
How to Apply This
- • Create an AGENTS.md file in your project root—that's it, you've adopted the standard
- • Start with the essentials: build commands, test commands, and one or two "never do" boundaries
- • Use the three-tier system: Always Do (formatting, tests), Ask First (architecture changes), Never Do (delete production data, commit secrets)
- • Include code style examples—showing the preferred pattern is more effective than describing it
- • For monorepos, nest AGENTS.md files in subdirectories for package-specific guidance
- • Keep it under 150 lines. Long files slow agents down and bury the important signals
- • Maintain it like you maintain your code—outdated instructions are worse than no instructions
- • Use file-scoped commands (lint one file, test one file) instead of project-wide commands for faster AI feedback
What to Watch Out For
Honest Limitations
- • Boundaries are written in natural language, which means they're suggestions, not enforcements. An AI might still violate a "never do" rule in edge cases.
- • AGENTS.md is part of your attack surface. A malicious file in a forked repo could attempt to manipulate agent behavior. Review AGENTS.md in pull requests from external contributors.
- • Some fragmentation persists—Claude Code still prefers CLAUDE.md and Cursor has .cursorrules. You may need symlinks or dual files for full coverage.
- • AGENTS.md needs maintenance. Outdated instructions (wrong build commands, deprecated patterns) actively make the AI worse. Treat it like living documentation.
- • There's no validation or enforcement mechanism. The AI reads AGENTS.md as guidance, not as a constraint system. Structured permissions are proposed but not yet standardized.
Get Started
- AGENTS.md Website — Official specification and format guide
- AGENTS.md GitHub Repository — Source, templates, and community contributions
- Lessons from 2,500+ Repositories — GitHub's analysis of what makes an effective AGENTS.md
- Apache Airflow AGENTS.md — Real-world example from a large open source project