Agents.md: The README for Your AI Coding Agents
This guide introduces AGENTS.md, an open specification changing how AI agents interact with software projects. Unlike traditional README.md files, which are written for humans and often leave gaps, AGENTS.md provides clear, machine-readable instructions that both people and AI agents can follow with precision.
The documentation gap: Challenges in AI agent automation
- Human vs. machine language: Traditional README files are written for people, not machines. Phrases like “activate your virtual environment” or “run the usual tests” make sense to developers but are ambiguous to AI agents. Automation requires explicit, step-by-step instructions with no room for interpretation.
- Scattered knowledge: Many workflows aren’t fully documented. Critical steps are often hidden in configuration files, chat messages, or stored in developers’ memory. This fragmentation resulted in missing dependencies, broken command sequences.
- Collaboration conflicts: 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.
- Complex setups: Projects like Python web apps often involve virtual environments, dependency installations and environment variable configuration. A human developer can adjust when something goes wrong, but an AI agent requires every step to be defined precisely, including error handling and dependency validation.
- 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: 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
Introducing AGENTS.md
AGENTS.md is a dedicated Markdown file that provides clear, structured instructions for AI coding agents. It offers one reliable place for contributors to find details that might otherwise be scattered across wikis, chats, or outdated docs.
Unlike a README, which focuses on human-friendly overviews, AGENTS.md includes the operational, machine-readable steps agents need, such as:
- Project overview
- Set up and build steps
- Test commands and CI notes
- Code style and formatting rules
- Commit and PR guidelines
- Security and dependency policies
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:
- 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:
AGENTS.md architecture
AGENTS.md has no complex architecture. It is a lightweight convention; simply a Markdown file placed in the project to document clear instructions. There is no special schema or tooling 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 migrate to AGENTS.md?
Migrating to AGENTS.md is simple and can be done in two quick steps from your terminal:
- Rename your file in the project root: 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.
- Create a symbolic link in the same folder (optional): Still in the project root, create a symbolic link so that tools looking for “AGENT.md” will be redirected to “AGENTS.md”. In your terminal you can run “ln -s AGENTS.md AGENT.md”.
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.