Quick answer
A useful AGENTS.md tells the agent what the repo is, which commands prove work is done, what files are sensitive, and how the team wants changes reviewed. Do not turn it into a long policy essay; the best template is short, specific, and easy to verify.
Copyable starter template
Use this structure: project purpose, install command, development command, test command, formatting command, safe edit boundaries, files to avoid, pull request expectations, and known failure notes.
For small repos, one AGENTS.md at the root is enough. For monorepos, add short nested files only where commands or ownership really differ.
For teams, add one security section: no secrets in prompts, no production writes without approval, and no generated code merge without review.
What not to put in it
Do not paste secrets, access tokens, private customer data, or vague motivational rules. Avoid rules like 'write clean code' unless you explain what command or reviewer checks that rule.
Do not copy the same paragraph into every instruction file. Keep one source of truth and link tool-specific files back to it when possible.
Recommended play
- Create a root AGENTS.md first, then add nested files only when a folder has different commands or ownership.
- Keep every command copy-pasteable from a clean checkout.
- Review AGENTS.md whenever CI, package managers, test commands, or security boundaries change.
AGENTS.md template blocks
Use these blocks as a practical template. Delete anything that is not true for the repo.
| Area | What to write | Example | Keep it out when |
|---|---|---|---|
| Repo purpose | One sentence on what the project does | Next.js marketing site with a FastAPI admin backend | The repo is private and purpose details reveal sensitive plans |
| Commands | Install, dev, test, build, lint | npm run test; npm run build | The command is stale or only works on one developer machine |
| Safe boundaries | Allowed files, risky files, generated files | Do not edit migrations without approval | The team has not agreed on ownership yet |
| Review rule | How to prove the change is done | Show changed files, test result, and known risk | The rule is only style preference and not checked anywhere |
Execution steps
Write the root file
Start with the project purpose, commands, safe boundaries, and review expectations.
Test every command
Run the listed commands once so the agent does not inherit broken instructions.
Add folder-specific notes only when needed
Use nested AGENTS.md files for monorepo packages, generated folders, or high-risk areas with different rules.
Add a drift owner
Name the person or team that updates instructions when CI, package managers, or release flow changes.
Common pitfalls
Writing a policy novel
Keep the file practical: commands, boundaries, and review steps beat long philosophy.
Listing commands nobody runs
Only include commands that work from a clean checkout or explain the required setup.
Hiding secrets in instructions
Describe environment variable names and access boundaries, never credential values.
Implementation checklist
- Explain what the repo does in one sentence.
- List install, test, build, and lint commands.
- Name files or folders the agent should not edit without approval.
- Explain how to verify a completed task.
- Keep secrets and customer data out of the file.
- Review the file when CI or package managers change.
Questions this guide answers
What is the answer to AGENTS.md template for AI coding agents?
Start AGENTS.md with the repo purpose, safe edit boundaries, install commands, test commands, style rules, and review expectations. Keep it short enough that an agent can follow it during a real task.
Who is this template and checklist for?
Developers setting up Codex-compatible agents, team leads standardizing repo instructions, and maintainers cleaning stale agent rules.
Which sources support this guide?
This guide is grounded in official or high-confidence sources from OpenAI, GitHub.