AGENTS.md: The Complete Guide to Configuring AI Coding Agents (2026)

You've got an AI coding agent running in your terminal. It can read your files, write code, run commands. But it doesn't know that your team uses Tailwind instead of CSS modules, that the /legacy folder shouldn't be touched, or that tests need to pass before any commit.

That's what AGENTS.md solves.

What Is AGENTS.md?

AGENTS.md is a Markdown file you drop into your repository to give AI coding agents context about your project. It's the difference between an agent that generates generic code and one that follows your conventions from the first line.

Think of it like onboarding documentation: except the reader is an AI agent, not a new hire. You describe your tech stack, coding standards, file structure, boundaries, and any rules the agent should follow.

A minimal AGENTS.md looks like this:

# Project: My SaaS App

## Stack
- Next.js 15 (App Router), TypeScript strict, Tailwind CSS
- Database: Postgres via Prisma
- Auth: NextAuth.js v5

## Conventions
- Use named exports, not default exports
- All API routes go in /app/api/
- Tests use Vitest, not Jest
- Never modify files in /legacy/, that code is frozen

## Before committing
- Run `npm run lint && npm run test`
- Keep PR descriptions under 3 sentences

No special syntax. No schema to learn. Just Markdown that the agent reads before it starts working.

AGENTS.md Adoption Status (Mid-2026)

AGENTS.md started as an OpenAI initiative in August 2025 and quickly became the closest thing the ecosystem has to a cross-tool standard. By December 2025, it was placed under the Linux Foundation's Agentic AI Foundation (alongside Anthropic's MCP protocol and Block's Goose) with backing from OpenAI, Anthropic, Google, AWS, and others.

As of June 2026, the official AGENTS.md site lists 28+ tools with native support and over 60,000 open-source repositories on GitHub include an AGENTS.md file. The standardization race is effectively over.

Here's the current support landscape:

The pattern is clear: AGENTS.md is the cross-tool default. The remaining holdout is Gemini CLI, which still uses its own GEMINI.md format. Claude Code added AGENTS.md support over the spring of 2026, but its richer CLAUDE.md memory model is still preferred for Claude-specific configuration. Want a closer look at how teams actually use it? See our AGENTS.md review and the related Spec Kit review.

OpenAI Codex CLI: AGENTS.md Is Home

Codex CLI uses AGENTS.md as its primary instruction file, no surprise, since OpenAI originated the format. The CLI walks from the Git root down to your current working directory, checking each directory for instruction files.

The precedence order at each level: AGENTS.override.md > AGENTS.md > fallback files (TEAM_GUIDE.md, .agents.md). Files closer to your working directory override those closer to the root.

# AGENTS.md

## Project context
This is a Python FastAPI backend. Use Pydantic v2 models.

## Rules
- Always use async def for route handlers
- Use HTTPException for error responses, not raw Response objects
- Run pytest before suggesting completion

Codex also supports a global ~/.codex/AGENTS.md for personal defaults and lets you configure fallback filenames in ~/.codex/config.toml: you can even add CLAUDE.md to the fallback list if you want Codex to read Claude-formatted instructions.

Claude Code: CLAUDE.md (Plus AGENTS.md Support)

Claude Code has arguably the most mature instruction file hierarchy. CLAUDE.md remains its richer native format, but as of spring 2026 Claude Code also reads AGENTS.md when no CLAUDE.md is present, closing the last big gap in cross-tool compatibility.

The CLAUDE.md hierarchy:

1. ~/.claude/CLAUDE.md – Personal, global instructions (applies to every project)
2. CLAUDE.md in the repo root: Project-wide instructions
3. CLAUDE.md in subdirectories: Scoped instructions for that directory tree (loaded on-demand)

Subdirectory scoping is the standout feature. Drop a CLAUDE.md in your /api folder, and Claude Code only applies those rules when working on API files. Different standards for different parts of a monorepo, without cluttering the root file.

my-project/
├── CLAUDE.md           # Project-wide rules
├── AGENTS.md           # Cross-tool shared rules (other tools read this)
├── frontend/
│   └── CLAUDE.md       # Frontend-specific conventions
└── backend/
    └── CLAUDE.md       # Backend-specific conventions

The practical pattern for Claude Code: Put your shared rules in AGENTS.md and keep CLAUDE.md thin, with Claude-only items like permission boundaries, MCP servers, and subdirectory-scoped overrides. Claude reads AGENTS.md when CLAUDE.md is absent, and many teams reference AGENTS.md from CLAUDE.md to keep one source of truth.

For a deep dive on Claude Code's CLI capabilities, see our Claude Code CLI vs Desktop comparison.

GitHub Copilot: AGENTS.md + .github/copilot-instructions.md

