The AGENTS.md standard for AI coding agents

AGENTS.md is an operating document for AI coding agents. It tells the agent how to work in this tree: where the map is, which commands to run, how this repo does git, and what it must always do, ask about, or never do.

It is not a second README. A README introduces the project to people. It is not a style guide. Linters and the codebase already own coding standards.

The format is plain Markdown. There is no required schema, YAML frontmatter, or JSON config. The open convention lives at agents.md: the filename is AGENTS.md, the closest file to the files being edited wins, listed commands get run, and a message in chat always overrides the file.

In December 2025 the format was donated to the Agentic AI Foundation (AAIF), a directed fund under the Linux Foundation, alongside Anthropic's Model Context Protocol. One file, many agents.

Aim for about 200 lines at the root. That is complete enough for the map, git rules, and boundaries. It is short enough to load every session.

What the file contains

Five blocks. Keep them in this order.

Overview — what this tree is, in a few sentences.

Map and where to find more — the folders that matter, and a pointer to the index for durable knowledge. Point. Do not paste the wiki.

Commands — the exact install, test, and lint commands. If you write it, the agent will try it.

Git workflow — how this repo ships. Branch names, whether to open a pull request or push to main, commit-message mood. Git is repo-specific, unlike coding standards.

Boundaries — Always do. Ask first. Never do.

Example: a root AGENTS.md

A fictional billing monorepo. The names are illustrative. Keep the blocks.

Repository root — fictional billing monorepo

# AGENTS.md

## Project overview
Billing platform monorepo: a Node API (`apps/api`), a React dashboard (`apps/web`), and shared libraries under `packages/`. Root rules apply unless a nested AGENTS.md says otherwise.

## Map
- `apps/api` — invoice and payment API
- `apps/web` — operator dashboard
- `packages/` — shared types and clients
- `infra/` — Terraform for staging and production
- Durable product knowledge: `docs/INDEX.md`. Open that map when you need a service, runbook, or decision.

## Commands
pnpm install
pnpm test
pnpm lint
pnpm --filter @acme/api test
docker compose up -d   # before API integration tests

## Git workflow
- Open a pull request against `main`. Do not push commits to `main`.
- Branch names: `feat/<short-name>` or `fix/<short-name>`
- Commit messages: imperative mood, complete sentences.

## Boundaries

### Always do
- Run `pnpm test` and `pnpm lint` before you consider a change done.
- Read `docs/INDEX.md` before inventing a service name or a runbook step.

### Ask first
- Changing auth, billing webhooks, or CI workflows.
- Adding a nested `AGENTS.md`.
- Touching `infra/` production modules.

### Never do
- Commit `.env`, API keys, or customer payment data.
- Invent an undocumented payment provider.

Nested files

The closest AGENTS.md to the files being edited wins. Nesting is rare on purpose. Most subdirectories follow the root file. Do not nest another copy for coverage.

Add a nested file only when that subtree actually breaks a root rule. The nested file is a delta. It does not restate pnpm, git, or never-commit-secrets.

infra/AGENTS.md — a delta, not a second copy of the root

# AGENTS.md — infra/

Root git, pnpm, and Never-secrets still apply. This file is only the delta.

## Ask first
- `terraform plan` or `terraform apply` against staging.

## Never do
- Run `terraform apply` against the production workspace.
- Edit Terraform state by hand.

What you keep out

Style that a linter can enforce. Put it in the linter.

Human CONTRIBUTING.md, except the git lines the agent will execute. If those lines are operating rules, they belong in AGENTS.md too.

If a tool still reads CLAUDE.md, point that file at AGENTS.md. Do not copy the operating rules.

Durable product knowledge — people, services, decisions — belongs in the knowledge map, not in the operating file. See Organizing knowledge for AI agents.

Long procedures belong in a linked doc or skill. One line in AGENTS.md is enough: for X, read Y. Do not make skills the spine of the file.

Keep it alive

When an agent repeats a mistake, add a boundary line. When a line goes stale, delete it. The 200-line budget is how you notice bloat.

Summary

Write one root AGENTS.md of about 200 lines. Give it a map, git rules, and Always / Ask first / Never. Nest another file only when a subdirectory actually breaks those rules. Chat still overrides the file.

Dylan Engelbrecht updates this knowledge hub as agent practice evolves. Treat these articles as living reference — current practice, not a frozen snapshot.