AGENTS.md is an open, tool-agnostic Markdown file placed at the root of a repository that tells AI coding agents how to work in it — the project's stack, key commands, conventions, what not to do, and the definition of done. Because it's vendor-neutral it's read by 28+ agents (OpenAI Codex, Cursor, Aider, Cline, Continue, Goose, Jules, Zed and more), so you write the guidance once instead of per tool.

What should go in an AGENTS.md file?

A one-line project overview, the stack, the key commands (build, test, lint, deploy), code conventions and decisions the agent must follow, explicit don't-dos (anti-patterns), and your definition of done. There is no required schema — keep it short and specific. Bloated files hurt: research found dump-everything context files lowered task success ~3% and raised cost 20%+, while lean curated ones improved success ~4%.

Where do I put AGENTS.md?

At the root of your repository. In a monorepo you can also add an AGENTS.md inside a subdirectory; the file nearest to the code being edited wins, so each package can have its own rules layered over the root.

Do all AI tools read AGENTS.md?

Many do directly (Codex, Cursor, Aider, Cline, Continue, Goose, Zed and others — 28+). Claude Code reads CLAUDE.md, Cursor also reads .cursor/rules/*.mdc, GitHub Copilot reads .github/copilot-instructions.md, and the Gemini CLI reads GEMINI.md. The content is identical across them — only the filename and location change, so keep one source of truth and generate the rest.

AGENTS.md

AGENTS.md is the open, tool-agnostic file that tells AI coding agents how to work in your repo — stack, commands, conventions, what not to do, definition of done. It lives at your repo root and is read by 28+ tools, so you write the rules once instead of per tool.

Generate your AGENTS.md free →

What is AGENTS.md?

A plain-Markdown file at the root of your repository — no required frontmatter, no schema. Its whole job is to give a coding agent the context a new teammate would need: what the project is, how to run it, the conventions, the landmines, and what "done" means. Because the format is vendor-neutral, agents converged on it — OpenAI Codex, Cursor, Aider, Cline, Continue, Goose, Jules, Zed and more read it directly.

What goes in an AGENTS.md file?

Overview — one line on what the project is.
Stack — languages, framework, database, key libraries.
Commands — build, test, lint, dev, deploy.
Conventions — the decisions an agent must follow.
Don't — explicit anti-patterns and off-limits areas.
Definition of done — what must be true before a change ships.

AGENTS.md example

A clean, lean example you can adapt:

# Acme Web — agent guide

> Senior full-stack engineer. Small, reviewable diffs. Tests with every change.

## Stack
Next.js 15 (App Router) · TypeScript · Tailwind · Drizzle ORM · Postgres (Neon)

## Commands
```
dev:    pnpm dev
build:  pnpm build
test:   pnpm test
lint:   pnpm lint && pnpm typecheck
```

## Conventions
- Server components by default; add "use client" only when needed.
- All DB access goes through src/db/ (Drizzle) — never raw SQL in routes.
- Match the surrounding file's style; don't reformat unrelated code.

## Don't
- Don't add dependencies without asking.
- Don't edit generated files in src/db/migrations/.
- Don't commit secrets — use .env.local (see .env.example).

## Definition of done
- pnpm lint + pnpm test pass.
- New UI works at 375px mobile width.

Make one for your project →

Best practices

Keep it lean. ETH Zurich's Evaluating AGENTS.md found dump-everything machine-generated files lowered task success ~3% and raised cost 20%+, while short curated ones improved success ~4%. Fewer, sharper rules win.
Be specific, not aspirational. "All DB access through src/db/" beats "write clean code."
One source of truth. Don't hand-maintain AGENTS.md, CLAUDE.md and Cursor rules separately — they drift. Generate them, or symlink (ln -s AGENTS.md CLAUDE.md).
Use nearest-file-wins. In a monorepo, put a focused AGENTS.md in each package; the file nearest the edited code applies.
Keep it fresh. Update it when commands or conventions change — a stale rule is worse than no rule.

Where do I put it?

At the repo root. In a monorepo you can also drop an AGENTS.md in a subdirectory — the file nearest to the code being edited wins, so each package layers its own rules over the root.

AGENTS.md and the other files

Same guidance, different filenames per tool:

File	Tool
AGENTS.md	Codex, Cursor, Aider, Cline, Continue, Goose, Zed… (28+)
CLAUDE.md	Claude Code — see AGENTS.md vs CLAUDE.md
.cursor/rules/*.mdc	Cursor (glob-scoped)
.github/copilot-instructions.md	GitHub Copilot
GEMINI.md	Gemini CLI

Generate all of them, free

Fill in your project's rules once and get AGENTS.md + CLAUDE.md + Cursor + Copilot + Gemini, correctly formatted, with a token-budget warning so they stay lean. No signup.

Open the Agent Memory Compiler →

Keep it in sync with your work

Generated files drift the moment your project changes. In TaskPrio your rules live in one place and your agents pull them over MCP with get_next_task — the memory and the task queue become one source of truth. Edit once; every agent stays current. See the MCP queue →

FAQ

What is AGENTS.md?

An open, tool-agnostic Markdown file at your repo root telling AI coding agents how to work — stack, commands, conventions, don't-dos, definition of done. Read by 28+ tools.

What goes in it?

Overview, stack, commands, conventions, don't-dos, definition of done — kept lean. No required schema.

Where does it go?

Repo root; subdirectory files override for that subtree (nearest-file-wins).

Generate your AGENTS.md → AGENTS.md vs CLAUDE.md →