What Is AGENTS.md? A Beginner’s Guide to the AI Coding Agent Instructions File

What it is: A plain-English guide to AGENTS.md — the open Markdown file standard that AI coding agents like Codex, Cursor, and GitHub Copilot read at the start of every session to learn your project’s rules.
Who it is for: Anyone using AI coding agents on a real project. You don’t need to be a senior engineer, but you should be comfortable editing a Markdown file at your repo root.
Best if: You want a complete walkthrough — what AGENTS.md is, who reads it, what goes in it, and a copy-paste sample you can adapt today.
Skip if: You haven’t used an AI coding agent yet. Start with How to Use AI and Claude Code Beginners Guide first. Want one practical AI workflow every morning? Subscribe to our free daily newsletter.

What is AGENTS.md?

AGENTS.md is a plain Markdown file you put at the root of your code project. AI coding agents read it automatically at the start of every session and use it as a project-specific instruction manual — how to run the code, how to run the tests, what conventions to follow, and what NOT to touch.

The format is intentionally simple. There’s no schema, no required fields, no YAML front-matter. Just standard Markdown headings. The official spec at agents.md describes it as “a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project.”

The format emerged from a collaboration between OpenAI Codex, Amp (Sourcegraph), Jules (Google), Cursor, and Factory, and is now stewarded by the Agentic AI Foundation under the Linux Foundation. As of May 2026, over 60,000 open-source projects use AGENTS.md, and OpenAI’s own main repo contains 88 nested AGENTS.md files.

Why does AGENTS.md exist?

Without a project-level instructions file, every AI coding agent has to figure out the same things on its own: where the source code lives, how to build it, which test command to run, what the team’s conventions are, which files are auto-generated and shouldn’t be edited. The agent guesses, and the guesses are sometimes wrong — which is one of the most common reasons agents fail (see our Why AI Coding Agents Fail guide for the full list).

AGENTS.md fixes this. It puts the answers in a predictable place every agent knows to look. A good AGENTS.md is the single highest-leverage thing you can do to make AI coding agents work reliably on your project — bigger than upgrading the model, bigger than switching tools.

There’s also a coordination benefit. Before AGENTS.md, every major AI coding tool wanted its own special config file (Anthropic had CLAUDE.md, Cursor had .cursorrules, others had their own). Developers were maintaining three or four parallel files. The whole industry converging on one open standard means you write the file once and every supported tool reads it.

Which AI coding agents read AGENTS.md?

As of May 2026, the supported-tools list on agents.md includes essentially every major agent except Claude Code:

• OpenAI Codex and Codex CLI — native; the format’s originator.
• GitHub Copilot — native AGENTS.md support across the agent surface.
• Cursor — native.
• Google Jules and Gemini CLI — native.
• Cognition Devin, Windsurf, Amp, Aider, goose, Factory, RooCode, Augment Code, Phoenix, Semgrep — native.
• JetBrains Junie, Warp, opencode, VS Code, Zed, UiPath Autopilot — native.

