What Is an AGENTS.md File?

An AGENTS.md file is a Markdown file at the root of a repository that tells AI coding agents how to work with your codebase — the commands to run, the conventions to follow, and what to avoid. It's an emerging cross-agent standard: one file, readable by any tool that chooses to support it.

Without an AGENTS.md, every agent session starts from zero. The tool doesn't know your build command, your test runner, or that /generated is build output — so it guesses, and guessing is expensive. The file is the community answer to that problem: a plain-Markdown convention at the repo root that any agent-supporting tool can read.

Why AGENTS.md Exists

CLAUDE.md solved the "session starts from zero" problem for Claude Code. But the ecosystem is bigger than one tool — Cursor, open-source agents, and CI bots all need the same project context. AGENTS.md is the community answer: one file, no tool-specific config, readable by anything that chooses to support it.

The format was chosen deliberately: plain Markdown. No YAML frontmatter, no JSON schema, no tool-specific directives. Any agent, from a CLI tool to a browser-based coding assistant, can parse a Markdown file and extract the instructions.

What Belongs in an AGENTS.md

The same things that make any agent instruction file work:

• Project overview — 2-3 sentences: what this repo is, what stack it uses
• Setup and commands — install, build, test, lint, typecheck. The exact commands, verbatim
• Architecture map — where the important code lives, so the agent doesn't have to explore the whole tree
• Conventions — naming, formatting, error handling, commit style
• Boundaries — files and directories the agent must not touch, and why
• Definition of done — what a completed task looks like in this repo

Example

# AGENTS.md

## Overview
Payment service for the storefront. Go + Postgres, deployed to Fly.

## Commands
- Build: `make build`
- Test: `make test` (unit) - `make test-integration`
- Lint: `golangci-lint run`
- Migrate: `make migrate`

## Architecture
- /internal/api — HTTP handlers
- /internal/domain — business logic (no db calls here)
- /internal/store — Postgres access only

## Conventions
- Wire errors up in handlers; domain returns typed errors
- Table names are snake_case; columns singular
- HTTP endpoints follow /v1/resource/action

## Don't
- Never edit /migrations after it's applied to prod
- No new external services without a written proposal

AGENTS.md vs CLAUDE.md — Which Do You Need?

They're not either/or. Many teams keep a short AGENTS.md as the tool-agnostic baseline and let Claude Code pick up CLAUDE.md for its own specifics — or keep one file and point the other at it. Check the docs of the agents you actually use; support varies and moves fast.

Best Practices

1. Commands verbatim — the whole file is useless if the install command is half-remembered
2. Keep it under ~100 lines — agents follow short instruction files; they skim long ones
3. Write imperatives — "Run make test before committing" beats "it would be good to run the tests"
4. Review it in PRs — it's code-adjacent documentation; stale instructions are worse than none
5. No secrets, ever — this file is read by every session and shipped in every clone
6. Update it when the repo changes — and let the agent that noticed the change write the update

Why Hosting Your AGENTS.md Matters

A repo-root file gets read inside the repo — that's its home. But teams increasingly want the file to live somewhere it can be edited by humans, fetched by agents over HTTP, and versioned independently of the codebase:

• Keep the canonical AGENTS.md in a shared markdown workspace
• Your agent pulls it via the API at session start — identical context across machines and teammates
• When conventions change, one edit updates every future session

This pattern is especially useful for open-source projects where contributors use different tools. A centrally-hosted AGENTS.md means every contributor's agent — whether they run Claude Code, Cursor, or something else — gets the same project context, without each person needing to find and copy the file into their own repo.

Frequently Asked Questions

Is AGENTS.md an official standard? It's an emerging community convention, not an official spec — which is exactly why plain Markdown was chosen: any tool can parse it.

Does Cursor read AGENTS.md? Support varies by tool and version — check your agent's documentation. The convention was designed so any tool can read it.

Where does AGENTS.md go? The repository root, by convention. Some agents also support nested files for subdirectories.

README or AGENTS.md? Both. The README explains the project to humans; AGENTS.md tells agents how to behave in it. They serve different readers.

Should open-source projects add one? Yes — it's quickly becoming a quality signal for agent-friendly repos, and it reduces low-quality agent PRs from outsiders.

Related

• CLAUDE.md: What It Is and How Claude Code Uses It
• How Claude Code Uses CLAUDE.md (Full Walkthrough)
• What Is a Markdown File?
• Complete Guide to Markdown Files