AGENTS.md Guide

Templates, examples, and best practices for AI agent context files

What Is AGENTS.md?

AGENTS.md is a Markdown file in your project’s root directory that gives AI coding agents the context they need to work on your codebase. It describes your project’s architecture, coding conventions, build commands, and constraints — so agents produce code that fits your project from the first attempt.

Every major AI coding tool uses a file like this. Claude Code reads CLAUDE.md, GitHub Copilot reads .github/copilot-instructions.md, and Cursor reads .cursor/rules. AGENTS.md is the cross-tool convention — a single file that any AI agent can understand.

The concept is straightforward: instead of explaining your project in every prompt, you write the instructions once. The agent reads them automatically at the start of every session.

Quick Start

Create an AGENTS.md file in your project root with these basics:

AGENTS.md (minimal) # Agent Instructions ## Stack Node.js 20, TypeScript, PostgreSQL ## Commands - `npm run dev` — start dev server - `npm test` — run tests - `npm run lint` — check code style ## Rules - TypeScript strict mode, no `any` - Tests required for all new endpoints - Never commit .env files

This 12-line file already saves you from repeating “use TypeScript strict mode” and “run npm test” in every prompt.

AGENTS.md Template

A comprehensive template that covers everything an AI agent needs to know about your project. Copy this and fill in your details:

AGENTS.md (full template) # Agent Instructions ## Project Overview E-commerce API built with Node.js, Express, PostgreSQL. Monorepo managed with Turborepo. ## Commands - `npm run dev` — start all services with hot reload - `npm test` — run Jest tests - `npm run test:e2e` — end-to-end tests (requires running DB) - `npm run migrate` — run database migrations - `npm run lint` — ESLint + Prettier check - `npm run build` — production build ## Architecture - `apps/api/` — Express REST API - `apps/web/` — Next.js frontend - `packages/db/` — Sequelize models and migrations - `packages/shared/` — shared types and utilities ## Conventions - TypeScript strict mode everywhere - Functional style — no classes except Sequelize models - Error handling: throw AppError, not generic Error - API responses follow JSON:API format - Date/time: always UTC, use date-fns ## Constraints - Never expose internal IDs in API responses (use UUIDs) - Rate limiting on all public endpoints - No raw SQL — use Sequelize query builder - Do not modify `packages/auth/` without explicit approval - Max bundle size: 200KB (web), check with `npm run analyze` ## Testing - Unit tests next to source: `foo.test.ts` - E2E tests in `tests/e2e/` - Minimum 80% coverage for new code - Mock external services, never call real APIs in tests ## Deployment - Main branch auto-deploys to staging - Production requires PR approval + passing CI - Database migrations run automatically on deploy

AGENTS.md Examples by Stack

Here are ready-to-use templates for common tech stacks. Copy the one that matches your project and customize it.

TypeScript / Next.js

AGENTS.md (Next.js) # Agent Instructions ## Stack Next.js 15 (App Router), TypeScript, Tailwind CSS, Prisma, PostgreSQL ## Commands - `npm run dev` — dev server on localhost:3000 - `npm test` — Vitest - `npx prisma migrate dev` — run migrations - `npx prisma generate` — regenerate client after schema change ## Architecture - `app/` — routes and layouts (App Router) - `app/api/` — API route handlers - `components/` — shared React components - `lib/` — utilities, database client, auth - `prisma/schema.prisma` — database schema ## Conventions - Server components by default, 'use client' only when needed - Tailwind CSS only — no CSS modules, no inline styles - Use `cn()` from lib/utils for conditional classes - Zod for all input validation - Server actions for form mutations ## Constraints - No `any` type — use `unknown` and narrow - Images through next/image only - Environment variables: validated in lib/env.ts, never accessed directly

Python / FastAPI

AGENTS.md (Python) # Agent Instructions ## Stack Python 3.12, FastAPI, SQLAlchemy 2.0, PostgreSQL, uv ## Commands - `uv run fastapi dev` — dev server with auto-reload - `uv run pytest` — run tests - `uv run pytest --cov` — tests with coverage - `uv run ruff check .` — lint - `uv run ruff format .` — format - `uv run alembic upgrade head` — run migrations ## Architecture - `app/api/` — route handlers grouped by domain - `app/models/` — SQLAlchemy models - `app/schemas/` — Pydantic request/response schemas - `app/services/` — business logic - `app/core/` — config, security, database setup ## Conventions - Type hints on all functions (mypy strict) - Pydantic v2 models for request/response validation - Dependency injection via FastAPI Depends() - Async endpoints with async SQLAlchemy sessions - snake_case everywhere (PEP 8) ## Constraints - No ORM queries in route handlers — use service layer - Alembic for all schema changes, no raw DDL - Secrets in environment variables only, never in code

Go

