AGENTS.md Examples: Templates for Python, TypeScript and Monorepos

An AGENTS.md is a plain Markdown file at the root of a repository that tells a coding agent how to work there: how to set up, the exact build and test commands, the conventions that differ from the defaults, and what not to touch. There are no required fields and no special syntax. A good one reads like the note you would leave a capable contractor on their first morning, and is short enough to read in two minutes. Below are three annotated examples, a Python project, a TypeScript app and a monorepo root with a nested file, then how long the file should be, what to leave out, and which tools read it. How AGENTS.md sits beside CLAUDE.md, Copilot’s files and Cursor rules, and which wins when several apply, is in AI context files compared.

The format in one paragraph

The AGENTS.md site↗ (opens in a new tab) describes it as a simple, open format for guiding coding agents, now stewarded by the Agentic AI Foundation under the Linux Foundation. It is standard Markdown: use any headings you like. The sections it lists as popular are a project overview, build and test commands, code style, testing instructions, security considerations, commit and pull request guidelines, and deployment steps. In a monorepo you put another AGENTS.md inside each package, and the nearest file to what is being edited takes precedence. If you list test commands, agents will try to run them and fix failures before they finish, which is the single best reason to get the commands exactly right.

Example 1: a Python project

# Clinic bookings

Django 5 web app for booking appointments at three clinics. Python 3.12,
dependencies managed with Poetry, PostgreSQL in every environment (also in tests).

## Setup
- `poetry install`
- `docker compose up -d db`, then `poetry run python manage.py migrate`

## Test and check
- All tests: `poetry run pytest`
- One test: `poetry run pytest bookings/tests/test_slots.py -k overlapping`
- Before finishing: `poetry run ruff check . && poetry run ruff format --check .`

## Conventions
- Business rules live in bookings/services/. Views and serializers call
  services; they never query across apps themselves.
- Times are stored in UTC and shown in the clinic's own time zone.
- Every model change ships with its migration in the same commit.

## Do not
- Edit a migration that is already on main. Add a new one.
- Touch settings/production.py. Ask instead.

## Pull requests
- Title: "<app>: <what changed>", for example "bookings: stop double-booking a slot".

• The first two lines are the overview: what it is, the versions, and the one fact that breaks tests on a clean machine, the database.
• Setup is in the order it must run. An agent that migrates before the database is up wastes its first few minutes.
• The one-test command sits beside the full suite. Agents check a change far more often than they run everything.
• Conventions state the rule an agent would otherwise break, where the rule lives, and in the time zone case, the behaviour to expect.
• Every “do not” is paired with what to do instead, so the agent is not left guessing.

Example 2: a TypeScript app

# Inventory API

TypeScript (strict) HTTP API on Node 22 with Fastify and Prisma. npm, not pnpm.

## Setup and commands
- Install: `npm ci`
- Database: `npm run db:up` (Docker), then `npx prisma migrate dev`
- Dev server: `npm run dev` on http://localhost:4000
- Tests: `npm test`; one file: `npx vitest run src/stock/reserve.test.ts`
- Before finishing: `npm run lint && npm run typecheck && npm test`

## Code style
- ESM only. Named exports; no default exports.
- Validate every request body with the zod schemas in src/schemas/.
- Errors: throw an AppError from src/errors.ts; never send a raw 500.
- After changing prisma/schema.prisma, run `npx prisma generate`.

## Testing
- New behaviour needs a test. A bug fix starts with a failing test.
- Tests hit a real database via `npm run db:up`. Do not mock Prisma.

## Security
- Never log request bodies; they can contain customer addresses.
- Secrets come from environment variables. .env is never committed.

• “npm, not pnpm” is five words that prevent a second lockfile. Say the package manager whenever there is any chance of a wrong guess.
• The Prisma lines cover the step that fails silently: a schema change without prisma generate compiles against stale types.
• Testing says what kind of test, not only that tests exist. “Do not mock Prisma” is a decision the agent cannot infer.
• The security section is short and specific. “Be careful with data” changes nothing; “never log request bodies” is checkable in review.

Example 3: a monorepo root and a nested file

# Acme platform

