AGENTS.md Template: 7 Copy-Paste Examples for 2026

Every coding agent you use can be pointed at the same file: AGENTS.md. It is plain Markdown, it has no required fields, and per agents.md — the site maintaining the format — it is already "used by over 60k open-source projects". If your agent still ignores your test command, adds a duplicate HTTP client, or refactors files you never touched, the fix is usually not a better prompt. It is an instruction the agent reads before it starts.

This page is the template library: format rules in one table, a support matrix limited to tools whose own documentation confirms it, and seven copy-paste templates for real project shapes.

TL;DR — the AGENTS.md format at a glance

Who actually reads AGENTS.md

Only tools I could confirm in writing today are listed; each row cites the vendor's own documentation, not the format site's compatibility list.

Also listed as compatible on agents.md, without behavior detail here: Factory, goose, Zed, Devin, UiPath, Junie, Amp, RooCode, Kilo Code, Phoenix, Semgrep, Ona, Windsurf, Augment Code, Jules, VS Code.

Where the file goes, and which one wins

Root-level is the default. For big repos the format's advice is explicit: "Place another AGENTS.md inside each package. Agents automatically read the nearest file in the directory tree, so the closest one takes precedence and every subproject can ship tailored instructions." agents.md notes the main OpenAI repository carries 88 AGENTS.md files.

Three mechanics matter once you nest:

• Merge vs. replace. Codex concatenates files from root down to your working directory, so a nested file adds to the root file and overrides it by appearing later. Devin Desktop infers activation from location instead: root = always-on, subdirectory = scoped glob.
• Size caps. Codex stops adding files once combined size reaches project_doc_max_bytes, "32 KiB by default". Documented remedies: raise the limit, or split instructions across nested directories.
• Chat outranks the file. Explicit prompts override everything, and if you list test commands the agent "will attempt to execute relevant programmatic checks and fix failures before finishing the task."

The minimal skeleton

Every template below is a variation on this — the shortest version that consistently helps.

# AGENTS.md

## Project

Next.js 15 app router dashboard, Postgres. README.md has product context.

## Commands

- install: pnpm install
- dev: pnpm dev
- lint: pnpm lint
- test: pnpm test
- single test: pnpm test -- <path>

## Rules

- TypeScript strict; no `any` without a `// reason:` comment
- Prefer editing existing files over creating new ones
- Never commit .env or anything that looks like a key

7 copy-paste AGENTS.md templates

Before you copy anything, read two real ones: agents.md links production files in openai/codex, apache/airflow, temporalio/sdk-java, and PlutoLang/Pluto, plus a GitHub code search for path:AGENTS.md. These seven are the shapes those files converge on.

1. TypeScript / React application

# AGENTS.md

## Stack

Vite + React 19 + TypeScript (strict) + Tailwind. Package manager: pnpm only.

## Commands, in order

1. `pnpm install --frozen-lockfile`
2. `pnpm typecheck`
3. `pnpm lint`
4. `pnpm test`
5. `pnpm build`
   Stop and report the first failing step; do not continue past it.

## Conventions

- Components: one file each, named export, no default exports
- Data fetching lives in `src/hooks/use-*.ts`, never in a component body
- Shared types in `src/types/`; do not redeclare a props type inline twice
- New dependency: name it and its size in your summary before adding it

## Do not

- Migrate class components you were not asked to touch
- Add `use client` markers — this is a Vite SPA

2. Python service or CLI

# AGENTS.md

## Environment

Python 3.12, managed with uv. `uv sync` to install, never `pip install` by hand.

## Commands

- run: `uv run python -m app.cli --help`
- test: `uv run pytest -q`
- one test: `uv run pytest tests/test_orders.py::test_refund -q`
- lint: `uv run ruff check . && uv run ruff format --check .`
- types: `uv run mypy app/`

## Conventions

- Type hints on every public function; no `typing.Any` in signatures
- Raise typed exceptions from `app/errors.py`; no `print()` in library code
- Use `httpx` over `requests`; Pydantic models at the boundary
- Every bug fix needs a regression test; run `pytest` before summarizing

3. Go or Rust CLI

# AGENTS.md

## Go

- Build: `go build ./...` Test: `go test ./...`
- Lint: `gofmt -l .` must print nothing; then `golangci-lint run`
- Errors: wrap with `fmt.Errorf("...: %w", err)`; never panic in library code
- Tables for tests: `name`, `input`, `want` — one `t.Run` per case
- No new module dependencies without stating why the stdlib is not enough

## Rust equivalents

- `cargo fmt --check`, `cargo clippy -- -D warnings`, `cargo test`
- No `.unwrap()` in `src/`; return `Result` and use `?`

4. Monorepo root file

# AGENTS.md

## Layout

- `packages/ui` — presentational components, no data access
- `packages/core` — domain logic, framework-free
- `apps/web`, `apps/api` — composition roots only

## Working in this repo

- Turbo filters everything: `pnpm turbo run test --filter=<pkg>`
- After adding a package: `pnpm install --filter <pkg>` so the workspace sees it
- Cross-package imports go through a package's public entry point, never deep paths

