Agents.md: A Machine-Readable Alternative to README
AI coding agents work better when they have clear instructions. Most projects include a README.md, but this file is written for people. It explains the project, shows how to get started, and helps new contributors.
AGENTS.md, on the other hand, is a small, open, and predictable file. It provides coding agents with the additional details they need to understand your project and act accordingly. More than 60,000 open-source projects already use it.
Explore the architecture and the benefits of AGENTS.md files:
Why README is not enough in AI agent automation
1. Human vs. machine language
A README often uses informal phrases like “set up your environment” or “run the usual tests.” Humans understand these. AI agents do not.
Agents need exact, step-by-step instructions they can follow without having to guess.
2. Scattered knowledge
Important details can be found in various locations, such as configuration files, old messages, or team memory. When steps are missing, agents may install the wrong dependencies or run commands in the wrong order.
3. Many agents working together
In team environments, multiple AI agents interact with the same codebase. Without standardized processes, agent actions can overlap or lead to errors. Each integration then requires additional manual configuration and oversight.
4. Complex project setups
Modern projects often incorporate virtual environments, package managers, automated tests, and environment variables. Humans can adapt when something fails. Agents cannot. They need every step written clearly.
5. Outdated instructions
Documentation often becomes outdated as projects evolve. AI agents following outdated instructions encounter mismatches with the actual codebase, wasting time on automation failures caused by stale documentation rather than real software issues.
Path to standardization: Introducing AGENTS.md
- Spring ’25: Pressure for a shared standard grew, and Sourcegraph proposed a dedicated AGENT.md file, turning scattered practices into a concrete idea.1
- Soon after, OpenAI secured the agents.md domain as the central place for publishing best practices, giving the movement an official anchor.2
- Late June ’25: Major tools, including Codex, OpenCode, Gemini CLI, Jules, and Factory A, began adopting the plural AGENTS.md convention, bringing consistency across coding assistants and developer workflows.
- July 16: OpenAI announced a collaboration with Sourcegraph and Google to formalize the guidelines.3
What AGENTS.md Is
AGENTS.md is a simple, open format used by more than 60,000 open-source projects.
It acts like a “README for agents.”
It gives AI coding agents one reliable place to find instructions about:
- how the project works
- how to set up a development environment
- how to run builds and tests
- what coding rules the team follows
- how to write commits or pull requests
- security and dependency rules
It keeps these details separate from the human-oriented README, so both stay clear and focused.
Because it is plain Markdown, the file is lightweight and can be opened in any editor, CLI, or browser. Currently, mainstream coding assistants all support AGENTS.md:4
- Cursor
- Zed
- Phoenix
- OpenCode
- And more
- Aider
- Gemini CLI (from Google)
- And more
Below is a basic illustration of what an AGENTS.md file includes:
How AGENTS.md works in practice
One file, predictable behavior
Place an AGENTS.md file at the root of your project. Most agents will automatically look for this file.
Larger projects or monorepos
You can use multiple AGENTS.md files. Each subproject can have its own version with localized rules. Agents read the closest file in the directory tree, so instructions always match the work area.
Lightweight design
Linters, build systems, and test runners follow the commands written in the file. This gives more consistent and repeatable results.
AGENTS.md architecture
AGENTS.md is a simple Markdown file without dependencies or schema requirements. It is a lightweight convention; simply a Markdown file placed in the project to document clear instructions. No special schema or tooling is required.
- In larger projects or monorepos, agents use the nearest AGENTS.md file to the code they are working on. Local files override the root-level file, so instructions remain relevant to that part of the project.
- Tools such as linters, test runners, and build systems are executed exactly as defined in the file, ensuring predictable and consistent results.
Why AGENTS.md matters for code quality
AGENTS.md boosts both quality and consistency by giving AI agents access to the same standards and rules that guide human developers.
With clear, project-specific instructions available upfront, the AI can avoid many of the common coding pitfalls that arise when it operates without context.
Below are some of the ways AGENTS.md makes a tangible difference:
- Applying coding standards. AGENTS.md makes sure the AI follows the same coding rules as the team. If your project requires unit tests for every function or uses a specific naming style for API endpoints, writing that in AGENTS.md tells the AI to do the same.
For example, if the rule is “use Python’s logging library instead of print() for messages”, the AI will use logging by default.
- Providing architectural context. Documenting the overall structure of the project in AGENTS.md helps the AI know where new code belongs and which design conventions to follow.
For example, if your project separates code into folders for data, logic, and user interface, documenting that structure helps the AI place new files in the right folder
- Modular documentation: For larger codebases, AGENTS.md supports modularity. Additional files can be placed in subfolders, allowing individual packages or modules within a monorepo to have their own localized rules.
By embedding these practices directly into AGENTS.md, teams reduce the risk of introducing bugs and save time that would otherwise be spent fixing preventable issues later in code review.
How to Add AGENTS.md to Your Project
1. Create the file
Open a terminal, navigate to your project’s root folder, and rename your existing instruction file. For example, run “mv AGENT.md AGENTS.md”. This ensures your main configuration follows the new convention.
2. Add what matters most
Include the details an agent needs to work effectively:
- Project overview
- Build and test commands
- Code style guidelines
- Security notes
- Testing instructions
Think of what you would tell a new teammate.
3. Add extra instructions
You can also include:
- Commit message format
- PR rules
- Notes about large datasets
- Deployment steps
4. For large monorepos
Place additional AGENTS.md files inside packages. As mentioned earlier, agents always use the closest file.
Further Readings
- Low/No-Code AI Agent Builders: n8n, AgentKit, make, Zapier
- AI Agents: Operator vs Browser Use vs Project Mariner
- Agentic CLI Tools Compared: Claude Code vs Cline vs Aider
Reference Links
Cem's work has been cited by leading global publications including Business Insider, Forbes, Washington Post, global firms like Deloitte, HPE and NGOs like World Economic Forum and supranational organizations like European Commission. You can see more reputable companies and resources that referenced AIMultiple.
Throughout his career, Cem served as a tech consultant, tech buyer and tech entrepreneur. He advised enterprises on their technology decisions at McKinsey & Company and Altman Solon for more than a decade. He also published a McKinsey report on digitalization.
He led technology strategy and procurement of a telco while reporting to the CEO. He has also led commercial growth of deep tech company Hypatos that reached a 7 digit annual recurring revenue and a 9 digit valuation from 0 within 2 years. Cem's work in Hypatos was covered by leading technology publications like TechCrunch and Business Insider.
Cem regularly speaks at international technology conferences. He graduated from Bogazici University as a computer engineer and holds an MBA from Columbia Business School.
Be the first to comment
Your email address will not be published. All fields are required.