# AGENTS.md Template for Codex and Monorepos

Build, audit, copy, and download concise AGENTS.md starters for Codex, Node.js, Python, and monorepos with commands, boundaries, and review checks.

## Quick Answer

A useful AGENTS.md template gives Codex copyable repo instructions: project purpose, install command, test command, safe edit boundaries, forbidden files, and review expectations. Start with one root file, then add nested AGENTS.md files only for Node.js, Python, or monorepo packages that need different commands, ownership, or safety boundaries.

## Best for

Developers setting up Codex-compatible agents, team leads standardizing repo instructions, and maintainers cleaning stale agent rules.

## Use this guide to

Developers want a copyable AGENTS.md template instead of another explanation of what instruction files are.

## Recommended play

1. Create a root AGENTS.md first, then add nested files only when a folder has different commands or ownership.
2. Keep every command copy-pasteable from a clean checkout.
3. 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 |
| Nested scope | Package-specific commands and boundaries | apps/web/AGENTS.md uses npm test; packages/api/AGENTS.md uses pytest | The folder does not actually differ from the root policy |

## Execution steps

1. **Write the root file** — Start with the project purpose, commands, safe boundaries, and review expectations.
2. **Test every command** — Run the listed commands once so the agent does not inherit broken instructions.
3. **Add folder-specific notes only when needed** — Use nested AGENTS.md files for monorepo packages, generated folders, or high-risk areas with different rules.
4. **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.

## FAQ

**Q: What should an AGENTS.md template include?**

A useful AGENTS.md template gives Codex copyable repo instructions: project purpose, install command, test command, safe edit boundaries, forbidden files, and review expectations. Start with one root file, then add nested AGENTS.md files only for packages that need different commands, ownership, or safety boundaries.

**Q: When should you add a nested AGENTS.md file?**

Add a nested AGENTS.md only when a folder genuinely needs different guidance, such as package-specific test commands, generated-file boundaries, ownership rules, or risk limits. Keep the root file for shared repo policy and the nested file for local exceptions.

**Q: Who is this AGENTS.md template for?**

Developers setting up Codex-compatible agents, team leads standardizing repo instructions, and maintainers cleaning stale agent rules across Node.js, Python, and monorepo layouts.

**Q: Should you generate AGENTS.md automatically?**

Use a generator only as a starter for repository facts you verify yourself: exact setup and test commands, scope, restricted paths, and completion rules. Do not let a model invent a long repository overview. Run every generated command, delete redundant guidance, and audit the final file before committing it.

## Evidence sources

- [OpenAI Codex AGENTS.md documentation](https://learn.chatgpt.com/docs/agent-configuration/agents-md) — OpenAI. Official AGENTS.md behavior and precedence reference.
- [GitHub Copilot custom instructions](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions) — GitHub. Official repository instruction reference for Copilot workflows.
- [Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?](https://arxiv.org/abs/2602.11988) — arXiv. 2026 preprint comparing no context, model-generated context, and developer-written context across coding-agent tasks; reports higher cost and recommends minimal repository-specific guidance.
- [Configuration Smells in AGENTS.md Files](https://arxiv.org/abs/2606.15828) — arXiv. 2026 repository-mining preprint cataloging six instruction-file smells across a sample of 100 AGENTS.md or CLAUDE.md repositories.

## Related guides

- [AGENTS.md examples for Node.js, Python, and monorepos](/guides/agents-md-examples-codex-node-python-monorepos) — Template readers often need concrete examples after they understand the required sections.
- [AGENTS.md vs CLAUDE.md comparison](/guides/agents-md-vs-claude-md-cursorrules-copilot-instructions) — Readers who need to choose the right instruction file can start there.
- [Codex vs Claude Code](/guides/codex-vs-claude-code) — AGENTS.md setup matters most when choosing a Codex-compatible workflow.
- [agent governance checklist](/guides/agent-governance-checklist-for-software-teams) — Team instructions should connect to broader approval and audit rules.
- [loop engineering for AI coding agents](/guides/loop-engineering-ai-coding-agents) — AGENTS.md should name the verification command and iteration cap that agent loops rely on.

---
Canonical: https://www.kyenai.com/guides/agents-md-template-for-ai-coding-agents