AGENTS.md Examples: 7 Copy-Paste Files for Real Projects (2026)

Published 2026-10-22 · 6 min read · by AgentKit Co

AGENTS.md is a plain Markdown file that tells AI coding agents how to work in your repo: which commands to run, where things live and what not to touch. Codex, Cursor, Jules, Aider, Gemini CLI, Copilot's coding agent and many other tools read it. There are no required fields, so the hard part is knowing what a good one looks like. Here are seven you can copy today, each with a note on why the lines are there.

Facts below were checked on 2026-10-20 against the AGENTS.md site and OpenAI's Codex AGENTS.md guide. Tools change fast, so re-check anything you depend on.

How agents find the file

• Put AGENTS.md at the repo root. For a monorepo, add more inside packages. Agents read the nearest file in the directory tree, so the closest one wins.
• If instructions conflict, the file closest to the edited code wins, and your chat prompt overrides everything.
• Codex also reads a personal file at ~/.codex/AGENTS.md, then walks from the repo root down to your current folder, reading at most one file per folder (AGENTS.override.md first, then AGENTS.md). Files are joined root first, so deeper files appear later and take priority.
• Codex stops adding files once the combined size reaches 32 KiB by default (project_doc_max_bytes). Short files are not just tidier, they keep working.

Example 1: a Next.js app

# AGENTS.md

## Project
Storefront: Next.js 15 (App Router), TypeScript strict, Tailwind, Prisma + Postgres.

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev` (port 3000)
- Test one file: `pnpm vitest run path/to/file.test.ts`
- Before finishing: `pnpm lint && pnpm typecheck && pnpm test`

## Layout
- `app/` routes; server components by default.
- `lib/db.ts` is the only place that creates a Prisma client.

## Conventions
- Add `"use client"` only when a component needs state or browser APIs.
- Money is integer cents everywhere. Format with `lib/money.ts`.

## Boundaries
- Ask before adding a dependency or editing `prisma/schema.prisma`.
- Never commit `.env*` files.

Why it works: the commands section is the highest-value part, because agents run what you list. The site's FAQ says it plainly: list the test commands and the agent will try to run them and fix failures before finishing.

Example 2: a Python API

# AGENTS.md

## Project
Billing API: Python 3.12, FastAPI, SQLAlchemy 2, Alembic, managed with uv.

## Commands
- Setup: `uv sync`
- Run: `uv run fastapi dev app/main.py`
- Test: `uv run pytest -q` (one test: `uv run pytest tests/test_invoices.py -k refund`)
- Lint and format: `uv run ruff check --fix . && uv run ruff format .`

## Conventions
- Type hints on every public function; `mypy` must pass.
- Request and response bodies are Pydantic models in `app/schemas/`.
- Database changes need an Alembic migration: `uv run alembic revision --autogenerate -m "..."`.

## Boundaries
- Don't edit files in `alembic/versions/` that are already merged.
- Ask before changing anything under `app/payments/`.

Why it works: it names the tool (uv), so the agent doesn't fall back to bare pip, and it shows how to run one test, which saves minutes on every loop.

Example 3: a Go service

# AGENTS.md

## Commands
- Build: `go build ./...`
- Test: `go test ./...` (race check before finishing: `go test -race ./...`)
- Lint: `golangci-lint run`

## Conventions
- Wrap errors with context: `fmt.Errorf("load user %d: %w", id, err)`.
- Pass `context.Context` as the first argument to anything that does I/O.
- Table-driven tests; copy the style in `internal/store/store_test.go`.

## Boundaries
- Generated files (`*.pb.go`, `*_gen.go`) are rebuilt with `make gen`; never hand-edit them.

Why it works: each convention points to a real file to copy from, which beats a paragraph of style advice.

Example 4: a monorepo root plus a nested package

Root AGENTS.md:

# AGENTS.md (repo root)

## Workspace
pnpm + Turborepo. Apps in `apps/`, shared code in `packages/`.

## Commands
- Run checks for one package: `pnpm turbo run lint test --filter <package-name>`
- The package name is the `name` field in that package's `package.json`, not the folder name.

## Rules for every package
- Shared types live in `packages/types`. Don't redefine them locally.
- Each package has its own AGENTS.md; follow it when working there.

packages/ui/AGENTS.md:

# AGENTS.md (packages/ui)

- Components are React + TypeScript, one folder each with a `*.stories.tsx`.
- Run `pnpm --filter @acme/ui test` and `pnpm --filter @acme/ui build-storybook`.
- No app-specific logic here; ui must not import from `apps/`.

Why it works: the root stays short and general, and each package carries its own details. The AGENTS.md site notes that OpenAI's main repo had 88 of these files at the time of writing.

Example 5: your personal ~/.codex/AGENTS.md

# ~/.codex/AGENTS.md

## Working agreements
- Explain the plan in 3 bullets before editing more than 3 files.
- Prefer small diffs; don't reformat code you didn't change.
- Ask before adding a production dependency.
- When a command fails, show the error and your fix, don't retry silently.

Why it works: it holds preferences that follow you to every repo, so project files can stay about the project. Don't put project commands here.

Example 6: an override file for a sensitive folder

services/payments/AGENTS.override.md:

# Payments service rules

- Use `make test-payments` instead of `npm test`.
- Every change needs a test that covers the failure path.
- Never log card data, tokens or full customer emails.
- Ask before touching anything in `migrations/`.

Why it works: in Codex, an AGENTS.override.md in a folder is read instead of that folder's AGENTS.md, so a team can tighten rules for one service without editing the shared file. Other tools may only read AGENTS.md, so if you need the rules everywhere, keep them in the normal file.

Example 7: code review rules

## Code Review Rules

- Flag any SQL built with string formatting. Safe path: use parameters.
- Flag new endpoints without an auth check. Exception: routes under `/public`.
- Don't comment on formatting; CI handles that.

Why it works: Codex's GitHub code review reads a ## Code Review Rules section from the AGENTS.md closest to the code. OpenAI's advice is to say what to flag, give the safe path or exception, and leave lint checks to CI.

Using one file with every tool

• Claude Code: add @AGENTS.md to your CLAUDE.md so both share one source. Our AGENTS.md vs CLAUDE.md vs Cursor rules guide covers the differences.
• Aider: add read: AGENTS.md to .aider.conf.yml.
• Gemini CLI: set "context": { "fileName": "AGENTS.md" } in .gemini/settings.json.
• Old file names: the AGENTS.md site suggests renaming and linking back, for example mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md. Codex can also read other names through project_doc_fallback_filenames in ~/.codex/config.toml.

What to leave out

1. Anything a linter already enforces. Formatting rules waste space.
2. Long procedures. A ten-step release checklist belongs in a doc the file links to.
3. Vague advice. "Write clean code" changes nothing. "Wrap errors with context, like internal/store" does.
4. Secrets and personal data. The file goes in git.
5. Stale commands. If the file says npm test and the repo moved to pnpm, the agent will run the wrong thing. Treat AGENTS.md as living documentation, as the spec says.

More on choosing sections: how to write an AGENTS.md that agents follow.

Skip the blank page

Our free AGENTS.md generator reads your real package.json or pyproject.toml in the browser and drafts a file with your actual commands. Want more? The AI Coding Agent Config Kit ($14) has AGENTS.md templates for 12 stacks, Cursor rules and prompts that draft and audit your own files.

Sources: agents.md and Codex: custom instructions with AGENTS.md (both checked 2026-10-20). AgentKit Co is not affiliated with OpenAI, Anthropic or the Agentic AI Foundation. This guide was written with AI assistance and checked against the pages above.

Keep reading