AGENTS.md explained
What is AGENTS.md?
AGENTS.md is a Markdown instruction file for AI coding agents. Think of it as a README written for agents instead of users.
AGENTS.md meaning
`AGENTS.md` gives coding agents predictable project instructions. It can describe setup commands, test commands, code style, file ownership, deployment notes, and safety rules. OpenAI Codex reads AGENTS.md before doing work, and the open AGENTS.md format is intended to work across agent tools.
What to include in AGENTS.md
- Setup and install commands
- Test and build commands
- Code style rules
- Important file locations
- What not to change
- Review, formatting, and deployment expectations
AGENTS.md vs README.md
README.md explains the project to humans. AGENTS.md tells AI coding agents how to work inside the project. README.md can be broad and product-focused; AGENTS.md should be direct, operational, and specific.
AGENTS.md vs CLAUDE.md
AGENTS.md is a cross-agent instruction file. CLAUDE.md is specifically used by Claude Code for persistent project memory. Some teams keep both: AGENTS.md for shared agent instructions and CLAUDE.md for Claude-specific preferences.
How to write AGENTS.md with Markdown Docs
Draft the file in Markdown Docs online editor, preview the headings and command blocks, then save it as `AGENTS.md` in your project root. Use the desktop editor when you want local file association and autosave.
Related references
- OpenAI Codex AGENTS.md guide for official Codex behavior.
- AGENTS.md open format for the broader agent-instructions format.
FAQ
Is the file AGENT.md or AGENTS.md?
The common open format and Codex convention is AGENTS.md, plural. Some teams may create AGENT.md, but AGENTS.md is the safer default.
Does AGENTS.md replace README.md?
No. README.md explains the project to users. AGENTS.md gives operational instructions to AI coding agents.
Where should AGENTS.md go?
Place it at the repository root for project-wide instructions. Add nested AGENTS.md files only when a subfolder needs different rules.