How to Write an AGENTS.md File Your Coding Agent Will Actually Follow

Last month, Anthropic quietly surrendered. On September 18, Claude Code version 2.1.277 shipped with support for AGENTS.md — the instruction-file format invented by OpenAI's Codex team. If no CLAUDE.md exists in a folder, Claude now checks for AGENTS.md and follows it. The rival lab adopted its competitor's standard, and it had little choice: more than 60,000 open-source projects had already adopted the format, and Shopify's CEO had threatened a company-wide ban on Claude Code unless it started reading the same file as everyone else.

That file is the single most effective change you can make to your AI coding workflow. Your agent doesn't fail because the model is bad — it fails because it doesn't know where it is.

The problem isn't your prompt

A prompt is an instruction for a single task. Context is everything the agent uses to interpret that instruction. When you tell it "add tests," it has to guess: which testing library? Which folder? What naming convention? Without context, it guesses — and often wrong.

AGENTS.md removes the guesswork. It doesn't compete with your prompt; it makes it shorter and more precise. The prompt tells it what to do. AGENTS.md tells it how things are done here.

GitHub found the same thing empirically: analyzing more than 2,500 repositories, the recurring lesson was that specific, runnable commands beat vague prose. An agent can execute npm test. It cannot act on "make sure your changes work."

The four things that belong in the file

Every good AGENTS.md covers four things: commands, tests, style, and boundaries. No philosophy, no wish lists — just concrete instructions the agent can follow directly. Here is a complete example for a TypeScript project:

# TaskFlowAPI
Task management backend built with Node.js, TypeScript, and PostgreSQL.

## Setup & Commands
- Install: `pnpm install` (we use pnpm, never npm or yarn)
- Dev server: `pnpm dev`
- Run tests: `pnpm test`
- Lint and type check: `pnpm lint && pnpm typecheck`

## Coding Standards
- TypeScript strict mode, no exceptions
- Named exports only — no default exports
- Prefer async/await over raw promises

## Testing
- Use Vitest, not Jest
- Add or update tests for any code you change, even if unasked
- Integration tests use a throwaway Docker Postgres, not mocks

## Boundaries
- Ask before adding any new production dependency
- The `/legacy` folder is frozen pending a migration tracked in ticket X
- Never commit secrets, tokens, or .env files
- Do not modify generated files (*.gen.ts)

Notice what isn't there. No explanations of why Vitest is better, no long justifications. The agent doesn't need persuasion — it needs a rule. The shorter and more concrete the rule, the better it works.

The boundaries section is the one people skip and shouldn't — agents are eager to clean up code you didn't ask them to touch. And the /legacy line includes the why, which gives the agent a reason to respect the boundary instead of questioning or ignoring it.

What to leave out

A bloated AGENTS.md is an ignored AGENTS.md. The three files on your repo serve three different audiences, and duplicating between them is the fastest way to make the agent stop trusting the instructions:

• README.md is for humans new to the project — intro, quickstart, links, welcoming tone.
• CONTRIBUTING.md is for human contributors — the process for filing issues and opening pull requests.
• AGENTS.md is for AI coding agents — operational instructions, written imperatively, to produce correct code.

The decision rule is simple: if an AI agent needs it to write correct code, it belongs in AGENTS.md. Cross-reference instead of duplicating.

Two things in particular don't belong. First, anything your linter or CI already enforces — reserve the file for judgment calls a static tool can't make: which of two valid approaches this codebase prefers, which directories are off-limits, what the deploy sequence is. Second, marketing. "We build world-class software" is noise. A good rule of thumb: if the file grows beyond a page — roughly 200 to 500 lines — something is too much. Remove what the agent already gets right, and use nested AGENTS.md files in monorepo subfolders for package-specific rules. The agent reads the closest file first, so the package gets its own rules on top of the general ones.

Treat it as a living document

Don't try to write the perfect file on day one — that's the fastest way to give up. Start small, in about thirty minutes:

1. Write the file. Add your build, test, and lint commands. This alone solves most of the errors.
2. Verify every command yourself. An AGENTS.md full of commands that don't work is worse than no file at all.
3. Run a real session. Give the agent a refactor or a new endpoint and watch whether it follows the file.
4. Test a guardrail on purpose. Ask the agent to do something your file forbids. If it complies, the rule is too vague — rewrite it as a hard constraint.

Then keep the freshness loop going. Commit the file to git and review it monthly. And the real growth mechanism: every time the agent repeats a mistake, log the fix in the file. One correction that turns into a rule is a correction you never make again. A useful heuristic: if you'd repeat an instruction across sessions, it belongs in AGENTS.md. If you'd only say it once, it belongs in the prompt.

Why this file won

AGENTS.md started in OpenAI's Codex team in 2025. That December, OpenAI donated it to the Agentic AI Foundation — a new body under the Linux Foundation — as one of three anchor projects, alongside Anthropic's Model Context Protocol and Block's goose agent. Today it's read by Codex, Cursor, GitHub Copilot, Google's Jules and Gemini CLI, Devin, Zed, Warp, VS Code, Aider, and others, across more than 60,000 open-source repositories (self-reported, but consistent with how quickly the tool list grew).

Before the format existed, every tool invented its own: .cursorrules, CLAUDE.md, .github/copilot-instructions.md. Teams using two tools maintained two files that drifted out of sync. The pressure for one format turned public in late August 2026, when Shopify's CEO said he was weighing a company-wide ban on Claude Code unless it read AGENTS.md — a directory missing the file left part of his team "working with half a brain." Weeks later, Anthropic's Thariq Shihipar announced the support, and OpenAI's Thibault Sottiaux replied: "Yay! This is the way. Come to the light."

That history is why the file matters more than any single prompt trick. One maintained file now programs the agent's behavior across every tool on your team — it is the agent's only permanent memory. Write it like documentation and you've added a paragraph to a manual. Write it like code and you've given a teammate a brain.

Do one thing today

Create an empty AGENTS.md at your repo root and add your project's build and test commands to it. It's a five-minute job. Then give the agent a standard request with no extra instructions and see whether it hits the mark. If it does, your file is working. If it doesn't, you've just found the next line to add.

References

• Anthropic decides to support OpenAI's markdown instructions spec — The Register, 2026-09-18
• OpenAI & Anthropic Launch Agentic AI Foundation — TechProvidence, 2026-10-13
• What Is AGENTS.md? A Guide for AI Coding Agents — llms-txt.io, 2026-10-17
• Claude Code 2.1.277 Adopts OpenAI-Backed AGENTS.md — COINOTAG, 2026-09-19
• How to write your AGENTS.md — Michaela Minds, 2026-07-11
• Why Your Coding Agent Keeps Making the Same Mistakes — AGENTS.md Fixes It — dev.to, 2026-08
• AGENTS.md Complete Guide for Engineering Teams (2026) — buildbetter.ai
• AGENTS.md Guidelines — Best practices for AI coding assistant instruction files — GitHub gist (2,500+ repos analysis)
• AGENTS.md Explained: Format, Setup, and Tool Support (2026) — ayautomate.com