## Nested instructions

Every package has its own AGENTS.md. Read the nearest one; this file is the shared floor.

5. Strict gate version (tests + lint as blockers)

# AGENTS.md

## Definition of done — all four must pass, in order

1. `pnpm typecheck`
2. `pnpm lint --max-warnings 0`
3. `pnpm test -- --coverage` (80% on changed files)
4. `pnpm build`

## Hard rules

- If a check fails, fix it before writing more code. Never leave a red suite.
- Do not weaken a test, delete an assertion, or add a skip to make CI pass —
  report the conflict instead of resolving it silently.
- Do not touch `pnpm-lock.yaml`, migrations, or generated files unless asked.

## Escalate instead of guessing when

- The task needs a schema change, a new env var, or a new dependency.
- Two conventions in this repo contradict each other.

6. CLI-agent global file (Codex and friends)

Global guidance lives in your tool's home directory so every repo inherits it. For Codex that is ~/.codex/AGENTS.md (AGENTS.override.md replaces it there; CODEX_HOME relocates the directory).

# ~/.codex/AGENTS.md

## Working agreements

- State your plan in three bullets before editing more than two files.
- Prefer `rg` over walking the tree with `ls`.
- Run the repo's test command after each edit batch, not only at the end.
- Ask before adding a production dependency.

## Never

- No `git push`, no `--force`, no amending commits you did not create.
- No committing generated files or anything secret-looking.

Verify rather than assume: Codex's documented check is codex --ask-for-approval never "Summarize the current instructions.", which echoes your global and project files in precedence order.

7. Layered codebase with dependency rules

The highest-value AGENTS.md encodes an architecture an agent cannot infer from filenames.

# AGENTS.md

## Architecture

`core/` (infrastructure) ← `modules/` (business logic) ← `routes/` (HTTP) ← `components/` (UI).
Imports point one direction only. Nothing imports another module's internals.

## Per-module shape

- `modules/<name>/service.ts` — pure functions, no framework imports
- `routes/api/<name>.ts` — auth check, parse input, call service, return the standard envelope
- Responses use `{ code, message, data }`; errors use the same shape

## Forbidden

- SQL outside a service file
- Skipping auth because a handler "looks internal"
- Cross-module imports (one documented exception exists; ask first)

What belongs, and what makes an agent worse

Include what an agent cannot see in the code: command order, conventions written down nowhere, files it must not touch, the point at which it should stop and ask. Exclude anything derivable from the repo.

Devin Desktop's documentation puts the test bluntly — "Concrete examples and explicit conventions work better than vague guidelines" — and contrasts Use TypeScript strict mode with Write good code.

Rules of thumb that hold across the tools above:

Keep it short. Instruction files that exceed a tool's byte cap do not fail loudly — Codex truncates, and the rules at the bottom go first.

FAQ

Is there a required AGENTS.md format or schema? No. Asked "Are there required fields?", the official FAQ answers: "No. AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide." Sections are convention, not syntax.

AGENTS.md or CLAUDE.md — which should I write? AGENTS.md if you use more than one agent: it is the cross-tool name, and Claude Code reads it when no CLAUDE.md exists (changelog 2.1.277). Copilot CLI discovers AGENTS.md, CLAUDE.md, and GEMINI.md in the same pass, so one shared file covers all three. Keep CLAUDE.md for Claude-specific settings only.

Does it work for Python or Go, not just TypeScript? Yes — the format is language-agnostic. Only the commands change: template 2 uses uv/ruff/mypy, template 3 uses gofmt/golangci-lint. Write the exact invocation, because that is what agents get wrong when it is not on paper.

Can I use it as a global Codex config? Yes. Codex reads ~/.codex/AGENTS.md (or AGENTS.override.md) before project files, so reusable agreements live there and repo specifics stay in the repo. project_doc_fallback_filenames adds legacy names like TEAM_GUIDE.md to discovery.

Should AGENTS.md be committed to git? Yes — that is how everyone else's agents get the same instructions, and opencode's docs say so. The exception is agent-workspace use like OpenClaw's, where the file is private state best kept in a private repository.

Why does my agent still ignore the file? Four documented causes: a nearer AGENTS.override.md (Codex) or WARP.md in the same directory (Warp) is winning; combined size hit the byte cap; the filename case is wrong (Warp needs all caps, though Devin Desktop accepts agents.md); or your chat prompt outranked it. Copilot CLI's /instructions and Codex's instruction-summary probe both show what actually loaded.

Related

• DeepSeek harness setup guide — the terminal-agent wiring your AGENTS.md describes
• OpenCode tutorial — install, /init, and running an agent on free models
• Claude Code Router tutorial — when CLAUDE.md and AGENTS.md point at different models
• Antigravity YOLO mode guide — what changes when an agent skips approval gates
• Claude Code for game development — project instructions in practice
• Claude Projects templates — the same "write it down once" idea inside Claude Projects

A well-scoped AGENTS.md is an hour of work that never expires the way a prompt does. Start from the skeleton, add the two commands your agent gets wrong, and stop there.