AGENTS.md
Also called agents md file
AGENTS.md is a tool-neutral convention for a Markdown file in a repository that gives AI coding agents the project context they need — build commands, conventions, architecture, and constraints. It aims to be one file every agent reads, instead of a different file per vendor.
The problem it addresses is duplication. A repo used with several tools accumulates a rules file for each, all saying the same things and drifting apart as one gets updated and the others do not.
Support varies by tool and is still settling, so in practice teams keep whichever file their primary tool reads and treat the others as pointers to it rather than maintaining several copies of the same content.
What this means in practice
If you use one tool, use its native file — .cursor/rules or CLAUDE.md — since support there is certain. If you use several, keep the content in one place and have the others reference it, so there is a single thing to update when a convention changes.
A minimal AGENTS.md that points to one source of truth
# Project Invoice API. Fastify + Postgres. pnpm, Node 22. # Commands - pnpm dev / pnpm test / pnpm lint - pnpm test:int needs the Docker Postgres up # Conventions The full conventions live in .cursor/rules — follow them. This file exists so any agent that reads AGENTS.md lands on the same rules instead of a stale copy. # Boundaries - Ask before adding dependencies or touching migrations. - The suite must pass before any task is declared done.
The Conventions section deliberately points at one file instead of restating it — duplicated rules drift the first time only one copy gets updated.
Prompts for the tools this applies to
Related terms
- CLAUDE.md
CLAUDE.md is a Markdown file in your repository that Claude Code reads at the start of every session.
- Cursor rules
Cursor rules are project-level instructions stored in your repository that Cursor applies to every AI request — conventions, framework versions, patterns to follow, things never to do.
- Custom instructions
Custom instructions are standing directions you give an AI tool that apply to every request rather than a single one — preferred language and framework, response style, conventions to follow.