What is an AGENTS.md file?

The one-sentence version

AGENTS.md is a plain-text README, but written for an AI agent instead of a human. It states your setup commands, your code conventions, your project structure, and the guardrails the agent must never cross. Modern coding agents look for it automatically and read it before starting a task.

Why it exists

Dropped into a repo with no context, an agent guesses. It reinvents patterns you already have, reaches for libraries you don’t use, edits generated files, and ignores your test and commit conventions — so you end up re-explaining the same rules in every prompt. AGENTS.md moves those rules out of your prompts and into the repo, where every agent and teammate reads the same thing.

What goes in it

A good AGENTS.md is short and specific. Five sections cover almost everything an agent needs:

• Project overview — one or two lines on what the project is and the stack, so the agent has context.
• Setup & commands — the real install, dev, build and test commands, with the exact package manager (pnpm vs npm matters).
• Code style — typing, formatting, and the patterns you expect (e.g. “TypeScript strict mode; no any without a comment”).
• Project structure — where things live, so new files land in the right place.
• Guardrails — the “never do this” rules: don’t edit build output, don’t commit secrets, don’t hand-edit migrations. This is the highest-value section.

A minimal example

Here’s what a small but complete AGENTS.md looks like for a Next.js project:

# AGENTS.md

## Project
Next.js 14 app (App Router) in TypeScript.

## Setup
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test` — run before marking any task done.

## Code style
- TypeScript strict mode; no `any` without a justifying comment.
- Prefer Server Components; add 'use client' only when needed.

## Guardrails
- Never edit files in `.next/` — they are build output.
- Never commit secrets or `.env` files.

Notice it’s mostly imperative, scannable lines — not prose. Agents follow short, explicit rules far more reliably than paragraphs.

Where it goes and who reads it

Place it as AGENTS.md at your repository root; agents read the nearest one in the tree, so monorepos can have a tailored file per package. It’s a shared convention across Cursor, Claude Code, OpenAI Codex, GitHub Copilot, Gemini, Windsurf, Zed and more. Tools that use their own filename can be pointed at it with a symlink, so you maintain one source of truth.

How it relates to .cursorrules and CLAUDE.md

Before AGENTS.md, each tool had its own file — Cursor’s .cursorrules, Claude Code’s CLAUDE.md, Copilot’s instructions file. AGENTS.md is the tool-neutral version of the same idea. The practical approach is to keep one canonical AGENTS.md and generate or symlink the tool-specific files from it, so they can’t quietly drift apart. See AGENTS.md vs .cursorrules and AGENTS.md vs CLAUDE.md for the details.

Common mistakes

• Writing a novel. Long prose dilutes the rules. Keep it to scannable bullet points.
• Skipping guardrails. The “never do X” list is the part that saves you cleanup — don’t omit it.
• Vague commands. “Run the tests” is weaker than the exact command, pnpm test.
• Letting it rot. An AGENTS.md that disagrees with your actual scripts is worse than none. Keep it current as the project changes.

The fastest way to write one

A blank file helps no one — the value is the specific rules your stack needs. The free agentsmd generator detects your stack from a manifest and writes a tuned file in about thirty seconds, then exports it to every agent format. If you already have one, the linter scores it and shows exactly what’s missing.

Frequently asked

Other stacks & guides