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.

Which Tools Support AGENTS.md?

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.

Here's the current support landscape:

Tool	Reads AGENTS.md	Also Has	Subdirectory Support
OpenAI Codex CLI	Primary file	AGENTS.override.md	Yes
GitHub Copilot	Yes	.github/copilot-instructions.md	Yes
Cursor	Yes	.cursor/rules/*.mdc	Yes
Windsurf	Yes	.windsurfrules	Yes
Amp (Sourcegraph)	Yes	Falls back to CLAUDE.md	Yes
Devin	Yes	—	Yes
Claude Code	Not yet	CLAUDE.md	Yes (CLAUDE.md)
Gemini CLI	Not confirmed	GEMINI.md	Yes (GEMINI.md)

The pattern is clear — AGENTS.md has become the cross-tool default. The notable holdout is Claude Code, where native AGENTS.md support is an active feature request. The workaround is to reference AGENTS.md from within your CLAUDE.md so Claude reads it manually.

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 (AGENTS.md Pending)

Claude Code has arguably the most mature instruction file hierarchy, but it uses its own CLAUDE.md format. As of March 2026, it does not natively auto-load AGENTS.md — this is an open feature request on GitHub.

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 workaround for AGENTS.md: Add a line to your root CLAUDE.md that tells Claude to read the AGENTS.md file. Not ideal, but it works until native support lands.

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), and Factory. The full list is tracked at the official AGENTS.md site.

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 (AAIF) alongside Anthropic's Model Context Protocol and Block's Goose agent. 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 has an open feature request for native AGENTS.md support — given that Anthropic is an AAIF member, it's likely coming
• Gemini CLI already has a mature GEMINI.md system 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.

---

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.