What is AGENTS.md?
AGENTS.md is a Markdown file for repository-specific instructions aimed at coding agents. Teams use it to record commands, code conventions, testing expectations, directory boundaries, and safety notes close to the code. It complements human documentation. Which files are discovered and how conflicting instructions are resolved depends on the agent using it.
What should an AGENTS.md contain?
Include the commands and constraints a contributor needs to change the repository safely: setup, targeted checks, formatting, architecture boundaries, sensitive paths, and the definition of done. Prefer executable specifics over broad preferences.
How should it stay maintainable?
Treat the file as part of the code review surface. Update commands when scripts change, remove obsolete rules, and keep nested guidance focused on the directory it governs.
Useful instruction categories
| Category | Include | Avoid |
|---|---|---|
| Commands | Exact install, test, lint, and build commands | Commands that no longer exist |
| Boundaries | Owned paths and files that need extra care | Vague warnings without a reason |
| Completion | Required checks and expected evidence | Unverifiable quality slogans |
AGENTS.md maintenance checklist
- Every command works from the stated directory.
- Rules identify their scope and reason.
- Sensitive files and prohibited actions are named.
- The file is reviewed when project scripts or structure change.
Frequently asked questions
Is AGENTS.md required?
No. It is an optional convention. Its value depends on whether the agent recognizes it and whether the instructions are accurate.
Does AGENTS.md replace README.md?
No. README.md serves human readers; AGENTS.md can hold operational guidance tailored to coding agents.
Can a repository have more than one AGENTS.md?
The open format describes nested files, but discovery and precedence should be confirmed for each agent you use.
Should secrets go in AGENTS.md?
No. Document how credentials are obtained and handled without committing secret values.
Who should maintain AGENTS.md?
The team that owns the affected code should review it alongside build scripts, architecture, and contribution rules.