pnpm workspaces with Turborepo. apps/web (Next.js), apps/api (NestJS),
packages/* shared libraries. Each app and package has its own AGENTS.md.

## Commands (from the root)
- `pnpm install`
- Build one package: `pnpm turbo run build --filter=<package>`
- Test one package: `pnpm --filter <package> test`
- Do not run `pnpm test` at the root during a task; it builds everything.

## Rules for every package
- Shared types live in packages/types. Never copy a type into an app.
- Changes to packages/* need a changeset: `pnpm changeset`.
- Commit messages start with the package name: "api: fix session expiry".

# packages/billing

Money maths and invoice generation, used by apps/api and apps/web.

## Commands
- Tests: `pnpm --filter billing test`
- Property tests are slow: `pnpm --filter billing test:props` before finishing only

## Rules
- Amounts are integer minor units (pence, cents). No floating point anywhere.
- Rounding goes through round.ts. Do not call Math.round on money.
- The public API is src/index.ts. Anything else can change without notice.

• The root file is a map and a set of rules that hold everywhere. It stays short because each package carries its own detail.
• The nested file only adds what is true inside packages/billing. It does not repeat the root’s commands or rules.
• The root line “Each app and package has its own AGENTS.md” tells the agent, and the next person, where to look. Not every tool picks nested files up the same way, which AI context files compared covers.
• Where a nested rule contradicts the root, the convention says the nested one wins, but tools that concatenate files send both. Write rules so that they never contradict: narrow, do not override.

How long should an AGENTS.md be?

The format sets no limit, but the tools do, and the model’s attention does. OpenAI’s AGENTS.md guide for Codex↗ (opens in a new tab) says Codex stops adding instruction files once their combined size reaches 32 KiB by default, counting every file from the repository root down to your working folder. Anything past that is simply not read. GitHub asks for no more than two pages in its own repository-wide file, and the same thinking applies here.

• Aim for a root file you can read in two minutes: roughly 30 to 100 lines for most repositories.
• In a monorepo, keep the root small and push detail into nested files, so an agent working in one package reads only what applies.
• Every line should pass one test: would removing it make an agent get something wrong? If not, cut it.
• When an agent keeps ignoring a rule, the file is usually too long and the rule is buried. Shorten before you add capitals.

What not to put in it

• Things the agent can read from the code: the directory tree, the dependency list, a file-by-file tour.
• General advice: “write clean code”, “follow best practices”, “think carefully”. Nothing checkable, nothing changes.
• Secrets, tokens, connection strings, customer details. The file is committed and read by every agent in every session.
• The current sprint, work in progress, or who is on leave. It is stale within days and misleads the next session.
• Long procedures, such as the release checklist. Link to the document, or use your tool’s skills feature so it loads only when needed.
• Tool-specific syntax. AGENTS.md has no import mechanism of its own, and a line that only one tool understands reads as noise to the rest.
• Hard security boundaries. An instruction is guidance a model tries to follow. Protect branches, secrets and production with permissions and settings, not a sentence.

Which tools read it

• OpenAI Codex reads AGENTS.md from your home folder and from the repository root down to the working folder, as its guide above describes. Setup is in Codex CLI with a task board.
• GitHub Copilot reads it on most agent surfaces. GitHub’s guide to repository custom instructions↗ (opens in a new tab) says the nearest AGENTS.md in the directory tree takes precedence. Surface by surface: does GitHub Copilot support AGENTS.md?
• Claude Code reads it when there is no CLAUDE.md in the working folder or above, according to Anthropic’s memory documentation↗ (opens in a new tab); with a CLAUDE.md, start that file with @AGENTS.md to share one source.
• Cursor supports it at the project root and in subfolders, and its rules documentation↗ (opens in a new tab) says nested files combine with their parents, the more specific instructions taking precedence.
• Gemini CLI and Aider can be pointed at it in their own configuration, as the agents.md FAQ shows. Many other tools read it too; check each one’s documentation before relying on it.

The work goes on a board, not in the file

An AGENTS.md says how to work in the repository. It is the wrong place for what to work on, and the temptation is strong: a “current tasks” section appears, grows, and is wrong by Friday. Keep one short section that points at where the work lives instead. With fenbs connected over MCP, every agent in the list above that speaks MCP can use the same board, and the section can be three lines:

## Work tracking
- Tasks live on the fenbs board, project "acme-platform". Start with fenbs_get_context.
- Read the task you were given with fenbs_get_item; comment on it when you stop,
  with what changed and how it was tested.
- File anything you notice but do not fix as a new task (bug, feature or enhancement).

The board keeps what the file cannot: tasks in To Do, Next Up, In Progress and Completed, each with its problem, its plan and its testing notes, and a record of every change with the name of the person or assistant who made it. It also keeps AI context, short notes about how you work that any connected assistant reads through fenbs_get_context, so a lesson one agent learns reaches the next one whichever tool it is.