What Is AGENTS.md? A Guide for AI Coding Agents

Last verified: September 25, 2026, against agents.md and each tool's own docs.

Most AI coding tools invented their own rules file: CLAUDE.md, .cursor/rules, GEMINI.md, .clinerules. AGENTS.md is the attempt at one shared file that more than one agent can read.

This is for anyone maintaining a repository that more than one AI coding agent touches, and anyone deciding whether to add one to a new project.

What is AGENTS.md?

Agents.md describes it as a README for agents: a predictable place to put the context and instructions an AI coding agent needs to work on a project, separate from the README a human reads. There are no required fields. It is “just standard Markdown,” and an agent parses whatever headings you use.

The format emerged from a collaboration across the AI software development ecosystem, including OpenAI Codex, Amp, Jules from Google, Cursor, and Factory. It is now stewarded by the Agentic AI Foundation, a Linux Foundation project, not owned by a single vendor.

AGENTS.md also tells agents to act on what you list: agents attempt to run the test commands and checks you list, and try to fix failures before finishing a task. That is worth keeping in mind before you add commands to the file, and it is the reason the security section below matters.

What goes in an AGENTS.md file?

Agents.md's own guidance points to a handful of common sections: project overview, build and test commands, code style guidelines, testing instructions, and security considerations. Commit message or pull request rules, deployment steps, and anything you would tell a new teammate fit too.

Here is an original example, not the one from agents.md's own site:

# AGENTS.md

## Project
Next.js app with a Postgres database. Source lives in src/.

## Commands
- Install: npm ci
- Test: npm test
- Lint before every commit: npm run lint

## Conventions
- TypeScript strict mode, no `any`.
- New API routes go in src/app/api/.

## Never
- Edit files under generated/.
- Commit .env files.

Keep it short, specific, and command-first. Vague prose gives the agent nothing to act on.

How do nested AGENTS.md files work in a monorepo?

Agents.md's guidance for large monorepos is to put an AGENTS.md in each package. Agents read the nearest file in the directory tree, so the closest one to the file being edited takes precedence, and every subproject can ship its own instructions. Explicit chat prompts from the user override everything, including the file. Agents.md notes that, at time of writing, the main OpenAI repository has 88 AGENTS.md files.

For example, a repo might look like this:

repo/
  AGENTS.md            # repo-wide: install, lint, commit rules
  packages/
    api/
      AGENTS.md        # API-specific test + migration rules
    web/
      AGENTS.md        # UI conventions
      src/Button.tsx

Under the agents.md rule, editing packages/web/src/Button.tsx means the nearest file, packages/web/AGENTS.md, takes precedence.

One honest caveat: tools differ on whether the root file is also loaded alongside the nearest one. The spec only says the closest file takes precedence, not whether parent files stack on top of it. See how Bodega One Code documents its own merge order later in this post.

Which AI coding tools read AGENTS.md?

Rows sourced to a vendor's docs were checked against that documentation. Rows sourced to agents.md rest on its own listing.

The short version for engines that skip tables: Copilot and Cursor document support outright. Claude Code reads AGENTS.md conditionally. Gemini CLI and Aider need a config line first.

Agents.md also lists Jules, Amp, Factory, Zed, Warp, JetBrains Junie, VS Code, Roo Code, Kilo Code, opencode, Windsurf and Devin from Cognition, among others, as supporting the format; we did not check those against each vendor's own docs.

Pointing Gemini CLI or Aider at AGENTS.md

Gemini CLI, in .gemini/settings.json (an array also works, e.g. ["AGENTS.md", "GEMINI.md"]):

{ "context": { "fileName": "AGENTS.md" } }

Aider, in .aider.conf.yml:

read: AGENTS.md

How is AGENTS.md different from CLAUDE.md?

CLAUDE.md is Claude Code's own instruction file. AGENTS.md is the cross-tool one. Since v2.1.277, Claude Code can read AGENTS.md directly, but the default behavior depends on what else is in the directory tree:

• An AGENTS.md and no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in the working directory or above: Claude reads AGENTS.md.
• An AGENTS.md plus a CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in the working directory or above: Claude reads the CLAUDE.md files only, and AGENTS.md is ignored.
• A CLAUDE.md that already imports AGENTS.md: Claude reads both.

~/.claude/CLAUDE.md, a managed CLAUDE.md, and .claude/rules/ do not count toward that check and keep loading alongside AGENTS.md either way. In subfolders, Claude reads a subfolder's AGENTS.md when it opens a file there and that subfolder has no CLAUDE.md-family file of its own. Claude Code does not read AGENTS.local.md, AGENTS.override.md, or anything under .agents/.

This default can be changed with the Project instructions setting, for example to always read both files. Unlike Copilot and Cursor, Claude Code's AGENTS.md support is conditional, so don't assume it behaves like Codex or Copilot.

Keeping one source of truth for Claude Code and other tools

If you want Claude Code to read the same file as every other agent, keep AGENTS.md as the shared file and add an @AGENTS.md import in CLAUDE.md, with any Claude-only notes below it. For example:

@AGENTS.md

## Claude Code
- Use plan mode for changes under src/billing/.

Is it safe to let an agent follow an AGENTS.md file?

The file lives in the repo, so anyone who can land a pull request can change what your agent is told, and as covered above, agents run the commands it lists.

A few practical habits follow from that. Review AGENTS.md diffs the way you review code; a CODEOWNERS entry on the file is a reasonable way to enforce that. Be careful opening an untrusted repository with an agent that auto-runs commands from it. And watch for instruction files that point outside the project, since that is one way a rules file can be used to reach further than you intended. For a broader look at this class of risk, see our guide to securing AI apps against prompt injection, and our write-up on coding agents and CI secrets.

Does Bodega One Code read AGENTS.md?

Yes, since beta.43 (September 23, 2026). Bodega One Code reads .bodega-rules, AGENTS.md, and CLAUDE.md from the project root on every message, in that order, and uses every one that exists, each under its own header. That is different from Claude Code's either/or default above: Bodega loads all three at once rather than picking one file family over another. The three files share an 8,000-character budget; a file that does not fit is left out whole, never cut mid-file.

Subfolder AGENTS.md files are added outermost first, so the one nearest the edited file has the final word, up to 6 files and 6,000 characters. node_modules and .git are skipped, and a file that links outside the project is refused, the same kind of guard covered in the security section above. This works the same in the app, the CLI, and external ACP agents.

Other editors' own rules files, like .cursorrules or .clinerules, are not read directly; a one-time import appends them into .bodega-rules instead. See the Project Instruction Files section of the getting started docs for the full behavior. For how rules files eat into a local model's context, see our context window planner. Bodega One Code is free for everyone during beta, commercial use included, and there is no Pro price yet; download it here.

Sources

• AGENTS.md: agents.md
• Claude Code memory and AGENTS.md docs: code.claude.com/docs/en/memory
• GitHub Copilot repository custom instructions: docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions
• Cursor rules docs: cursor.com/docs/rules
• Gemini CLI GEMINI.md docs: google-gemini.github.io/gemini-cli/docs/cli/gemini-md.html