AGENTS.md is a plain Markdown file in a repository that gives coding agents project-specific instructions. It keeps guidance such as build commands and coding conventions next to the code, so you do not have to repeat it in every prompt.
For example, suppose a Python billing service stores money as integer cents. A root AGENTS.md can tell every agent to run uv run pytest tests/test_billing.py -q, to never use floats for amounts, and to never hand-edit files under src/generated/. A coding agent that supports the convention reads those rules before it changes any code.
Build better agents with Arize
Trace, evaluate, and learn. Build agents that work with Arize AX and start tracing your runs today.
Prefer open source? Try Arize Phoenix for self-hosted, open source agent observability.
Why AGENTS.md matters for coding agents
A coding agent starts each task knowing nothing about your project. Without written guidance, it has to guess your test command, your conventions, and which files are off limits.
AGENTS.md is useful for:
- Sharing commands: Tell the agent how to install, test, and lint, so it does not guess.
- Enforcing conventions: State rules the agent would otherwise break, such as how money is stored.
- Protecting files: Mark generated or vendor files that must not be edited by hand.
- Setting review expectations: Describe what the agent must check and report before it finishes.
The file is written for agents, but maintainers read and edit it like documentation. Changes go through a normal pull request.
For more on how coding agents operate, see coding agent.
How AGENTS.md works
The agents.md site describes the open convention. A repository places one or more AGENTS.md files in its tree. A coding agent working in a directory applies the nearest applicable file, and the root file covers the whole project.
Scope is based on directories. A nested file guides work in its own subtree. Depending on the tool, it can narrow or override the broader guidance in the root file.
Typical contents include:
- Build and test commands
- Language and style conventions
- Architecture notes that are expensive to rediscover
- Pull request expectations
- Explicit “do not” rules, such as generated files that must not be edited by hand
What is left to each tool
The file is ordinary Markdown with no required schema. This makes adoption cheap and the content easy to review.
The trade-off is that each tool decides how to interpret it. Heading structure, length limits, and how multiple files merge are defined by the consuming agent, not by the file. So is whether a nearer file overrides a parent file or only adds to it.
Before you rely on a subtle override, check how the exact tool and version you use handles precedence and truncation.
How to write an AGENTS.md file
Here is a root file for the Python billing service from the example above.
# Contributor guide for agents
## Commands
- Install: `uv sync`
- Test one file: `uv run pytest tests/test_billing.py -q`
- Lint: `uv run ruff check .`
## Conventions
- Money is stored as integer cents; never use floats for amounts.
- Do not edit files under `src/generated/`; regenerate with `make gen`.
## Before finishing
- Run the tests for every module you changed and report failures plainly.
Each line tells the agent something it cannot guess or would otherwise get wrong. The commands save the agent from searching. The conventions prevent a specific class of bug.
Add a nested file for a subdirectory
Now suppose the payments code has stricter rules. A nested services/payments/AGENTS.md could add the payments-specific test command. It could also note that refund logic requires a second reviewer.
For a payments task, the agent’s context then combines several layers. These are the system and user instructions, the root file, and the nearer payments file. Every layer takes up space, which is why each one should stay short.
Keep the file short and current
Write as little as still changes behavior. Include the commands an agent cannot guess, the conventions it would otherwise violate, and the checks it must run.
Stale instructions are followed just as confidently as correct ones. If a command changes, update the file in the same pull request.
How to debug an ignored instruction
When an agent ignores a rule in AGENTS.md, check these causes in order:
- Scope: Confirm the file is in the directory scope the tool actually reads.
- Support: Confirm the tool version supports nested files.
- Conflicts: Check whether a nearer file or a higher-priority instruction contradicts the rule.
- Length: Check whether the tool truncated the file because it was too long.
Tracing what the agent did makes these failures visible. A trace shows which commands the agent ran and which files it opened. The Phoenix documentation covers the broader tracing workflow.
For more on the system around the agent, see agent architecture and harness engineering.
How to measure whether AGENTS.md helps
Treat an edit to the file like any other change to an agent. Run a fixed set of repository tasks before and after the edit, with the same model and tooling.
Then compare three things:
- Task completion: How many tasks the agent finished.
- Test pass rate: How often the agent’s changes passed the test suite.
- Corrective follow-ups: How many times a person had to step in and redirect the agent.
Change only the file during the comparison. If you change the file and the prompt at the same time, you cannot tell which one caused the difference.
Limitations of AGENTS.md
- It cannot enforce anything: The file cannot stop an agent from running a command the environment permits. Permissions and sandboxing must do that work.
- It is not a security boundary: Treat it as guidance, not as access control.
- Long files dilute attention: More text increases the chance that the agent misses a rule or finds two rules that contradict each other.
- Instructions go stale: Commands and conventions change. Maintain the file like code, with owners and review.
- Precedence is tool-defined: The order between system, user, root, and nested instructions varies. A rule that works in one coding agent may be advisory or ignored in another.
AGENTS.md vs. CLAUDE.md and skills
CLAUDE.md is a vendor-specific instruction file with the same basic purpose. AGENTS.md is the cross-tool convention described at agents.md.
Projects often keep one canonical file and symlink or generate the other. Even so, do not assume the two behave the same. Loading, precedence, and memory features belong to each tool and change over time.
Skills are a different kind of thing. A skill packages instructions with optional scripts and resources, and an agent loads it on demand for one type of task. An instruction file like AGENTS.md is repository guidance that is always on.
For more on skills, see agent skills. For the action mechanism these instructions ultimately steer, see tool calling.
Frequently asked questions
Where should I put AGENTS.md?
Put it at the repository root for project-wide guidance. Add files in subdirectories only where conventions genuinely differ. Do not create nested files that just repeat the root file.
Does AGENTS.md work in every coding agent?
No. Support, merge order, and length handling differ by tool and by version. Check the current documentation for the agent you run, and check again after major upgrades.
Should secrets or credentials go in AGENTS.md?
No. The file is committed documentation that many people read. Keep credentials in the environment or a secrets manager, and describe the mechanism, not the values.
How long should AGENTS.md be?
As short as it can be while still changing behavior. If a line would not change what the agent does, consider deleting it.
Why does my agent ignore a rule in AGENTS.md?
The most common causes are scope, tool support, a conflicting instruction, or truncation. Check them in that order, and use a trace of the agent’s actions to see what it actually read and ran.
Putting AGENTS.md to work
Start with a short root file that lists your install, test, and lint commands and the few conventions agents get wrong. Add nested files only for directories with genuinely different rules.
Review the file in pull requests like code, and update it whenever a command changes. When you edit it, rerun a fixed set of repository tasks to confirm the change helped.
Keep enforcement in permissions and sandboxing, not in the file. Tools such as Arize Phoenix can trace an agent’s commands and file reads, which shows whether it followed the instructions you wrote.
