AGENTS.md File for Coding Agents: How It Works With CLAUDE.md

AGENTS.md File for Coding Agents: How It Works With CLAUDE.md

An AGENTS.md file for coding agents is a Markdown file at the root of a repository that collects instructions for AI coding tools: how to install dependencies, run tests, follow conventions and what to avoid. It works like a README written for the agent, and several tools already read it. Claude Code reads CLAUDE.md, so the simplest way to keep a single source of truth is to write everything in AGENTS.md and have CLAUDE.md point to it.

Key takeaways

• AGENTS.md is a simple, open format: plain Markdown, no required fields, versioned alongside the code.
• CLAUDE.md plays a similar role inside Claude Code. The two do not replace each other automatically, but they can share the same content.
• A single source avoids instructions that drift apart between tools and reduces the maintenance work for your team.
• The file should hold verifiable commands, conventions and limits, not generic advice about "being a good programmer."
• Instructions in a file guide the agent, but they do not replace permissions, a sandbox and human review.

What is AGENTS.md and what is it for?

Every coding assistant needs context about a project before it can act well. Which command runs the tests? Which package manager is used? Where do migrations live? Which folders must not be edited? Without those answers, the agent guesses, and guessing costs review time.

AGENTS.md solves this with a predictable place to put the answers. The idea, as described on the format's own website, is that the README keeps talking to people while AGENTS.md talks to agents, with details that would clutter a human read, such as exact build steps and style rules.

The format is deliberately light. There is no rigid schema: it is headings and lists in Markdown. In repositories with many folders you can also place nested files in subfolders, and the convention is that the file closest to the code being edited takes precedence. This helps in monorepos, where the payments service and the mobile app follow different rules.

The point that matters most for the person making the decision: the file lives in the repository. It goes through pull requests, has a history and has an owner. Instructions nobody reviews go stale and end up misleading the agent.

How does AGENTS.md relate to CLAUDE.md?

CLAUDE.md is the project memory file in Claude Code. It is loaded at the start of sessions and carries persistent instructions. The Claude Code memory documentation describes the levels at which these files can exist (project, user and others) and the option to import other files using the at-sign syntax.

In practice, the relationship is this: AGENTS.md is a format shared across many tools, and CLAUDE.md is the name Claude Code looks for. If a repository has only AGENTS.md, you should not assume Claude Code will depend on it by itself. Check the current behavior in the documentation for the version your team uses, because tools change.

There are three common arrangements:

• Two independent files. Simple at first, but the instructions drift apart within a few weeks.
• A symbolic link from CLAUDE.md to AGENTS.md. It works well on Linux and macOS, but it can cause friction for teams on Windows or in some CI workflows.
• A short CLAUDE.md that imports AGENTS.md. This is the most portable option: CLAUDE.md contains one import line and, if needed, instructions that apply only to Claude Code.

For most teams, the third option is the safest. Shared content stays in AGENTS.md, and CLAUDE.md holds only what is specific to the tool, such as references to skills or Claude Code settings. For that second group, see Claude Code Skills.

What should you write in the file, and what should you leave out?

The file is read in every session, so it takes up space in the model's context window. Too much text dilutes what matters. Anthropic's engineering material on context engineering makes this point: the goal is to provide the smallest set of information that actually guides behavior. To understand the limit in plain terms, read about the context window.

What is usually worth including:

• Exact commands to install, build, run tests and run the linter, with the directory to run them from.
• Project structure in a few lines: what each main folder contains.
• Conventions the linter does not catch, such as file names, commit format and the style of error messages.
• Clear limits: generated folders, files that must never be edited, migrations that require approval.
• A definition of done: which checks must pass before the agent says it has finished.
• How to handle sensitive data: do not paste real customer data into tests, use fictitious data, respect data protection law (LGPD in Brazil).

What to leave out:

• Secrets, tokens and passwords. The file is versioned and read by different tools.
• Long architecture descriptions that already exist in their own documentation. Point to that document instead.
• Vague rules such as "write clean code." If it cannot be verified, the agent cannot follow it consistently.
• Instructions that change every week. Those belong in a task, not in the permanent file.

A good writing rule: every line should answer a real mistake that has already happened or a question the agent would have. If it answers neither, the line can probably go.

How to keep a single source of instructions, step by step

This is an adoption plan that fits in an afternoon for a small repository and in a short pilot for several.