AGENTS.md (Go) # Agent Instructions ## Stack Go 1.23, Chi router, sqlc, PostgreSQL ## Commands - `go run ./cmd/server` — start server - `go test ./...` — run all tests - `go test -race ./...` — tests with race detector - `sqlc generate` — regenerate query code - `golangci-lint run` — lint ## Architecture - `cmd/server/` — main entry point - `internal/handler/` — HTTP handlers - `internal/service/` — business logic - `internal/store/` — database layer (sqlc generated) - `internal/middleware/` — auth, logging, rate limiting - `sql/queries/` — SQL queries for sqlc ## Conventions - Accept interfaces, return structs - Errors: wrap with fmt.Errorf("operation: %w", err) - Context passed as first argument - Table-driven tests - No init() functions ## Constraints - No global state or package-level variables - No external HTTP calls without context timeout - All SQL through sqlc — no raw database/sql queries

AGENTS.md vs CLAUDE.md vs Other Files

Every AI coding tool has its own context file. Here is how they compare:

File Tool Location Scope
AGENTS.md Cross-agent Project root (+ subdirectories) Universal agent instructions
CLAUDE.md Claude Code Project root (+ subdirectories) Claude-specific: memory, hooks, slash commands
copilot-instructions.md GitHub Copilot .github/ Copilot-specific instructions
.cursor/rules Cursor .cursor/ Cursor AI rules and context
README.md All tools Project root General project overview (for humans and agents)

Which should you use? Start with AGENTS.md for universal instructions. Add CLAUDE.md if you use Claude Code and want Claude-specific features. Add tool-specific files only if your team uses those tools and needs vendor-specific settings.

Many teams use AGENTS.md as the single source of truth and reference it from tool-specific files. For example, a .github/copilot-instructions.md might simply say: “Follow the instructions in AGENTS.md at the project root.”

Directory-Specific Instructions

Large projects benefit from AGENTS.md files at multiple levels. Each subdirectory can have its own AGENTS.md with module-specific rules:

  • ./AGENTS.md — global project conventions and build commands
  • ./frontend/AGENTS.md — React component patterns, styling rules
  • ./backend/AGENTS.md — API design, database conventions
  • ./infra/AGENTS.md — Terraform patterns, deployment process
  • ./mobile/AGENTS.md — Swift/Kotlin conventions, platform constraints

When an agent works in ./frontend/, it reads both the root AGENTS.md and the frontend-specific one. This keeps the root file short while giving each module detailed context.

Best Practices

  • Keep it under 200 lines — every line consumes context window tokens. A bloated AGENTS.md leaves less room for actual code in the AI’s working memory.
  • Commands over descriptions — write npm test -- --watch, not “we use Jest with watch mode for development testing.”
  • State constraints as rules — “Never use any type” is clearer than “we prefer strong typing.”
  • Link, don’t duplicate — “See docs/auth.md for auth architecture” keeps your AGENTS.md lean. The agent can read linked files when needed.
  • Review in pull requests — treat AGENTS.md changes like code changes. A wrong instruction in AGENTS.md produces wrong code across the entire project.
  • Update when things change — stale instructions cause wrong code. When you rename a directory, change a convention, or switch a dependency, update AGENTS.md in the same PR.
  • Test your instructions — after writing AGENTS.md, start a fresh AI session and ask the agent to make a small change. If it gets it right without extra prompting, your file is working.

Common Mistakes

  • Too long — a 500-line AGENTS.md wastes tokens and buries the important constraints. Aim for 50–200 lines.
  • Too vague — “Write clean code” tells an AI nothing. “Use early returns, max 30 lines per function, no nested ternaries” is actionable.
  • Duplicating README.md — agents already read README.md. AGENTS.md should contain operational instructions that a human developer would not need (which commands to run, which patterns to follow, what not to touch).
  • Forgetting constraints — the most valuable part of AGENTS.md is what NOT to do. If there are modules the AI should never modify, authentication flows it should not change, or dependencies it should not add — state those explicitly.
  • Never updating it — AGENTS.md that describes last quarter’s architecture actively harms code quality. Update it when the project changes.

Multi-Agent Workflows

Modern development often involves multiple AI agents working together — one writing code, one reviewing, one running tests. AGENTS.md gives all of them the same baseline context:

  • The coding agent knows which patterns to follow and which files not to touch
  • The review agent knows which constraints to check and what conventions to enforce
  • The testing agent knows which commands to run and what coverage to expect

Without a shared context file, each agent would need separate instructions in every prompt — and those instructions would inevitably drift apart.

Why Markdown for Agent Context?

  • Token-efficient — Markdown uses fewer tokens than JSON or XML for structured text. A 100-line AGENTS.md costs roughly 1,500 tokens, leaving more room for code.
  • Human-editable — developers read and write it without special tools or syntax knowledge
  • Git-friendly — clean diffs in pull requests, blame history for every instruction
  • Structured enough — headings, lists, and code blocks provide semantic structure that AI models parse reliably
  • Universal — every AI model understands Markdown from training data

For the full reasoning, see Why AI Tools Use Markdown.

Related Guides

View AGENTS.md with MDViewer

MDViewer renders AGENTS.md with full formatting — headings, code blocks, syntax highlighting, and links. See your agent instructions the way the AI sees them. Edit inline, preview changes, and keep your context files up to date.

Download MDViewer

Requires macOS 13.0 or later. Intel and Apple Silicon.