GitHub Copilot added AGENTS.md support in August 2025, making it one of the earlier adopters. It also keeps its original .github/copilot-instructions.md format and added a newer .github/instructions/*.instructions.md system with YAML frontmatter for path-specific rules.

# .github/copilot-instructions.md

This repository uses TypeScript with strict mode.
Prefer functional components with hooks over class components.
Use Zod for runtime validation, not io-ts.
All database queries go through the repository pattern in /src/repos/.

The .github/instructions/ format lets you scope rules to specific file patterns:

---
applyTo: "src/**/*.ts"
---
Use strict TypeScript with no `any` types.

For AGENTS.md, Copilot follows the nearest-file-in-directory-tree precedence: same as most other tools. Both systems coexist, so you can use AGENTS.md for cross-tool instructions and .github/ files for Copilot-specific rules.

Gemini CLI: GEMINI.md

Google's Gemini CLI uses GEMINI.md as its native format. It hasn't confirmed native AGENTS.md support, but its GEMINI.md system is solid.

Gemini CLI has a unique directory traversal behavior: it reads GEMINI.md files both UP and DOWN the directory tree, concatenating everything with path separators. You can inspect the final combined context with /memory show.

# GEMINI.md

## Stack
- Go 1.22, Chi router, sqlc for database queries
- Frontend: Svelte 5 with TypeScript

## Guidelines
- Use structured logging (slog) not fmt.Println
- All errors must be wrapped with fmt.Errorf
- Tests go in _test.go files in the same package

Global defaults go in ~/.gemini/GEMINI.md, mirroring the Claude Code and Codex patterns.

Cursor: .cursorrules + .cursor/rules/ + AGENTS.md

Cursor was one of the first tools to popularize project-level AI instructions with .cursorrules. The community built entire repositories of shared rule sets for different frameworks.

Cursor now also reads AGENTS.md and supports a .cursor/rules/ directory with MDC-format files that include YAML frontmatter for glob-based scoping:

---
alwaysApply: true
description: "TypeScript conventions"
globs: "src/**/*.ts"
---
Use strict TypeScript. No `any` types. Named exports only.

The .cursorrules format still works but is considered legacy. New projects should use .cursor/rules/ for tool-specific config and AGENTS.md for cross-tool instructions.

Windsurf, Amp, Devin, and Others

Windsurf reads both .windsurfrules and AGENTS.md. Root-level AGENTS.md files are always active. Subdirectory AGENTS.md files apply only when Cascade works in that directory.

