What is AGENTS.md? The New Standard for AI Agent Instructions

AGENTS.md is a markdown file in your project root that tells AI coding agents how to work with your codebase. It contains instructions about coding standards, test commands, architecture decisions, and file conventions. AI tools like Claude Code, Cursor, and Codex read it automatically and follow the rules you set.

Why It Exists

AI coding agents are getting good at writing code. They’re bad at knowing your project’s conventions. Without context, an agent will:

• Use npm when your project uses pnpm
• Write tests in Jest when you use Vitest
• Put files in the wrong directories
• Ignore your linting rules
• Skip your commit message format

You could explain this every time you start a conversation. Or you could write it down once in a file the agent reads on its own.

That’s what AGENTS.md does. It’s a one-time setup that saves you from repeating yourself across every AI interaction.

The robots.txt Analogy

The comparison to robots.txt is useful. robots.txt is a plain text file at the root of a website that tells search engine crawlers what to index and what to skip. Every major crawler respects it.

AGENTS.md works the same way, but for AI coding assistants. Drop it in your project root. AI agents that support the convention will read it before they start writing code. The instructions shape how the agent behaves in your repo.

What Goes in AGENTS.md

A typical file covers four areas:

Project setup and commands. How to install dependencies, run the dev server, execute tests, and build the project. Agents use this to verify their changes work.

Coding standards. Formatting rules, naming conventions, import ordering, preferred patterns. If your team uses tabs over spaces, say so here.

Architecture notes. Where different types of files live, how the module system is organized, which patterns to follow (and which to avoid).

Constraints and warnings. Files the agent shouldn’t modify, deprecated patterns to avoid, security-sensitive areas that need careful handling.

Here’s a practical example:

## Setup
- Package manager: pnpm (do not use npm or yarn)
- Node version: 22+
- Install: `pnpm install`
- Dev server: `pnpm dev` (port 3001)

## Testing
- Framework: Vitest
- Run all tests: `pnpm test`
- Run single file: `pnpm test src/utils/parser.test.ts`
- Always run tests after making changes

## Code Standards
- TypeScript strict mode, no `any` types
- Use arrow functions for callbacks
- Tab indentation, double quotes
- Formatter: Biome (run `pnpm check` to verify)
- Imports: group by external, internal, types

## Architecture
- Routes: `src/routes/` (file-based routing via TanStack Router)
- Components: `src/components/` (React function components only)
- Database queries: `src/db/queries/` (Drizzle ORM)
- API contracts: `src/contracts/` (ts-rest with Zod schemas)

## Do Not
- Modify migration files in `src/db/migrations/`
- Use `console.log` in production code
- Add dependencies without asking first

Short, scannable, and specific. An agent reading this file knows exactly how to operate in the project.

How AI Tools Use It

Different AI coding tools have adopted this pattern under slightly different names, but the concept is the same.

Claude Code reads CLAUDE.md (its own variant) from the project root automatically at the start of every conversation. It also checks parent directories and ~/.claude/ for user-level instructions.

Cursor reads .cursorrules or picks up AGENTS.md from the project root. The instructions are injected into the system prompt.

OpenAI Codex supports AGENTS.md directly. The file is read before the agent starts working.

The trend is clear: a root-level markdown file with project instructions is becoming a standard part of codebases, just like .gitignore or .editorconfig.

AGENTS.md vs. MCP

These two concepts are complementary, not competing.

AGENTS.md is static. It’s a file with instructions that the agent reads. It tells the agent how to work. Think of it as documentation for the AI.

MCP (Model Context Protocol) is dynamic. It’s a protocol that lets agents call external tools at runtime. It tells the agent what it can do. Think of it as an API for the AI.

A project can use both. AGENTS.md tells the agent “we use PostgreSQL, Drizzle ORM, and here’s how to run migrations.” An MCP server gives the agent the ability to actually query the database or run those migrations.

For more on MCP, see What is MCP? A Developer’s Guide.

Tips for Writing a Good AGENTS.md

Be specific. “Follow best practices” tells the agent nothing. “Use Vitest for tests, place test files next to source files with .test.ts suffix” tells it exactly what to do.

Keep it current. An outdated AGENTS.md is worse than none at all. Update it when you change your tooling or conventions. Treat it like code, not documentation that rots in a wiki.

Test it. Start a new AI coding session and see if the agent follows your instructions. If it doesn’t, your instructions are unclear. Rewrite them.

Start small. You don’t need to document everything on day one. Start with the commands to install, build, test, and lint. Add more as you notice the agent making the same mistakes.

Publishing Your AGENTS.md

If you maintain open-source projects, your AGENTS.md helps external contributors who use AI coding tools. It also makes it easy to share your project conventions with new team members, AI-assisted or not.

You can publish your AGENTS.md to a shareable URL with MDtoLink for easy reference outside the repo:

mdtolink AGENTS.md

For more on how AI agents work with documentation, see AI Agent Reports.