When a new engineer joins your team, you do not just hand them the codebase and say “good luck.” You give them onboarding docs, explain the build system, point out where the tests live, and warn them about the parts of the code they should not touch.
AI coding agents need the same thing. Without project context, an agent will guess at your conventions, use the wrong test runner, miss your branching strategy, and generally produce code that does not fit your project. AGENTS.md solves this by giving agents a structured onboarding document they can read before they start working.
Imagine your company gives every new hire a one-page cheat sheet on day one. It lists the WiFi password, how to run the build, where to find the style guide, and what never to touch. AGENTS.md is that cheat sheet - but for AI agents working on your codebase.
Key takeaway: AGENTS.md is a simple Markdown file you place in your repo to tell AI agents how to work on your project. Most major AI coding tools read it automatically.
AGENTS.md is an open-format Markdown file that lives in your repository. It provides instructions and context to AI coding agents - tools like Claude Code, Cursor, GitHub Copilot, Gemini, and others.
There is no special schema, no YAML frontmatter requirement, no tooling dependency. It is plain Markdown. You write it like you would write instructions for a human, because that is essentially what it is - instructions for an AI that reads like a human.
Without AGENTS.md, every time you use an AI coding agent you end up repeating yourself:
make lint before committing”src/api/, the frontend is in web/”vendor/”AGENTS.md captures this once, in one place, so every agent that touches your code starts with the right context.
AGENTS.md file in the root of your repositoryAGENTS.md files in subdirectories for area-specific guidanceThat is it. No configuration, no build step, no integration work.
AGENTS.md emerged in August 2025 from a collaboration between OpenAI (Codex), Amp, Google (Jules), Cursor, and Factory. Rather than each company creating its own proprietary format, they agreed on a shared, open standard.
In December 2025, AGENTS.md was contributed to the Agentic AI Foundation (AAIF) under the Linux Foundation, alongside Anthropic’s Model Context Protocol (MCP) and Block’s Goose. It is now a foundation-stewarded open standard.
As of early 2026, over 60,000 open-source repositories include an AGENTS.md file.
Analysis of thousands of real repositories has identified six core areas that make the biggest difference:
The exact commands to build, lint, test, and run your project. Be specific - include flags and options, not just tool names.
## Commands
- Build: `npm run build`
- Lint: `npm run lint -- --fix`
- Test all: `npm test`
- Test single file: `npm test -- --testPathPattern=<filename>`
- Dev server: `npm run dev` (runs on port 3000)
- Type check: `npx tsc --noEmit`
Why this matters: agents that know the exact commands can verify their own work by running tests and linting before presenting results.
How tests are organized, what framework you use, and any conventions the agent should follow when writing new tests.
## Testing
- Framework: pytest with pytest-asyncio for async tests
- Test location: tests mirror src structure (src/api/users.py -> tests/api/test_users.py)
- Naming: test files start with `test_`, test functions start with `test_`
- Fixtures: shared fixtures live in tests/conftest.py
- Run a single test: `pytest tests/api/test_users.py::test_create_user -v`
A map of where things live. Agents work better when they know which directories to look in.
## Project Structure
- `src/api/` - REST API endpoints (FastAPI)
- `src/core/` - Business logic, domain models
- `src/db/` - Database models and migrations (SQLAlchemy + Alembic)
- `src/workers/` - Background task processors
- `web/` - React frontend (Vite + TypeScript)
- `infra/` - Terraform infrastructure definitions
- `scripts/` - Developer utility scripts
Naming conventions, formatting rules, and preferred patterns. A short code snippet showing your style is worth more than paragraphs of description.
## Code Style
- Python: Black formatting, isort for imports, Google-style docstrings
- TypeScript: Prettier + ESLint, functional components with hooks
- Naming: snake_case for Python, camelCase for TypeScript
- Prefer explicit over implicit - no magic imports or star exports
- Error handling: use custom exception classes from src/core/exceptions.py
Branching strategy, commit message conventions, and PR requirements.
## Git Workflow
- Branch from `main`, prefix with `feat/`, `fix/`, or `chore/`
- Commit messages: conventional commits format (e.g., "feat: add user search endpoint")
- Squash merge PRs
- All PRs require passing CI and one approval
What the agent should never touch. This is one of the most important sections.
## Do Not Modify
- `vendor/` - third-party code, managed externally
- `.env` files - contain secrets, never commit
- `infra/production/` - production infrastructure, requires manual review
- `src/db/migrations/` - generate migrations with Alembic, do not write by hand
- `package-lock.json` - only modify via npm install
You can place AGENTS.md files at multiple levels of your directory tree. Agents read the nearest file in the current directory or its parents. This is useful for monorepos where different areas have different conventions.
my-monorepo/
AGENTS.md # Shared conventions (git workflow, CI, etc.)
services/
api/
AGENTS.md # Python-specific: pytest, Black, FastAPI patterns
frontend/
AGENTS.md # TypeScript-specific: Vitest, Prettier, React patterns
ml-pipeline/
AGENTS.md # Python + notebooks: data conventions, model testing
Each sub-project’s AGENTS.md can focus on what is unique to that area. The root-level file covers shared practices.
Multiple AI tools have their own instruction file formats. The content across all of them overlaps significantly - build commands, coding standards, project structure. The differences are tool-specific features.
| File | Tool | Special Features |
|---|---|---|
| AGENTS.md | Cross-tool standard | Universal, no special syntax, read by most agents |
| CLAUDE.md | Claude Code | Supports @path imports for modular instructions |
| .cursorrules / .mdc | Cursor | YAML frontmatter with activation modes (Always, Auto, Agent Requested) |
| .github/copilot-instructions.md | GitHub Copilot | Scoped .instructions.md files with glob patterns |
| GEMINI.md | Gemini | Gemini-specific instructions |
Put shared instructions in AGENTS.md. Most tools read it. Use tool-specific files only when you need features unique to that tool.
If you already have a CLAUDE.md or .cursorrules file, you do not necessarily need to duplicate everything into AGENTS.md. But if you want your instructions to work across multiple tools, AGENTS.md is the common denominator.
Aim for 150 lines or fewer. Long files bury important information and waste agent context window tokens. If your AGENTS.md is longer than your README, it is probably too long.
Bad: “We use a modern JavaScript stack” Good: “React 18 with TypeScript 5.3, Vite 5, and Tailwind CSS 3.4”
Bad: “Follow standard testing practices”
Good: “Run npm test -- --coverage and maintain >80% line coverage on new code”
A code example communicates style more effectively than a paragraph of description.
## API Endpoint Pattern
New endpoints should follow this structure:
\```python
@router.post("/users", response_model=UserResponse, status_code=201)
async def create_user(
request: CreateUserRequest,
db: AsyncSession = Depends(get_db),
current_user: User = Depends(get_current_user),
) -> UserResponse:
"""Create a new user account."""
user = await user_service.create(db, request)
return UserResponse.from_orm(user)
\```
Start with a minimal AGENTS.md. When you notice an agent making the same mistake repeatedly, add an instruction to address it. The best AGENTS.md files grow through iteration, not upfront planning.
Update AGENTS.md in the same PR when you change build processes, test conventions, or project structure. Stale instructions are worse than no instructions, because they actively mislead agents.
For non-obvious rules, a brief explanation helps the agent apply the rule correctly in edge cases.
- Do not use `datetime.now()` directly. Use `src/core/clock.py` instead.
This allows tests to control time without monkeypatching.
Here is a realistic AGENTS.md for a Python web application:
# AGENTS.md
## Project
Order management API built with FastAPI and PostgreSQL.
Python 3.12, managed with Poetry.
## Commands
- Install dependencies: `poetry install`
- Run dev server: `poetry run uvicorn src.main:app --reload --port 8000`
- Run all tests: `poetry run pytest`
- Run single test: `poetry run pytest tests/path/to/test.py -v`
- Lint: `poetry run ruff check src tests`
- Format: `poetry run ruff format src tests`
- Type check: `poetry run mypy src`
- Generate migration: `poetry run alembic revision --autogenerate -m "description"`
- Apply migrations: `poetry run alembic upgrade head`
## Project Structure
- `src/api/` - API route handlers
- `src/core/` - Business logic and domain models
- `src/db/` - SQLAlchemy models and Alembic migrations
- `src/services/` - External service integrations
- `tests/` - Mirrors src structure
## Code Style
- Ruff for linting and formatting (config in pyproject.toml)
- Google-style docstrings on public functions
- Type hints on all function signatures
- Prefer `async def` for all route handlers
- Use dependency injection via FastAPI's `Depends()`
## Testing
- pytest with pytest-asyncio
- Use factories from `tests/factories.py` to create test data
- Tests run against a real PostgreSQL database (not mocks)
- Each test function gets a fresh transaction that rolls back
## Git
- Branch naming: `feat/`, `fix/`, `chore/` prefixes
- Conventional commits
- Squash merge to main
## Do Not Modify
- `alembic/versions/` - Do not edit migration files by hand
- `.env` and `.env.local` - Contains secrets
- `src/core/legacy_adapter.py` - Scheduled for removal, do not add new code here
AGENTS.md handles project-level context well. But there are situations where you need more:
AGENTS.md is the foundation. Think of it as the first layer of context that makes everything else work better.
AGENTS.md file in one of your projects