The one major holdout is Claude Code, which still reads CLAUDE.md rather than AGENTS.md natively. Anthropic has had a feature request open for AGENTS.md support since August 2025 (claude-code issue #6235) but it’s not merged yet. The standard community workaround is a single shell command at your repo root:

ln -s AGENTS.md CLAUDE.md

That creates a symlink, so Claude Code reads the same file as every other agent. One file, every tool.

What’s the difference between AGENTS.md, CLAUDE.md, and README.md?

This is the most common question for beginners. Here’s the clean breakdown:

• README.md is for humans. It explains what the project is, how to install it, and how to use it. New contributors read it. Your future self reads it.
• AGENTS.md is for AI agents. It holds the operational detail an agent needs to do real work in your repo — commands to run, conventions to follow, files to leave alone. Most agents read this file at session start.
• CLAUDE.md is the Anthropic-specific equivalent of AGENTS.md. Same purpose, same kind of content, but Claude Code is currently the only major tool that reads it as the primary source. Most projects with both files just symlink them so they stay in sync.

README and AGENTS are siblings, not replacements. Keep the README focused on the human story (what does this project do, how do I get started, what’s the license). Move the operational density (every command, every convention, every gotcha) into AGENTS.md where the agents will actually use it.

What goes in a good AGENTS.md?

Working AGENTS.md files in 2026 all converge on roughly the same eight sections. None are required by the spec — you can include or skip any — but agents perform best when they find these answers in this order.

• Project overview. One paragraph: what this codebase does, what language and framework it uses.
• Setup commands. Exact, copy-pasteable. Don’t write “install dependencies” — write uv sync or pnpm install.
• Run commands. How to start the dev server, the worker, the CLI — whatever makes the project actually run.
• Test commands. One line per test type. Include a fast smoke-test command so the agent can verify after every change.
• Code style / conventions. Name the linter (ruff, eslint, biome). Name the formatter. State the rules a generic agent wouldn’t guess.
• Folder map. Three to six bullets: which folder holds what. Helps the agent reuse existing utilities instead of writing duplicates.
• Do not touch. Generated files, vendored code, legacy modules scheduled for removal, sacred files that break things if edited. The agent won’t know unless you tell it.
• Commit / PR conventions. Conventional Commits, branch naming, required CI commands — whatever your team enforces.

Keep the first version under 2 KB. Expand only when an agent gets something wrong because of missing information. The Thoughtworks Technology Radar specifically warns about AGENTS.md bloat — once a file passes a few KB, agents start losing signal in the noise.

What does a real AGENTS.md look like?

Here’s a complete sample you can copy, paste, and adapt. It’s a Python web project but the structure works for any language.

# AGENTS.md

## Project
Flask API serving the customer dashboard. Python 3.12, PostgreSQL 16.

## Setup
- `uv sync` installs dependencies
- Copy `.env.example` to `.env` and fill in values
- `make db-up` starts the local Postgres container

## Run
- `make dev` — runs the API at localhost:8000 with hot reload
- `make worker` — runs the background job processor

## Test
- `pytest` runs the full suite
- `pytest tests/unit` for unit tests only
- All new code must include tests in tests/unit or tests/integration

## Conventions
- Format with `ruff format`, lint with `ruff check`
- Type hints required on all public functions
- Import order enforced by ruff
- No `print()` — use the `logger` from `app.logging`

## Folder map
- `app/` — application code
- `app/api/` — HTTP route handlers
- `app/services/` — business logic (route handlers stay thin)
- `migrations/` — Alembic migrations, never edit historical ones
- `tests/` — pytest tests, mirror the `app/` structure

## Do not touch
- `migrations/versions/*` once committed
- `app/legacy/` — scheduled for removal Q3 2026
- Any file under `vendor/`

## Commits
- Conventional Commits format: `feat:`, `fix:`, `chore:`, etc.
- One logical change per PR
- Run `make ci` locally before opening a PR

That’s about 1.5 KB. It’s the right starting size. Replace the Python-specific bits with whatever your project uses and you have a working AGENTS.md in 15 minutes.

How does AGENTS.md work in a monorepo?

If you work in a monorepo, the AGENTS.md spec has a clean answer. You put a top-level AGENTS.md at the git root, then optional nested AGENTS.md files in each sub-project’s directory. When the agent runs, it walks from the git root down to the current directory, concatenating each AGENTS.md it finds along the way.

Two important rules:

• Closer files override further ones. If your root AGENTS.md says “use 2-space indentation” but the AGENTS.md inside `packages/api/` says “use 4-space indentation,” the API package wins inside that folder.
• Codex caps the combined load at 32 KiB. The Codex docs publish this limit (project_doc_max_bytes). Past that, instructions get truncated. So even with monorepos, brevity matters.

OpenAI’s own main repo uses this pattern: 88 nested AGENTS.md files across the tree, each adding only the instructions specific to that subdirectory.

What are the most common AGENTS.md mistakes?

• Too long. The “1,000-page manual” failure mode. Past 32 KiB Codex truncates; past a few KB most agents lose signal in the noise. Hand-written 1.5 KB beats LLM-generated 30 KB every time.
• Too vague. “Follow best practices” is useless. The agent already does that — the question is your conventions. Name the linter. Name the test command. Name the import-order rule.
• Pasting secrets. AGENTS.md is read by every agent, often uploaded to the cloud as context. Never paste API keys, tokens, or .env contents in it. Reference the environment variable name only.
• Drift. AGENTS.md goes stale when commands change. Treat it like code — review it during onboarding passes, add it to your code-review checklist when build or test commands change.
• Letting an LLM write it for you. The Thoughtworks Tech Radar found that hand-written AGENTS.md files outperform LLM-drafted ones. An LLM doesn’t know your team’s actual conventions; it generates plausible-sounding generic advice that doesn’t match how you work.

How do you write your first AGENTS.md in 30 minutes?

Nine concrete steps. The order matters — setup and test commands deliver the most value, so do those first.

• Step 1. Create AGENTS.md at the root of your repo. Empty file.
• Step 2. Add a one-paragraph project description. What it does, what language, what framework.
• Step 3. Add the exact install and setup commands. Copy-pasteable.
• Step 4. Add the run commands — how to start the dev server, the worker, the CLI.
• Step 5. Add the test command. If you have one. (If you don’t, that’s a bigger problem than AGENTS.md.)
• Step 6. Add three to five “do not touch” bullets — generated files, vendored code, legacy modules.
• Step 7. Add three to six folder-map bullets — where the main parts of the codebase live.
• Step 8. Add one line on commit/PR conventions.
• Step 9. If you use Claude Code, run ln -s AGENTS.md CLAUDE.md so Claude reads the same file.

Keep the whole file under 2 KB on the first pass. Resist the urge to be exhaustive. The right time to add a new section is the first time an agent gets something wrong because it didn’t know — then you add the one line that would have prevented the mistake.

What’s the Thoughtworks Tech Radar take?

The Thoughtworks Technology Radar is one of the most-read enterprise engineering reports in the industry. Volume 34, published April 2026, placed AGENTS.md at “Trial.” The Radar’s definition of Trial: “Worth pursuing. It is important to understand how to build up this capability. Enterprises should try this technology on a project that can handle the risk.”

The implication: AGENTS.md is no longer an experimental pattern. It’s a Trial-stage practice, which in Radar terms means “the early-adopter window is open and most teams should start.” If your team has any meaningful use of AI coding agents, AGENTS.md is the cheapest, lowest-risk reliability upgrade available right now.

Frequently asked questions

Do I need an AGENTS.md if my project is small?

For a single-file script, no. For anything with more than a handful of source files, a test suite, or any non-obvious convention, yes — the time you spend writing the first version pays back the next time you let an agent loose on it. A 30-minute file pays for itself in the second session.

Does Claude Code read AGENTS.md?

Not natively as of May 2026. Claude Code reads CLAUDE.md instead. The fix is a symlink: at your repo root run ln -s AGENTS.md CLAUDE.md and Claude Code will read the same file every other agent reads. Anthropic has had a feature request open for native AGENTS.md support since August 2025; we’ll update this guide when it lands.

Should I commit AGENTS.md to source control?

Yes — that’s the whole point. Like README.md, AGENTS.md should be in version control so every contributor and every agent uses the same instructions. The file is project-shared, not user-specific.

Should I have an AGENTS.md and a README.md, or just one?

Both. They serve different readers. README.md introduces the project to humans (what it is, how to install, the license). AGENTS.md gives operational density to agents (every command, every convention, every “do not touch”). Keep the README short and welcoming; keep the AGENTS.md dense and exact.

What happens if I don’t have one?

The agent still runs — it just guesses more, ignores your conventions more, and produces work that needs more rewriting. The failure modes covered in our Why AI Coding Agents Fail guide all happen more frequently without an AGENTS.md. None of them happen catastrophically; you just spend more time fixing the output. Adding the file is the lowest-effort way to cut that overhead.

You may also like

• Why AI Coding Agents Fail
• CLAUDE.md: The File That Makes Claude Code Smarter
• The CLAUDE.md Pattern: Why Every AI Project Needs a House-Rules File
• Claude Code Beginners Guide
• Claude Code vs Cursor vs Copilot
• AI Agents for Beginners
• AI Glossary

Sources

• agents.md — official spec (Agentic AI Foundation / Linux Foundation)
• OpenAI Codex — AGENTS.md guide (official)
• Thoughtworks Technology Radar Volume 34 — AGENTS.md (Trial, April 2026)
• Anthropic Claude Code — AGENTS.md feature request (issue #6235)
• Anthropic — Claude Code best practices
• GitLab Duo — AGENTS.md documentation
• Walking Labs — Learn Harness Engineering (free course)
• Claude Code — Grokipedia
• GitHub Copilot — Grokipedia

Last reviewed: May 2026. The AGENTS.md spec is stable but supported-tools and feature integrations change every quarter — verify on agents.md for the current list.