What Is AGENTS.md? How to Write One in 2026

Every coding agent has the same first problem. It shows up in your repository, knowing nothing. It doesn't know your build commands, your test runner, your naming conventions, or the three directories it should never touch. You can explain all of that in chat, every session, forever. Or you can write it down once, in a place many modern coding agents know to look.

That place now has a name. AGENTS.md is a simple, open format for guiding coding agents, used by over 60,000 open-source projects, and it has quietly become the closest thing the agent ecosystem has to a shared standard. We've spent the past year watching context files evolve from a single-tool curiosity into table stakes for any team running agents seriously, and this guide covers what AGENTS.md is, how to write one that works, and how it relates to tool-specific files like CLAUDE.md.

What is AGENTS.md?

AGENTS.md is a Markdown file at the root of your repository that gives AI coding agents the context and instructions they need to work on your project. The official spec describes it as "a README for agents": a dedicated, predictable place for build steps, test commands, and conventions. Over 60,000 open-source projects use it, and it's an open format rather than any one vendor's invention.

The reasoning behind a separate file is practical. Your README is written for humans, with quick starts, project descriptions, and contribution guidelines. Agents need different things, like the exact dependency install command, which test filter to run, and the gotchas you'd normally tell a new teammate in their first week. Putting that in the README clutters it for people; leaving it out starves the agent. AGENTS.md splits the difference.

Two details make it more useful than a typical convention. First, there are no required fields. It's standard Markdown with whatever headings you like, and the agent simply parses the text. Second, it's genuinely cross-tool. The official compatibility list includes OpenAI's Codex, Google's Jules and Gemini CLI, Cursor, Aider, Devin, Windsurf, Amp, Zed, Warp, GitHub Copilot's coding agent, Factory, and ten more. Write the file once, and most of the agent ecosystem can read it.

The project also has real governance now. It emerged from a collaboration that included OpenAI Codex, Amp, Jules, Cursor, and Factory, and it's stewarded by the Agentic AI Foundation under the Linux Foundation. That matters if you're betting your team's workflow on a file format. This one won't vanish when a single vendor pivots.

Why coding agents need an AGENTS.md

The case for the file comes down to one behavior. Agents act on it, not just read it.

The clearest example is testing. If you list your test commands in AGENTS.md, compatible agents will attempt to execute those checks and fix failures before declaring a task finished. That single behavior changes the quality of what comes back to you. An agent that knows pnpm test exists is far more likely to ship you a PR where the tests pass; an agent that doesn't ships you code that compiles and hopes for the best.

The second reason is consistency across sessions and across agents. Without a context file, every new session starts from scratch, and each engineer's agent behaves differently because each person explains the project differently in chat. With one, the floor is shared, with the same build commands, conventions, and warnings for everyone. We covered the deeper craft of context files in our CLAUDE.md best-practices guide, and the headline finding applies here too, since models follow focused instruction files more reliably than exhaustive ones, so a tight file beats a sprawling one.

The third reason is the one most teams discover late. You probably don't run just one agent. Maybe engineers use Cursor in the editor, Codex for refactors, and a background agent for ticket work. A tool-specific config helps exactly one of those. An open file helps all of them, which is the entire argument for a standard.

How to write an AGENTS.md file (with example)

There's no schema to memorize. The official guidance is to add sections that help an agent work effectively; popular choices include a project overview, build and test commands, code style guidelines, testing instructions, and security considerations. Here's a compact example in the spirit of the official samples:

# AGENTS.md

## Project overview
Node.js monorepo for the Acme billing platform. TypeScript everywhere.
Services live in /services, shared libraries in /packages.

## Setup commands
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run all tests: `pnpm test`

## Code style
- TypeScript strict mode
- Single quotes, no semicolons
- Prefer functional patterns; avoid classes for new code

## Testing instructions
- CI config lives in .github/workflows
- Run `pnpm vitest run -t "<test name>"` to focus a single test
- The commit should pass lint and all tests before merge

## Security considerations
- Never commit .env files or anything in /secrets
- Payment code in /services/billing requires a human review tag

## PR instructions
- Title format: [<service>] <description>
- Always run `pnpm lint` and `pnpm test` before committing

A few rules of thumb that separate files agents follow from files agents ignore:

• Write commands, not prose. "Run pnpm test" beats "we have a comprehensive testing strategy." Agents act on the former.
• Tell it what you'd tell a new teammate. Commit message format, PR conventions, deploy quirks, and the directory nobody should touch. The spec is written in exactly this spirit.
• Keep it tight. Style minutiae belong in your linter, not your context file. Models follow focused instruction files more reliably than exhaustive ones, a point we documented in the CLAUDE.md guide, so spend that budget on architecture and commands rather than semicolon rules.

