AGENTS.md example: sections that belong (and ones that don’t)

People searching for an “AGENTS.md example” usually already have a file — it just grew into a dump of README, architecture essays, and one-off workflows. Cursor treats root AGENTS.md as plain project instructions; Codex reads nested AGENTS.md chains and truncates when the combined project docs hit its default size cap (32 KiB). The useful pattern is a short always-on map, not a second wiki.

What belongs in AGENTS.md

• Project identity — one short paragraph: what the repo is and who it serves.
• Exact build / test / lint commands — the ones agents keep guessing wrong.
• Non-obvious conventions — “use uv, not pip”; “tests live next to the file.”
• Hard constraints — short always/never lines that differ from the model’s defaults.
• Pointers — where to read deeper docs or skills when a task needs them.

What usually does not belong

• Full directory trees and tech-stack inventories the agent can discover by reading the repo.
• Long release / migration / accessibility checklists (move those to skills or docs loaded on demand).
• Entire style guides (prefer a linter; Cursor’s rules docs explicitly warn against pasting them).
• Duplicate copies of the same rule that also live in CLAUDE.md or .cursor/rules.

Short example

# Project instructions

## What this is
Clogmeter-style SPA: Vite + TypeScript client that weighs agent instruction files in-browser.

## Commands
- Install: npm ci
- Dev: npm run dev
- Build: npm run build
- Preview: npm run preview

## Conventions
- TypeScript for all new files
- Prefer small focused modules over god-files
- Do not invent Stripe prices or offer discounts

## Never
- Never commit secrets or .env values
- Never change live Payment Link URLs without an explicit owner request

## When you need more
- Release checklist → skills/release/SKILL.md (load only for release tasks)
- API notes → docs/api.md (read when editing api/)

Cursor’s docs show the same idea: plain markdown instructions, concrete bullets, start small and add rules only when the agent repeats a mistake. Prefer referencing files over pasting their contents so the root file stays short and does not go stale.

After you write it

Weigh the file (and any sibling CLAUDE.md / rules) so you know how many tokens load every turn, then trim duplicates. For size ceilings across tools, see How long should CLAUDE.md / AGENTS.md be?.