← All articles

Coding

Understanding AGENTS.md: The Standard for AI Coding Agent Instructions

8 min read

Updated

Learn how to use AGENTS.md to configure coding guidelines, tech stacks, and project boundaries for AI coding tools like Copilot, Cursor, and Devin.

You have an AI coding agent running in your terminal or IDE. It can read your files, write code, and run commands. However, it does not automatically know that your project uses Tailwind CSS instead of CSS modules, that a specific legacy folder should remain untouched, or that tests must pass before any commit.

This is the problem that AGENTS.md solves.

What Is AGENTS.md?

AGENTS.md is a Markdown file placed in the root of your repository to provide AI coding agents with essential context about your project. It serves as developer onboarding documentation tailored specifically for AI agents, outlining your tech stack, coding standards, directory structure, boundaries, and validation workflows.

A basic AGENTS.md file 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 or strict schemas are required; it is standard Markdown that AI agents parse before initiating tasks.

AGENTS.md Adoption Status

Initially proposed as an open initiative in late 2025, AGENTS.md has transitioned to a cross-tool standard managed under the Linux Foundation's Agentic AI Foundation. It is supported across numerous developer tools and is utilized in thousands of open-source repositories.

Below is the compatibility landscape across major tools:

ToolReads AGENTS.mdNative AlternativesSubdirectory Support
OpenAI Codex CLIPrimary fileAGENTS.override.mdYes
GitHub CopilotYes.github/copilot-instructions.mdYes
CursorYes.cursor/rules/*.mdcYes
Windsurf (Devin Desktop)Yes.windsurfrulesYes
Amp (Sourcegraph)YesFalls back to CLAUDE.mdYes
DevinYesNoneYes
Claude CodeYesCLAUDE.md (richer native format)Yes
AiderYes.aider.conf.ymlYes
ZedYesNoneYes
Jules (Google)YesNoneYes
JetBrains JunieYesNoneYes
Gemini CLINot yetGEMINI.mdYes (for GEMINI.md)

Tool-Specific Integration Patterns

OpenAI Codex CLI

Codex CLI uses AGENTS.md as its primary instruction format. The CLI traverses from the Git root down to the active working directory, evaluating files at each level. The precedence order is AGENTS.override.md > AGENTS.md > fallback files like TEAM_GUIDE.md or .agents.md. Files located in deeper subdirectories override configuration files closer to the root. Codex also supports global preferences via ~/.codex/AGENTS.md.

Claude Code

Claude Code primarily targets CLAUDE.md for instruction handling, but it natively reads AGENTS.md when CLAUDE.md is absent. Many workflows reference AGENTS.md inside a minimal CLAUDE.md file to maintain a single source of truth. The format supports subdirectory scoping, allowing directory-specific instructions to be applied dynamically when navigating monorepos.

GitHub Copilot

GitHub Copilot supports AGENTS.md alongside its native .github/copilot-instructions.md file. It also supports file-path targeting using YAML frontmatter in .github/instructions/*.instructions.md files:

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

Gemini CLI

Google's Gemini CLI utilizes GEMINI.md files, which are read during directory traversal. It does not natively support AGENTS.md directly, meaning teams using Gemini CLI configure project contexts via GEMINI.md or global configurations in ~/.gemini/GEMINI.md.

Cursor

Cursor supports AGENTS.md alongside its newer .cursor/rules/ directory containing .mdc files. The newer .mdc format supports glob patterns to restrict instructions to specific folders:

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

AGENTS.md vs. Alternative Formats

While these configuration formats share a similar Markdown structure, their scoping and integration features differ:

  • AGENTS.md: The open, tool-agnostic standard. It contains no frontmatter or custom schema and is supported by the majority of agentic IDEs and command-line interfaces.
  • CLAUDE.md: Claude Code's native format. It uses standard Markdown but relies on Claude's multi-layered memory model (global, project, and directory levels).
  • Cursor Rules (.cursor/rules/*.mdc): Cursor-specific files containing YAML frontmatter to apply rules only to specific file extensions or subfolders.
  • .clinerules: Cline's project-specific rule file. Cline-only, requiring a separate configuration file or symbolic link if using multiple tools.

Recommended Configuration Hierarchy

For development environments using multiple AI platforms, the following structure maintains cross-tool compatibility without duplicating instructions:

project/
├── AGENTS.md              # Shared stack rules, code style, and build commands
├── CLAUDE.md              # Claude Code permissions, tool overrides, or MCP servers
├── GEMINI.md              # Gemini-specific CLI settings
├── .github/
│   └── copilot-instructions.md  # Copilot path-based configurations
└── .cursor/
    └── rules/             # Cursor-specific glob rules

How to Write an Effective AGENTS.md File

Poorly structured instruction files are often too generic ("write clean code") or unnecessarily long, wasting context window capacity. Follow these five guidelines to optimize your files:

1. Document Your Core Stack Upfront

Provide concrete version numbers and framework details to prevent the agent from guessing API patterns:

## Stack
- Python 3.12, FastAPI 0.115, SQLAlchemy 2.0 (async)
- PostgreSQL 16, Redis for caching
- Frontend: React 19 with Vite, Tailwind CSS v4

2. Focus on Rigid Boundaries

Vague styling preferences are less impactful than explicit, protective boundaries:

## Boundaries
- Never modify /db/migrations/ directly: run `alembic revision --autogenerate`
- Don't add new dependencies without listing them for monthly audits
- The /vendor/ directory is external code; do not edit it directly

3. Provide Code Templates

Demonstrate your specific architectural patterns using clear, minimal examples:

## Conventions
- API endpoints: `/api/v1/{resource}` (plural, lowercase)
- Database models: PascalCase (`UserProfile`, not `user_profile`)

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. Detail Verification and Testing Workflows
Tell the agent how to test and validate changes before considering a task finished:

```markdown
## 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

5. Keep Content Under 500 Lines

Every line in your root instruction file consumes token space in the agent's context window. Keep the root file brief and use subdirectory-specific files for localized, complex rules.

Real-World Templates

Template 1: TypeScript Web Application

# 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 Implementation Mistakes

  • Pasting Entire Style Guides: Do not duplicate 50-page coding standards in AGENTS.md. Focus on 10 critical operational rules and link to your wiki or documentation for deeper reference.
  • Vague Rules: Avoid subjective guidance like "follow best practices." Instead, use concrete instructions such as "use parameterized queries for database operations to prevent injection vulnerabilities."
  • Stale Configurations: Update the instruction file when changing tools or frameworks (e.g., migrating from Jest to Vitest) to prevent the agent from writing outdated tests.
  • Overusing Tool-Specific Rules globally: Put cross-tool commands and logic in AGENTS.md and save specific rules (like Cursor's globs or Claude Code's tools) for their respective files.

Frequently Asked Questions

What is AGENTS.md?
It is a Markdown file placed in a repository's root to supply AI development tools with context, including technology stacks, code conventions, API directories, and validation rules.

Which AI tools support AGENTS.md?
OpenAI Codex CLI, GitHub Copilot, Cursor, Windsurf, Amp, Devin, Aider, Zed, Jules, and JetBrains Junie all natively parse AGENTS.md. Claude Code supports it as a fallback format behind its native CLAUDE.md.

Should I use AGENTS.md or CLAUDE.md?
AGENTS.md is recommended as your primary file for project-wide conventions because it is supported across multiple IDEs and CLI assistants. Use CLAUDE.md or .cursor/rules/ for configurations unique to Claude Code or Cursor (like directory-scoped rules or API keys).