Amp (Sourcegraph's coding agent) reads AGENTS.md natively and falls back to CLAUDE.md if no AGENTS.md exists: a practical bridge for teams migrating between tools.

Devin reads AGENTS.md before starting any task, with nearest-file-in-directory-tree precedence.

Other confirmed adopters include Aider, VS Code, Zed, Warp, Roo Code, Jules (Google), JetBrains Junie, and Factory. The full list is tracked at the official AGENTS.md site.

How AGENTS.md Differs From CLAUDE.md, Cursor Rules, and .clinerules

The agent-config space settled on one pattern (a markdown file in the repo root) but five competing names. Here's the format-by-format breakdown:

• AGENTS.md is the open, tool-agnostic standard. No frontmatter, no schema, just markdown. Read by 28+ tools. If you only adopt one file, adopt this one.
• CLAUDE.md is Claude Code's native format. Same markdown body, but a richer three-layer memory model: user-level (~/.claude/CLAUDE.md), project root, and per-subdirectory files loaded on-demand. Best when you need scoped rules or Claude-specific config like permissions or MCP servers.
• Cursor rules (.cursorrules legacy, .cursor/rules/*.mdc current) are Cursor-only. The .mdc format adds YAML frontmatter with glob-based activation (globs: "src/**/*.ts"), which is genuinely useful but does not port to any other tool.
• .clinerules is Cline's project-config format. Same idea, Cline-only. Cline does not yet read AGENTS.md, so teams using Cline need to maintain both files or symlink one to the other.

In practice, 80–90% of the content is identical across these files: build commands, conventions, and boundaries do not change per tool. The common pattern is one detailed AGENTS.md as the source of truth, with thin tool-specific files that either point at AGENTS.md or add tool-only overrides.

AGENTS.md vs CLAUDE.md vs .cursorrules: When to Use What

If you're wondering which file to create, here's the decision framework:

Use AGENTS.md when:

• Your team uses multiple AI coding tools
• You want tool-agnostic project instructions
• You're setting up a public or open-source repo where contributors use different tools

Use a tool-specific file (CLAUDE.md, GEMINI.md, .cursorrules) when:

• You need to configure tool-specific behavior (like Claude Code's permission boundaries or Cursor's glob scoping)
• Your team standardizes on one tool
• You want to leverage features unique to that tool

Use both when:

• You want shared conventions in AGENTS.md and tool-specific overrides in the tool file
• Your monorepo has teams using different tools

The most practical setup for teams using multiple AI tools:

project/
├── AGENTS.md              # Shared: stack, conventions, boundaries (Codex, Copilot, Cursor, Windsurf, Amp, Devin)
├── CLAUDE.md              # Claude Code: permissions, MCP servers, Claude-specific rules
├── GEMINI.md              # Gemini CLI: Gemini-specific rules
├── .github/
│   └── copilot-instructions.md  # Copilot-specific path rules
└── .cursor/
    └── rules/             # Cursor-specific MDC rules with globs

Most tools read AGENTS.md plus their own native file, so shared rules live in one place. Claude Code is the exception: until native AGENTS.md support lands, you'll need to reference it from CLAUDE.md.

How to Write an Effective AGENTS.md

Most agent instruction files I've seen fall into two categories: too vague ("write good code") or too long (entire style guides pasted in). Neither works well.

Here's what actually moves the needle:

1. Start with Your Stack

Agents waste tokens guessing your framework. State it upfront.

## Stack
- Python 3.12, FastAPI 0.115, SQLAlchemy 2.0 (async)
- PostgreSQL 16, Redis for caching
- Frontend: React 19 with Vite, Tailwind CSS v4
- Testing: pytest with pytest-asyncio
- Deploy: Docker → AWS ECS

2. Define Boundaries, Not Preferences

"Prefer functional components" is nice. "Never modify files in /migrations/: use Alembic to generate them" prevents real damage.

## Boundaries
- Never modify /db/migrations/ directly: run `alembic revision --autogenerate`
- Don't add new dependencies without noting it: we audit packages monthly
- The /vendor/ directory is vendored third-party code, don't modify it
- Environment variables are in .env.example, never .env

3. Show Your Conventions Through Examples

Instead of saying "use our naming conventions," show them:

## Conventions
- API endpoints: `/api/v1/{resource}` (plural, lowercase)
- Database models: PascalCase (`UserProfile`, not `user_profile`)
- Services: `{resource}_service.py` with class-based services
- Tests: `test_{module}.py` mirroring source structure

Example endpoint pattern:
\`\`\`python
@router.get("/api/v1/users/{user_id}")
async def get_user(user_id: int, db: AsyncSession = Depends(get_db)):
    user = await user_service.get_by_id(db, user_id)
    if not user:
        raise HTTPException(404, "User not found")
    return UserResponse.model_validate(user)
\`\`\`

4. Include Verification Steps

Tell the agent how to check its own work:

## Before finishing
1. Run `make lint`: must pass with zero warnings
2. Run `make test`: all tests must pass
3. If you added a new API endpoint, add it to /docs/api-reference.md
4. If you modified a database model, generate a migration

5. Keep It Under 500 Lines

Seriously. Agents have context windows, and every line of instructions competes with the actual code they're working on. A 2,000-line AGENTS.md means the agent might miss the rule that matters most because it's buried on line 1,847.

If you need more detail, use subdirectory AGENTS.md files to scope instructions to where they're relevant.

Multi-Agent Setups and AGENTS.md

When you're running multiple agents in parallel: say, one handling frontend work and another on backend: AGENTS.md becomes even more important. Each agent needs to know its lane.

For teams doing multi-agent development workflows, subdirectory-scoped instruction files keep agents from stepping on each other:

project/
├── AGENTS.md                # Shared rules: git conventions, CI checks
├── frontend/
│   └── AGENTS.md            # "You handle UI only. Don't touch /backend/"
├── backend/
│   └── AGENTS.md            # "You handle API only. Don't touch /frontend/"
└── infra/
    └── AGENTS.md            # "You handle Terraform only. Get approval for any apply"

This pattern scales well for monorepos. Each agent gets the root-level shared context plus its own scoped instructions. No conflicts, no crossed wires.

If you're exploring parallel agent workflows, our guide on developer workflows with AI tools covers the broader orchestration patterns.

Real-World AGENTS.md Templates

Here are three templates you can adapt. Each follows the "stack → conventions → boundaries → verification" structure.

Template 1: TypeScript Web App

# AGENTS.md

## Stack
TypeScript 5.x (strict), Next.js 15 (App Router), Tailwind CSS v4, Prisma ORM, PostgreSQL

## Conventions
- Named exports only (no default exports)
- React components: functional with hooks, PascalCase filenames
- Server actions in /app/actions/, client components marked with 'use client'
- Use Zod for all form validation
- Error boundaries at route segment level

## Boundaries
- Don't modify prisma/schema.prisma without asking: migrations are tracked
- Never import from @/lib/legacy: those modules are deprecated
- Keep bundle size in mind: no lodash (use native), no moment (use date-fns)

## Verification
- `npm run typecheck && npm run lint && npm run test`
- Check for unused imports before committing

Template 2: Python Backend

# AGENTS.md

## Stack
Python 3.12, FastAPI, SQLAlchemy 2.0 (async), Alembic, pytest, Docker

## Conventions
- Type hints on all function signatures
- Pydantic v2 models for request/response schemas
- Repository pattern for database access (see /src/repos/ for examples)
- Dependency injection via FastAPI Depends()

## Boundaries
- Don't modify /alembic/versions/: generate migrations with alembic
- All secrets come from environment variables, never hardcoded
- /scripts/ contains ops scripts: only modify if explicitly asked

## Verification
- `make lint && make test`
- New endpoints need test coverage in /tests/api/

Template 3: Mobile App (React Native)

# AGENTS.md

## Stack
React Native 0.76, Expo SDK 52, TypeScript, Zustand, React Query

## Conventions
- Screens in /src/screens/, components in /src/components/
- Navigation defined in /src/navigation/: use typed navigation hooks
- API calls through /src/api/ client, never raw fetch
- All user-facing strings in /src/i18n/ for localization

## Boundaries
- Don't modify native/ directories: those need native dev environment
- App.tsx is the entry point, don't restructure it
- Expo config in app.config.ts: ask before modifying

## Verification
- `npx tsc --noEmit` for type checking
- `npx expo lint` for linting
- Test on both iOS and Android before marking complete

Common Mistakes to Avoid

Dumping your entire style guide in. Your 50-page coding standards doc doesn't belong in AGENTS.md. Extract the 10 rules that matter most and link to the full doc for reference.

Being too vague. "Follow best practices" tells the agent nothing. "Use parameterized queries for all SQL, never string concatenation" tells it exactly what to do.

Forgetting to update it. Your AGENTS.md says "use Jest" but you migrated to Vitest three months ago. Now every agent generates Jest tests. Treat it like code: keep it current.

Making it tool-specific when it shouldn't be. If you're writing instructions that apply to any AI tool, put them in AGENTS.md. Save tool-specific files for tool-specific config.

What's Next for Agent Instruction Files

AGENTS.md already won the standardization race. In December 2025, the Linux Foundation placed it under the Agentic AI Foundation alongside Anthropic's Model Context Protocol and Block's Goose agent (see the Linux Foundation announcement). Members include OpenAI, Anthropic, Google, AWS, Bloomberg, and Cloudflare.

Over 60,000 open-source repositories on GitHub already include an AGENTS.md. The remaining gaps are closing fast:

• Claude Code now reads AGENTS.md natively, with CLAUDE.md kept for the richer three-layer memory model
• Gemini CLI still uses GEMINI.md and may add AGENTS.md reading as the ecosystem consolidates
• Tool-specific files (.cursorrules, .windsurfrules) are becoming secondary to AGENTS.md in tools that support both

The practical move right now: put shared instructions in AGENTS.md, tool-specific config in the native file. You get cross-tool compatibility without losing tool-specific features. As more tools adopt AGENTS.md natively, the tool-specific files become optional overrides rather than the primary config.

If you're choosing your first AI coding tool, check out our complete guide to AI coding assistant tools or browse the tool directory to compare options side by side.

FAQ

What is AGENTS.md? AGENTS.md is a Markdown file you drop into your repository to give AI coding agents context about your project, including your tech stack, coding standards, file structure, and rules they should follow when making changes.

Which AI coding tools support AGENTS.md? OpenAI Codex CLI, GitHub Copilot, Cursor, Windsurf, Amp, and Devin all read AGENTS.md natively. Claude Code uses CLAUDE.md instead (AGENTS.md support is pending), and Gemini CLI uses GEMINI.md.

How do I get started with AGENTS.md? Start by placing an AGENTS.md file in your repository root with your stack, conventions, boundaries, and verification steps. Keep it under 500 lines and use subdirectory AGENTS.md files for scoped instructions.

What is the difference between AGENTS.md and CLAUDE.md? AGENTS.md is the cross-tool standard originated by OpenAI and governed by the Linux Foundation, while CLAUDE.md is specific to Claude Code and is the only instruction file it auto-loads. Most other tools read AGENTS.md directly.

Is AGENTS.md suitable for beginners? Yes. A minimal AGENTS.md requires no special syntax or schema, just plain Markdown describing your stack, conventions, and boundaries. You can start with a few lines and expand as needed.

---

Looking for more on working effectively with AI coding agents? Read our guide on anti-drift workflows for vibe coders to keep your projects on track as agents do more of the heavy lifting.

Related: Skills Sh Review.

Related: Openai Skills Review.