AGENTS.md: The Root-Level README That AI Coding Agents ...

TL;DR. AGENTS.md is a markdown file at the root of your project or site that AI coding agents read before doing anything. Roughly 35 agent tools (Cursor, Claude Code, OpenAI Codex, GitHub Copilot, Gemini CLI, Amp, Jules, Roo Code, Junie, and more) standardized on it during 2024 and 2025. If your site exposes any developer or repo surface (docs, API, examples), publishing one is a small investment with a meaningful payoff: the agents stop guessing and start following your conventions.

Why this exists

Coding agents have a problem that anyone who has onboarded a junior engineer recognizes. They show up smart but uncalibrated. They don't know which test command to run. They don't know your formatter. They don't know that make deploy actually pushes to staging or that the env var LEGACY_MODE exists for backward compatibility. Without a written README aimed at them, they invent answers and you spend the next twenty minutes correcting them.

AGENTS.md is the answer to that. It's a single markdown file scoped to AI coding agents, sitting at the root of a repository or static site at the canonical path /AGENTS.md. The spec lives at agents.md. It's intentionally simple: a markdown file with a handful of well-named sections.

The format settled out of independent conventions that several agent vendors were adopting around 2024 (CLAUDE.md, CURSOR.md, custom files for Codex). By mid-2026 the Linux Foundation's Agentic AI Foundation absorbed the format under the AGENTS.md name, and most major vendors aligned. As of this writing, 30-plus coding agents look for /AGENTS.md (or its repo equivalent at the project root) before they execute commands.

What goes inside

The spec is deliberately loose. Use the sections that map to your project. The ones that matter most:

## Setup — How an agent should install dependencies. Exact commands. The Node version, the Python version, the package manager. If there's a .tool-versions file, point at it.
## Test — How to run tests. Which tests are required, which are optional. Which suites are flaky and should be retried, which are deterministic and should never be retried.
## Build — The build command. Where output lands. How to verify the build worked.
## Deploy — Whatever an agent should know before triggering a deploy. Which branch deploys where. Which env vars must exist. Which paths must NOT be deployed (internal docs, backup folders, secrets that slipped past .gitignore).
## Conventions — Code style. Imports. Comment policy. Naming. The unwritten rules a human teammate would learn by osmosis.
## Gotchas — The things that have bitten you. The compose stack that needs the database to be up first. The migration that has to run before the test suite. The Netlify function that needs -background.mjs suffix or it silently drops the cron.
## Anti-patterns — Things you do NOT want an agent to do. Never run git push --force. Never install a new dependency without asking. Never modify the file named _secrets.example. Pre-declared "no" lines save you from cleaning up after a confident misstep.

Two minor conventions help. First, keep it under 200 lines. If it grows past that, split per-folder AGENTS.md files inside the relevant subdirectories (most agents respect the nearest one). Second, treat it like a README scoped to agents: write the things a smart new contributor would need to know on day one. Don't write planning docs, roadmaps, or architectural deep-dives. Those rot, and they push the useful instructions past the agent's context window.

What it has to do with your website

AGENTS.md started as a repo file but it's increasingly relevant for sites that have a developer surface. If you publish docs, expose an API, ship an SDK, or have any "build something with this" path on your site, an agent visiting from a developer-prompt context will look for /AGENTS.md at the root.

The Mega SEO Analyzer's agent-readiness dimension treats AGENTS.md as a conditional signal. It only flags missing AGENTS.md when the site appears to have a developer surface (docs, API, examples, references). A pure marketing brochure site, an e-commerce store with no dev path, or a content blog won't get the flag. If you do publish to developers, though, the file pays for itself the first time an agent uses it instead of guessing.

What to write in yours

For a static site with no repo surface, you don't need one. Skip it.

For a project with a repo (public or private), the bare minimum looks like this:

# AGENTS.md

## Setup
- Node 20+
- `npm install`

## Test
- `npm test` — fast, deterministic, must pass before commit
- `npm run test:e2e` — slow, run before deploy

## Build
- `npm run build` — output to `/dist`

## Deploy
- `main` branch auto-deploys to production via Netlify
- Never deploy from `dev`; use a PR

## Conventions
- TypeScript strict mode
- Single quotes, no semicolons (Prettier config in repo)
- Tests live next to source: `foo.ts` + `foo.test.ts`

## Anti-patterns
- Never `git push --force` to `main`
- Never bypass pre-commit hooks
- Never commit `.env`

That's enough for an agent to do useful work without breaking things. Add gotchas as you discover them. The Gotchas section is the one I find I update most often: every time an agent makes the same mistake twice, the third time gets a line in AGENTS.md.

How to verify yours is working

Open it in a coding agent that respects the spec (Claude Code, Cursor, Codex CLI all do). Give the agent an ambiguous task that depends on something in your AGENTS.md. If it picks the right command without asking, the file is doing its job. If the agent asks "which test command should I run?" your AGENTS.md is either missing, in the wrong place, or buried under other context.

For audit-level verification, the Agent-Ready Audit tool checks for /AGENTS.md at root alongside the rest of the Cloudflare Agent Readiness Score signals.

Fact-check notes and sources

agents.md: official spec
Linux Foundation Agentic AI Foundation: project page and adopter list
OpenAI Codex: Codex CLI docs that reference AGENTS.md
Anthropic: Claude Code project-memory documentation

This post is informational, not technical consulting. The list of 30+ agents reflects publicly-documented adoption as of mid-2026. Vendor lists shift; verify against the current agents.md adopter page before counting on a specific tool's behavior.

AGENTS.md: The Root-Level README That AI Coding Agents Actually Read