• Take inventory of what exists today: look for CLAUDE.md, editor rules files, copilot instructions and loose snippets in the README. List what each one says.
• Consolidate into one AGENTS.md at the root, removing duplicates and contradictions. When two instructions conflict, decide with the technical owner and record the decision.
• Create a short CLAUDE.md that imports AGENTS.md and keep only Claude Code specifics in it.
• For the other tools your team uses, check each one's documentation to confirm whether it reads AGENTS.md. If one requires a different file name, prefer a reference or an automated sync step over copying text by hand.
• Define an owner and a review rule: changes to AGENTS.md go through a pull request like any other code.
• Test with small, real tasks: ask each tool to run the tests and make a simple change. Check whether all of them followed the same commands and conventions.
• Review after a few weeks: remove what nobody used and add the recurring mistakes the agent made.

If your team is still choosing tools, the article on Claude Code vs Cursor vs GitHub Copilot helps compare criteria. A single source of instructions lowers the cost of switching or combining tools later.

Illustrative scenario: a team with three assistants

Imagine a small software house that serves retailers. One developer uses Claude Code, another prefers an editor with a built-in agent, and a third uses the GitHub assistant. Each wrote their own instructions. In the same repository, one assistant runs the tests with one command, another uses an outdated command, and the third formats code in a different style. Pull request reviews fill up with style fixes.

The team decides to consolidate. They create an AGENTS.md with the correct commands, the folder structure, the commit format and a list of files that must not be edited. CLAUDE.md now imports that file. Then the team gives each tool the same small task and compares the results. The remaining differences show what is still missing from the file.

This is an illustrative scenario with no measured results. What it shows is the mechanism: the same instruction, in one place, reviewed by people.

Instructions in a file are not access control

A common mistake is to treat AGENTS.md as a security fence. Writing "never delete the production folder" is useful, but it is only guidance. The model may follow it, forget it, or be pushed to ignore it, for example by malicious text in a file or web page it reads. The OWASP guidance on preventing prompt injection explains why instructions and untrusted data get mixed together and why defense needs layers.

For that reason, anything critical should be enforced outside the text:

• Tool permissions set to deny destructive commands and reading of secret files.
• A sandbox or isolated environment for execution.
• Human approval for irreversible actions such as deploys, migrations and deletions.
• Least-privilege credentials in the agent's environment, never production ones.

The article Claude Code Security: Permissions, Sandbox and Secrets for Teams covers permissions, sandboxing and secret handling in detail. AGENTS.md states what is expected; configuration prevents what must not happen.

There is also a privacy point. If the repository handles customers' personal data, the file should make clear that real data does not go into tests, prompts or logs. That does not satisfy data protection law on its own, but it records the internal rule your team can audit.

How the map, limit, pilot and hand-over method applies

The same reasoning we use for customer support agents applies to coding agents. Map: understand how the team works today, which tools it uses and where instructions are scattered. Limit: define what the agent can read, run and change, using permissions and not only text. Pilot: choose one repository and one real task, with an agreed success criterion, for example that the tests pass without manual style fixes. Hand over: leave the file with an owner, a review rule and an explicit decision to expand, adjust or stop.

There is no promise of gains here. What you are after is predictability: the agent behaving similarly in any tool, and the team knowing why.

Frequently asked questions

Does AGENTS.md replace the README? No. The README remains the front door for people, with an overview and usage instructions. AGENTS.md complements it with operational details for agents, such as exact commands and editing rules, which would be too much for a human reader.

Does Claude Code read AGENTS.md directly? The stable reference in Claude Code is CLAUDE.md. That is why the recommended practice is to create a CLAUDE.md that imports AGENTS.md rather than assuming direct reading. Because tool behavior changes, confirm it in the documentation for the version you use.

Can I have AGENTS.md files in subfolders? Yes, and it is useful in monorepos. The convention is that the file closest to the code being edited takes precedence over the root one. Keep nested files short and limited to what differs from the main file, to avoid conflicts.

Who should maintain AGENTS.md? Name one responsible person, usually whoever looks after the repository's technical quality, and use pull requests for every change. Review the file when the agent repeats a mistake or when project commands change. Outdated instructions are worse than no instructions.

Sources

• AGENTS.md: site oficial do formato
• Claude Code: documentação sobre memória e CLAUDE.md
• Anthropic: Effective context engineering for AI agents
• OWASP: prompt injection prevention