For monorepos, nest the files. Agents read the nearest AGENTS.md in the directory tree, so the closest file takes precedence, and every package can carry its own instructions. This scales further than you'd think. Large monorepos carry many nested AGENTS.md files, one per package. The main OpenAI repo had 88 of them when the standard's own site was written.

And when instructions collide? The spec's precedence rules are short and sensible. The AGENTS.md file closest to the edited file wins, and explicit user chat prompts override everything. Your file sets the defaults; the human in the loop keeps the steering wheel.

AGENTS.md vs CLAUDE.md (and other tool-specific files)

This is the question we hear most, and the answer is less either-or than people expect.

CLAUDE.md is Claude Code's native context file, a Markdown file in your project root whose contents are automatically included at the start of every Claude Code conversation. It plays the same role AGENTS.md plays, but for one tool, and per-tool files like it are exactly the fragmentation the open standard set out to end. Notably, the official AGENTS.md compatibility list spans most major agents, but Claude Code isn't on it; Anthropic's tooling reads CLAUDE.md.

In practice, the most straightforward setup for most teams is:

Keep the substance identical between them so no agent works from stale instructions, and let each file carry only the tool-specific extras. Some tools also make adoption a config switch rather than a convention. Aider reads AGENTS.md with one line in .aider.conf.yml, and Gemini CLI accepts it via a context file-name setting. The official site even documents a one-line symlink pattern for migrating older file names without breaking anything.

If you only maintain one file today, make it the open one, and mirror it for the tools that need their own.

One file, every agent: AGENTS.md at team scale

Here's where the standard stops being a documentation nicety and starts being infrastructure. The entire value of AGENTS.md is that your project's operating manual is no longer tied to a single tool, and that matters most when your team stops being a single-tool shop.

That moment arrives fast. Most teams we work with end up running several agents: one in the editor, one in the terminal, and background agents that handle tickets and scheduled jobs. The background agent layer is where Tembo lives. It runs Claude Code, Cursor, Codex, Gemini, or OpenCode as background agents off your Slack messages and Linear tickets. Tembo can use repo-level instruction files, such as CLAUDE.md, as part of the context you provide to agents working on your codebase. One well-written AGENTS.md (mirrored to CLAUDE.md for Claude Code) means every one of those agents, in every session, starts with the same understanding of your project. Swap the underlying agent next quarter, and your instructions come along for free.

That's also the strongest argument for investing an hour in this file: it's the only piece of your agent setup that's guaranteed to survive every tool change. For more on running multiple agents against one set of instructions, see our guide to coding agent orchestration.

Best practices (and the mistakes that break the file)

Commit it to the repo. The file only works if every engineer and every agent sees the same version. Treat it like code: review changes, keep it under version control, and update it when the architecture changes. It's living documentation, not a one-time setup step.

Start small and grow from evidence. Begin with setup commands, test instructions, and your two or three most violated conventions. When an agent gets something wrong twice, that's your signal to add a line.

Don't auto-generate it and walk away. A generated file tends to include everything except the things that matter most, like the architectural decisions and constraints that appear nowhere in the code. We made this argument at length for CLAUDE.md, and it goes double for a file that a dozen different agents will obey.

Don't duplicate your linter. If ESLint or Ruff enforces it, one line ("style is enforced by the linter; fix what it reports") outperforms forty rules the agent may drop anyway.

Watch for drift. An AGENTS.md that references a deleted script is worse than no file, because agents will confidently run commands that no longer exist. A quarterly review alongside your docs is enough for most teams.

Make the file once, benefit everywhere

AGENTS.md earns its place in your repo the same way a good README does. It answers the questions every newcomer asks, except the newcomer is an agent and it arrives a hundred times a day. Write the commands down, set the boundaries, nest files where the monorepo demands it, and mirror the content into CLAUDE.md for Claude Code. An hour of writing buys you consistency across every agent you run today and every one you'll try next quarter.

And if you're at the stage where multiple agents are doing real work across your repos, that's the problem Tembo was built for. Start free and point any agent you like at the context file you just wrote.

FAQ

What is AGENTS.md for? It's an open Markdown format that gives AI coding agents a predictable place to find your project's build commands, test instructions, conventions, and warnings. Think of it as a README for agents; over 60,000 open-source projects use it.

Is AGENTS.md the same as CLAUDE.md? They serve the same purpose, but AGENTS.md is the cross-tool open standard while CLAUDE.md is Claude Code's native file. Claude Code isn't on the official AGENTS.md compatibility list, so most teams keep both files identical in content.

Should AGENTS.md be committed to the repository? Yes. The file lives at the repo root, with optional nested files for monorepo subprojects. Committing it is the point, since every agent and engineer works from the same instructions, and changes get reviewed like any other code.

Are there required fields in AGENTS.md? No. It's standard Markdown with any headings you like. Popular sections include project overview, build and test commands, code style, testing instructions, and security considerations.