The short answer
AGENTS.md is a plain markdown file in your repository that tells a coding agent how your project works: commands, conventions, and guardrails. Codex uses it, and Claude Code can read it in place of a CLAUDE.md. Keep it short, specific, and reviewed like code, so one file serves every agent your team uses.
What is AGENTS.md?
AGENTS.md is an instruction file for coding agents. OpenAI’s Codex CLI documentation says that running /init creates an AGENTS.md file with instructions for Codex. Anthropic’s documentation says that if your repository already has an AGENTS.md for other coding agents, Claude Code can read it in place of a CLAUDE.md.
The practical value is a single place to describe your project to any agent, instead of one file per tool that drift apart.
What belongs in an AGENTS.md?
Put in what an agent cannot infer quickly from the code and what you would otherwise repeat in every prompt.
- Commands: install, build, lint, test, run, exactly as typed.
- Conventions: naming, formatting, error handling, patterns your team prefers.
- Architecture: a few lines on how the pieces fit.
- Guardrails: files not to edit, operations that need approval, secrets handling.
- Definition of done: for example, tests pass and the changelog is updated.
# AGENTS.md## Commands - Install: npm ci - Test: npm test - Lint: npm run lint
## Conventions - TypeScript strict. No any without a comment. - Small pure functions; side effects at the edges.
## Guardrails - Never edit /generated. - Ask before adding a dependency. - Never commit secrets or .env files. ```
What should you leave out?
Leave out anything long, obvious, or likely to go stale.
- Whole style guides. Link or summarize.
- Secrets, tokens, and personal data.
- Rules your linter already enforces.
- Vague advice such as "write clean code."
A test: if removing a line would not change the agent’s behavior, remove it. A long file dilutes the rules that matter.
How does AGENTS.md relate to CLAUDE.md?
They serve the same purpose for different tools. If your team uses both Codex and Claude Code, maintain AGENTS.md as the shared source, and let Claude Code read it. Add a CLAUDE.md only for Claude-specific guidance. See our CLAUDE.md guide for what is specific to Claude Code, such as auto memory.
An instruction file is guidance, not enforcement. For rules that must always hold, use permission settings, sandboxing, and review.
How do teams keep it healthy?
Treat it like code: version control, pull-request review, a named owner. When an agent makes the same mistake twice, add a line. When a rule stops applying, delete it. Review the file monthly and run a typical task to confirm the instructions still produce the right behavior.
In training, we have each developer write a first AGENTS.md for their own repository, then run the same task with and without it. Pair it with the safety practices in Codex team training and safety.
What did GitHub learn from thousands of AGENTS.md files?
GitHub’s engineering blog analyzed more than 2,500 repositories’ agent instruction files and reported that the best ones cover six areas: commands, testing, project structure, code style, git workflow, and boundaries. It also found that:
- Commands belong near the top, with the exact flags.
- Examples beat explanations. One real code snippet is worth paragraphs of prose.
- A specific persona helps more than a vague one.
- Boundaries work best as three tiers: always do, ask first, never do.
- "Never commit secrets" was the most common constraint.
Use that as your checklist. The goal is a short, specific file that the agent reads at the start of every session.
What does a starter AGENTS.md template look like?
# AGENTS.md## Role You are a careful contributor to [project]. Prefer small, reviewable changes.
## Commands - Install: [command] - Test: [command] - Lint: [command]
## Project structure - src/ holds [what]. tests/ holds [what].
## Code style - [One or two conventions, with a short example]
## Git workflow - Branch from main. Small commits. Describe why, not only what.
## Boundaries - Always: run tests and lint before finishing. - Ask first: new dependencies, schema changes. - Never: commit secrets, edit generated files, push to main. ```
Treat it like code: review changes, keep it short, and update it when the agent makes the same mistake twice. Claude Code can also read this file; see our CLAUDE.md guide.
Frequently asked questions
Where does AGENTS.md go?
In your repository, typically at the root. Check the documentation of each agent for additional supported locations.
Can I use AGENTS.md with Claude Code?
Yes. Anthropic’s documentation says Claude Code can read AGENTS.md in place of a CLAUDE.md.
Does AGENTS.md guarantee agents follow the rules?
No. It guides behavior. Use permissions, sandboxing, hooks where available, and review for rules that must hold.
How long should it be?
As short as possible while stating the rules the agent would otherwise get wrong.
What is the difference between agent.md and AGENTS.md?
People use both spellings in search, but the widely used file name is AGENTS.md. Use the name your tool documents.
How long should AGENTS.md be?
Short and specific. GitHub’s analysis favors commands, examples, and clear boundaries over long prose.
Sources and further reading
Product features, plans, and limits change often. This guide reflects the vendor documentation listed above as of November 2026. Check the vendor’s current documentation before you make purchasing or policy decisions. TechStack Consulting is an independent training firm and is not affiliated with Anthropic or OpenAI.