AGENTS.md: The README for AI Agents

TL;DR

• AGENTS.md is a README for agents. It's a simple, open format (agents.md) for providing context and instructions to AI coding agents—used by 60k+ open-source projects.
• One file, many agents. Write AGENTS.md once and it works across Cursor, Claude Code, VS Code, Devin, Windsurf, and 20+ other coding agents—no lock-in.
• Keep READMEs clean. Put agent-specific details (build steps, test commands, code style) in AGENTS.md. Keep README.md focused on humans.

Your agent is smart. Your repo's README is 200 lines of "getting started" aimed at humans. The agent reads it, tries npm install, fails because you use pnpm, then guesses at your test command and gets that wrong too. Twenty minutes later, you've typed the same setup instructions you typed last week. And the week before that.

AGENTS.md fixes this. One file, at the root of your repo, that tells every agent exactly how to build, test, and contribute. Write it once. Never repeat yourself again.

Where things stand: Over 60,000 open-source projects now include AGENTS.md—from OpenAI's Codex to Apache Airflow, Temporal, and Pluto. Coding agents from Google, OpenAI, Cursor, Anthropic, and others all read AGENTS.md automatically on startup. It's becoming the default way to guide agents, the same way README.md became the default for humans.

What Is AGENTS.md?

AGENTS.md is a Markdown file at the root of your repository that contains context and instructions for AI coding agents. Think of it as a "README for agents"—a place to document everything agents need to work effectively on your project, without cluttering your README.md.

From agents.md:

• For developers: A predictable, agent-focused place to document build steps, tests, and conventions.
• For agents: A clear, standardized file with project context and commands they need to be productive.
• For teams: Capture tribal knowledge in version-controlled, shareable documentation—onboard agents (and humans!) faster.

Why a separate file?

README.md files are for humans: quick starts, project descriptions, contribution guidelines. They're optimized for someone who wants to understand and use your project.

AGENTS.md is for agents: build commands, test workflows, code style rules, deployment steps. It's optimized for someone (or something) that needs to work on your project—make commits, fix bugs, add features.

Separation benefits:

• Clearer focus: README stays concise; AGENTS.md can be detailed.
• Less clutter: Agent-specific commands don't overwhelm human readers.
• Better agent performance: Agents know exactly where to look for instructions.

The Format

AGENTS.md is just Markdown. No required fields, no strict schema. Use whatever headings and structure make sense for your project.

Common sections:

Example (minimal):

# AGENTS.md

## Setup commands

- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`

## Code style

- TypeScript strict mode
- Single quotes, no semicolons
- Use functional patterns where possible

## Testing instructions

- Run `pnpm test` before committing.
- Add tests for any new features.
- Fix any failing tests before submitting a PR.

# AGENTS.md

## Dev environment tips

- Use `pnpm dlx turbo run where <project_name>` to jump to a package instead of scanning with `ls`.
- Run `pnpm install --filter <project_name>` to add the package to your workspace so Vite, ESLint, and TypeScript can see it.
- Use `pnpm create vite@latest <project_name> -- --template react-ts` to spin up a new React + Vite package with TypeScript checks ready.
- Check the `name` field inside each package's `package.json` to confirm the right name—skip the top-level one.

## Testing instructions

- Find the CI plan in the `.github/workflows` folder.
- Run `pnpm turbo run test --filter <project_name>` to run every check defined for that package.
- From the package root you can just call `pnpm test`. The commit should pass all tests before you merge.
- To focus on one test, add the Vitest pattern: `pnpm vitest run -t "<test name>"`.
- Fix any test or type errors until the whole suite is green.
- After moving files or changing imports, run `pnpm lint --filter <project_name>` to be sure ESLint and TypeScript rules still pass.
- Add or update tests for the code you change, even if nobody asked.

## PR instructions

- Title format: `[<project_name>] <Title>`
- Always run `pnpm lint` and `pnpm test` before committing.

Key takeaway: There's no required format. Write what helps agents (and future team members) work on your project.

How Agents Use AGENTS.md

Discovery

When an agent starts working on your project, it looks for AGENTS.md at the root. If found, it reads the file into its context. This happens automatically—no user action required.

Priority: The closest AGENTS.md in the directory tree takes precedence. For monorepos, you can have:

• A root AGENTS.md with general project info.
• Nested AGENTS.md files in each package/subproject with package-specific instructions.

Example:

my-monorepo/
  AGENTS.md            # General monorepo info
  packages/
    frontend/
      AGENTS.md        # Frontend-specific commands
    backend/
      AGENTS.md        # Backend-specific commands

When the agent edits packages/frontend/src/App.tsx, it reads packages/frontend/AGENTS.md. When it edits root-level files, it reads the root AGENTS.md.

The "aha" here: AGENTS.md is scoped automatically. You don't configure this. The agent just looks for the nearest AGENTS.md and uses it. It's like .gitignore — the closest one wins.

Execution

Agents use AGENTS.md to:

1. Understand project structure — What's this repo? What tech stack?
2. Run commands — How do I build? How do I test?
3. Follow conventions — What's the code style? Commit message format?
4. Fix issues — If tests fail, the agent knows how to run them and what the failure means.

Automatic execution:
If you list testing commands in AGENTS.md, agents will run them automatically before finishing a task. Example: if AGENTS.md says "Run pnpm test before committing," the agent will run that command and fix any failures.

Conflict resolution:
If instructions conflict, the priority is:

1. Explicit user prompts — "Do X" overrides everything.
2. Nearest AGENTS.md — The closest file to the edited code wins.
3. README or docs — Fallback if no AGENTS.md exists.

Why AGENTS.md Matters

For solo developers

• Faster onboarding: When you return to an old project, the agent knows how to build and test—no "how do I run this again?"
• Less repetition: Write setup instructions once; agents follow them forever.

For teams

• Consistent workflows: Everyone's agent runs the same commands, follows the same conventions.
• Capture tribal knowledge: "We always run this script before deploying" is written down, not passed by word of mouth.
• Easier code reviews: Agents know your PR title format and commit message style.

For open-source projects

• Better contributions: External contributors (and their agents) know how to build, test, and follow your conventions.
• Reduced friction: No more "How do I run the tests?" issues. It's in AGENTS.md.

Real-World Examples

Example 1: OpenAI Codex

Repo: github.com/openai/codex
Structure: Monorepo with 88 AGENTS.md files (1 root + 87 nested in subprojects).
What's documented:

• Dev environment tips (how to navigate the monorepo).
• Testing instructions (how to run tests, focus on one test).
• PR instructions (title format, pre-commit checks).

Result: Contributors and agents know exactly how to work on any subproject.

Example 2: Apache Airflow

Repo: github.com/apache/airflow
What's documented:

• Setup commands (install dependencies, start services).
• Testing instructions (run integration tests, unit tests).
• Code style (Python formatting, linting rules).

Result: New contributors (and agents) can start contributing faster.

Example 3: Temporal SDK (Java)

Repo: github.com/temporalio/sdk-java
What's documented:

• Build commands (Maven commands, test commands).
• Architecture notes (module structure, key classes).
• Security considerations (how to handle credentials).

Result: Agents know how to build and test the SDK without trial and error.

See 60k+ more: github.com/search?q=path:AGENTS.md

Compatible Agents (2026)

AGENTS.md works across 20+ coding agents and tools. When you write AGENTS.md, you're not locked into one tool—it's an open standard.

Supported agents (partial list):

• OpenAI Codex — General-purpose CLI tooling.
• Google Jules — Google's coding agent.
• Cursor — AI-powered code editor.
• Anthropic Claude Code — Coding agent from Anthropic.
• Devin (from Cognition) — Autonomous software engineer.
• GitHub Copilot Coding Agent — GitHub's agentic coding tool.
• Windsurf (from Codeium) — AI code editor.
• Aider — AI pair programming in your terminal.
• Factory — AI software engineer.
• Roo Code — AI coding assistant.
• VS Code — With AI extensions that read AGENTS.md.
• Zed — Next-generation code editor.
• Goose — Open-source coding agent.
• And 10+ more — See agents.md for the full list.

Key point: You write AGENTS.md once. Every compatible agent reads it. No need to configure each tool separately.

How to Write a Great AGENTS.md

1. Start simple

Don't overthink it. Start with the basics:

• How to install dependencies.
• How to build and run the project.
• How to run tests.

You can always add more later.

2. Be specific

Bad: "Run the tests."
Good: "Run npm test to run all tests. Run npm test -- --watch for watch mode."

Bad: "Follow code style."
Good: "Use Prettier with the config in .prettierrc. Single quotes, no semicolons. Run npm run format before committing."

3. Include gotchas

Document things that aren't obvious:

• "The backend requires a .env file. Copy .env.example to .env and fill in your API keys."
• "Tests require Docker to be running. Start with docker-compose up -d."
• "On macOS, you may need to install libpq via Homebrew for Postgres support."

4. Keep it up to date

AGENTS.md is living documentation. When your build process changes, update AGENTS.md. Treat it like code: commit updates when workflows change.

5. Use nested files for monorepos

If you have a monorepo, put a root AGENTS.md with general info and nested AGENTS.md files in each package with package-specific commands.

Example (Next.js monorepo):

# Root AGENTS.md

## Project structure

- `apps/web` — Next.js web app
- `apps/api` — Express API
- `packages/ui` — Shared UI components

## General setup

- Install: `pnpm install`
- Build all: `pnpm build`

## Testing

- Run all tests: `pnpm test`

# apps/web/AGENTS.md

## Web app commands

- Start dev server: `pnpm dev`
- Build: `pnpm build`
- Test: `pnpm test`

## Code style

- React functional components only
- Use Tailwind for styling

# apps/api/AGENTS.md

## API commands

- Start dev server: `pnpm dev`
- Run database migrations: `pnpm db:migrate`
- Test: `pnpm test`

## Code style

- TypeScript strict mode
- Use Express middleware for auth

6. Link to external docs

If you have detailed docs elsewhere (wiki, Notion, Confluence), link to them from AGENTS.md:

## Architecture

For detailed architecture diagrams, see [Architecture.md](docs/architecture.md).

## API docs

See [api-docs.md](docs/api-docs.md) for endpoint specifications.

Common Pitfalls

1. Duplicating the README

Mistake: Copying your entire README into AGENTS.md.
Fix: README is for using the project (what it does, how to install). AGENTS.md is for working on the project (how to build, test, contribute). They should complement each other, not duplicate.

2. Making it too long

Mistake: Documenting every possible edge case in AGENTS.md, making it thousands of lines.
Fix: Keep the main AGENTS.md concise (under ~500 lines). Put detailed docs in separate files and link to them.

3. Forgetting to update it

Mistake: Your build process changes, but AGENTS.md still has the old commands.
Fix: Treat AGENTS.md like code. Update it when workflows change. Add it to your PR checklist: "Did you update AGENTS.md if needed?"

4. Assuming agents will "figure it out"

Mistake: "The agent is smart; it'll figure out how to run tests."
Fix: Agents are smart, but explicit instructions are always better. If your test command is non-standard, document it.

Related Lessons

AGENTS.md is one piece of the agent toolkit. Two other capabilities complement it directly:

• Model Context Protocol (MCP) — AGENTS.md tells agents how to work on your project. MCP gives agents access to external tools and data (databases, APIs, Slack). Use both: AGENTS.md for project context, MCP for tool connections.
• Subagents — When your AGENTS.md documents complex workflows (build → test → deploy), subagents can execute each step in isolation. The subagent reads AGENTS.md for commands, runs them, and returns only the results.

When to Use AGENTS.md vs. Agent Skills

Both AGENTS.md and Agent Skills guide agents, but they serve different purposes:

They work together:
Your AGENTS.md says "Run pnpm test before committing." Your "PR review" skill says "Check test coverage, look for security issues, verify commit messages match the format in AGENTS.md."

Rule of thumb:

• Project-specific? → AGENTS.md.
• Reusable across projects? → Agent Skill.

How to Migrate Existing Docs to AGENTS.md

Option 1: Rename

If you already have a file like AGENT.md, CLAUDE.md, or CURSOR.md, rename it to AGENTS.md for consistency.

Example:

mv AGENT.md AGENTS.md
ln -s AGENTS.md AGENT.md  # Create symlink for backward compatibility

Option 2: Extract from README

If your README contains build/test commands, extract them into AGENTS.md and simplify your README.

Before (README.md):

# My Project

This is a task management app.

## Installation

```bash
npm install
```

## Running tests

```bash
npm test
```

## Code style

- TypeScript strict mode
- Single quotes, no semicolons

## Deployment

```bash
npm run deploy:prod
```

After (README.md):

# My Project

This is a task management app built with React and Node.

For development setup, see [AGENTS.md](AGENTS.md).

After (AGENTS.md):

# AGENTS.md

## Setup

```bash
npm install
```

## Testing

```bash
npm test
```

## Code style

- TypeScript strict mode
- Single quotes, no semicolons

## Deployment

```bash
npm run deploy:prod
```

Configuring Specific Agents

Most agents automatically read AGENTS.md from the repo root. Some require configuration:

Aider

Configure Aider to use AGENTS.md in .aider.conf.yml:

read: AGENTS.md

Gemini CLI (Google)

Configure Gemini CLI to use AGENTS.md in .gemini/settings.json:

{
  "contextFileName": "AGENTS.md"
}

Cursor, Claude Code, Devin, Windsurf, VS Code

No configuration needed. These agents automatically detect and read AGENTS.md.

Real-World Use Cases (2026)

Use case 1: Onboarding new team members

Scenario: A new developer joins your team. They clone the repo and ask an agent to "build the project."
Without AGENTS.md: The agent guesses, tries npm install, fails because you use pnpm. The developer has to ask the team.
With AGENTS.md: The agent reads AGENTS.md, sees pnpm install, runs it. Project builds successfully. Developer is productive on day one.

Use case 2: Contributing to open source

Scenario: You want to fix a bug in an open-source project you've never worked on.
Without AGENTS.md: You spend 20 minutes reading the README, trying different commands, debugging setup issues.
With AGENTS.md: Your agent reads AGENTS.md, runs setup commands, builds the project, runs tests. You focus on the bug fix, not the build setup.

Use case 3: Monorepo management

Scenario: You have a monorepo with 10 packages. Each package has different build/test commands.
Without AGENTS.md: You (and your agent) have to remember which commands to run for which package.
With AGENTS.md: Each package has its own AGENTS.md. The agent reads the right one based on which file you're editing and runs the right commands.

Do This Next

1. Read the standard. Open agents.md and skim the examples. Understand the format (just Markdown, no required fields).
2. Create your first AGENTS.md. In your current project, create AGENTS.md at the root. Start with three sections: Setup, Testing, and Code Style. Document the commands you run most often.
3. Test it. Ask your agent (Cursor, Claude Code, etc.) to "build and test the project." Observe whether it follows AGENTS.md. Refine your instructions based on what the agent does.
4. Add to your team repos. If you work on a team, propose AGENTS.md for your main repos. Add build, test, and PR conventions. Share with the team.
5. Use nested files for monorepos. If you have a monorepo, add a root AGENTS.md and nested AGENTS.md files in each package. Test that agents read the correct file based on which code they're editing.

By experience tier:

• 1–3 years: Start with a personal project. Document the three commands you always forget: install, build, test. You'll notice agents stop asking you the same questions.
• 4–7 years: Add AGENTS.md to your team's main repos. Document not just commands but gotchas—the things that trip up every new team member (and their agent).
• 8–15 years: Champion AGENTS.md as a team standard. Add it to PR checklists ("Did you update AGENTS.md?"). Use nested files for monorepos. Capture the tribal knowledge that currently lives in Slack threads.
• 15–20 years: Evaluate AGENTS.md adoption across your org. Create templates for different project types (microservices, monorepos, data pipelines). Train teams on writing effective agent documentation.
• 20–30 years: Use AGENTS.md as a lens for organizational documentation health. Projects with good AGENTS.md files have good engineering practices—it's a leading indicator. Drive adoption as part of developer experience initiatives.
• 30+ years: You've seen READMEs, Makefiles, and CI configs each become standard. AGENTS.md is the next one. Mentor teams on writing documentation that serves both humans and agents—the principles haven't changed, just the audience.

Resources

• Official site: agents.md
• GitHub search: 60k+ projects with AGENTS.md
• Example (OpenAI Codex): github.com/openai/codex/blob/main/AGENTS.md
• Example (Apache Airflow): github.com/apache/airflow/blob/main/AGENTS.md
• Example (Temporal): github.com/temporalio/sdk-java/blob/main/AGENTS.md
• FAQ: agents.md/#faq

About

AGENTS.md emerged from collaborative efforts across the AI software development ecosystem, including OpenAI Codex, Amp, Jules from Google, Cursor, and Factory. It's an open standard that benefits the entire developer community, regardless of which coding agent you use. For the latest governance and organizational details, see agents.md.