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.¹

• Soon after, OpenAI secured the agents.md domain as the central place for publishing best practices, giving the movement an official anchor.²

• 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.³

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:

Code editors & IDEs:

• Cursor
• Zed
• Phoenix
• OpenCode
• And more

Command-Line Tools (CLIs):

• 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. Run ln -s AGENTS.md AGENT.md. This step maintains compatibility with older assistants that haven’t yet switched.

External Links

• 1. https://github.com/agentmd/agent.md?
• 2. https://sgryphon.gamertheory.net/2025/07/agents-md-standardisation-for-agentic-coding-systems/
• 3. https://sgryphon.gamertheory.net/2025/07/agents-md-standardisation-for-agentic-coding-systems/
• 4. https://gyliu513.medium.com/agents-md-the-readme-your-ai-coding-agents-actually-read-b37a32876900
• 5. https://wandb.ai/wandb_fc/genai-research/reports/Introduction-to-Agents-md–VmlldzoxNDEwNDI2Ng