iTranslated by AI
What is AGENTS.md? The Role and Usage of AI Agent-Specific READMEs
When introducing an AI coding agent to a project, the first challenge is "how to get the agent to understand the correct rules and procedures."
The solution is AGENTS.md. Separate from the README that humans read, by summarizing setup procedures, coding standards, and development workflows in an AI-specific README, the agent can proceed with tasks without hesitation.
In this article, we will clearly explain the basic structure, operational tips, and differences from READMEs for AGENTS.md so that developers can introduce it immediately.
On August 20, 2025, OpenAI released "AGENTS.md," a simple format for providing instructions to AI coding agents.
What is AGENTS.md?
It was created in collaboration with development teams for agents and tools such as OpenAI Codex, Amp, Google's Jules, Cursor, Factory, and Roo Code.
The OpenAI Codex team created the name "AGENTS.md" in a format that is easy for other AI agents to adopt as well.
AGENTS.md is an open-format Markdown file that describes the context and instructions for AI coding agents to work within a project.
Just as there is a README.md for humans, AGENTS.md provides the information for AI coding agents to work efficiently and accurately.
Various AI coding agents are progressively adding support. Devin also supports AGENTS.md.
- Devin supports the AGENTS.md file.
- AGENTS.md is a simple manual for AI agents (similar to a README).
- You can describe the context and instructions necessary for the project, which Devin can read before starting work.
Functions across multiple agents
When the site was released, Devin was not included.
It seems they are working on enabling support across other agents gradually.
What is the difference between README and AGENTS.md?
Separation from human-oriented documentation
By consolidating technical instructions for AI into AGENTS.md, you prevent README.md from becoming cluttered, maintaining readability for humans.
OpenAI released the specification in August 2025, and it is being adopted by many open-source projects.
| Item | AGENTS.md | README |
|---|---|---|
| Target | AI agents | Human developers |
| Content | Setup procedures, code style, test guidelines, project structure, development workflows | Project overview, installation methods, usage, etc. |
| Reference | Automatically referenced by AI agents | Manual for humans to read |
| Purpose | To enable AI agents to work accurately | To enable developers to understand and utilize the project |
Setting up AGENTS.md
By placing AGENTS.md, AI agents will automatically reference and read the AGENTS.md file to perform their tasks.
- Place AGENTS.md in the project root or any desired location.
- Agents automatically reference this file before starting work.
- Depending on the content, they can understand coding styles, development procedures, testing procedures, etc.
Basic Configuration Example of AGENTS.md
AGENTS.md is a file for AI agents to load development environments and rules. The key to clarifying instructions is to write the basic structure, such as the development environment, code style, and testing, in bullet points.
I also recommend writing domain-specific or project-specific rules in AGENTS.md.
# AGENTS.md
## 1. Purpose
This file is an instruction manual dedicated to the AI agent (Devin).
Before Devin starts working, it references this to provide the context and rules of the project so that it can work accurately.
## 2. Setup Commands
- Install dependencies: `npm install`
- Start development server: `npm run dev`
- Run tests: `npm test`
- Production build: `npm run build`
## 3. Code Style
- Use TypeScript strict mode
- Prioritize function components for React
- Follow ESLint and Prettier settings
- Commit messages in Conventional Commit format
## 4. Testing Guidelines
- Create unit tests for new functions
- Test framework: Jest
- Target coverage >80%
- Always run tests before committing
## 5. Project Structure
- `/src` - Main application code
- `/tests` - Test code
- `/docs` - Documentation
- `/public` - Static assets
- README.md is for humans and not automatically referenced by Devin
## 6. Development Workflow
- Create feature branches from `main` branch
- Perform code reviews via pull requests
- Squash commits before merging
- Update documentation for new features
## 7. Pull Request Rules
- Title format: [<project_name>] <title>
- **Required**: Do not work on comments from reviewers until checking with the requester and receiving instructions
- Always create as a Draft PR
- Set Assignees to the person who requested the implementation
## 8. Notes
- Even if there are comments on a PR, do not work until instructed
- AGENTS.md must always be referenced before coding as a dedicated instruction manual for Devin
- .rules, .mdc, .cursorrules, .windsurf, etc., are also automatically referenced
- Including detailed and clear instructions as much as possible will improve Devin's work efficiency
I created an AGENTS.md like the one below for my personal project.
I haven't verified it yet, but I would like to try testing whether it works if I write specification-driven development in this manner as well.
Onboarding Points
It can be utilized for onboarding to help AI agents properly grasp product code.
Also, let team members who don't know about AGENTS.md know about it.
By understanding the role, members can use AI agents to make improvements.
- AGENTS.md is an operation manual dedicated to Devin
- README is an instruction manual for humans
- The more detailed and clear the instructions in AGENTS.md, the better the accuracy and efficiency of the AI agent's work
Points for creating and operating an AGENTS.md file
-
Maintain AGENTS.md
- Enable AI agents to understand the environment and rules necessary for the work.
-
Include development environment setup information
- Dependencies, build/test commands, etc.
-
Clarify rules for code style, testing, and workflows
- AI agents can work according to project standards.
-
Suggest project structure and document references
- Write down specific file or directory paths as needed.
-
Update and improve
- Update AGENTS.md whenever there are new rules or changes.
CLAUDE.md, GEMINI.md: About other formats
I think tools like Claude Code and Gemini CLI often use CLAUDE.md or GEMINI.md.
In my personal view, I felt it's better to use AGENTS.md as the starting point.
The reason is that considering some members use Claude Code and others don't, it is more convenient for Devin and Codex to align with AGENTS.md.
By placing AGENTS.md and adding a note to always read CLAUDE.md, you can have Devin automatically read CLAUDE.md when it performs implementation.
While maintaining existing formats, placing AGENTS.md serves as a starting point for multiple agents.
Summary
AGENTS.md has not been long since the site was released.
I think there will be many products adopting it from now on. I feel like creating documents that enhance precision by refining the use cases through repeated operation.
While repeating failure stories such as the agent ignoring the guardrails I set when requesting implementation with Devin, I find the common AGENTS.md appealing.
Considering that tools that can be used across multiple agents will increase in the future, it might be a good idea to consider it for your products.
Reference Articles
Discussion