AGENTS.md

What is AGENTS.md?

AGENTS.md is a specialized file designed to provide detailed, agent-focused instructions for AI coding agents. It complements the traditional README.md file, which is typically geared towards human readers. While README.md files offer quick starts, project descriptions, and contribution guidelines, AGENTS.md contains more detailed context that coding agents need, such as build steps, tests, and conventions. This separation helps keep READMEs concise and focused on human contributors while providing precise, agent-focused guidance.

Benefits

AGENTS.md offers several key benefits:

• Clear and Predictable Instructions: It gives agents a dedicated place for instructions, making it easier for them to understand and execute tasks.
• Complementary to README.md: It works alongside existing README and documentation files, providing additional context without cluttering the main project description.
• Wide Compatibility: AGENTS.md is designed to work with a growing ecosystem of AI coding agents and tools, ensuring broad applicability.
• Flexibility: It can be used in various projects, from small repositories to large monorepos, with the ability to nest AGENTS.md files for subprojects.

Use Cases

AGENTS.md can be used in a variety of scenarios:

• Project Setup: Providing detailed instructions for setting up the development environment, including build and test commands.
• Code Style Guidelines: Outlining coding standards and style guidelines that agents should follow.
• Testing Instructions: Specifying how to run tests, including commands and patterns for focusing on specific tests.
• Pull Request Guidelines: Including instructions for creating and reviewing pull requests, such as title formats and pre-commit checks.
• Security Considerations: Highlighting security best practices and potential gotchas.
• Deployment Steps: Detailing the steps required for deploying the project.

How to Use AGENTS.md

Using AGENTS.md is straightforward:

1. Add AGENTS.md: Create an AGENTS.md file at the root of the repository. Many coding agents can even scaffold one for you.
2. Cover What Matters: Add sections that help an agent work effectively with your project, such as project overview, build and test commands, code style guidelines, testing instructions, and security considerations.
3. Add Extra Instructions: Include any additional information you would tell a new teammate, such as commit message guidelines, security gotchas, and deployment steps.
4. Nested AGENTS.md for Large Monorepos: For large monorepos, place another AGENTS.md inside each package. Agents will automatically read the nearest file in the directory tree, ensuring tailored instructions for each subproject.

Additional Information

AGENTS.md emerged from collaborative efforts across the AI software development ecosystem. It is maintained and evolved as an open format to benefit the entire developer community, regardless of which coding agent you use. The format is flexible and can be adapted to various projects and tools, making it a valuable addition to any AI-powered development workflow.