AGENTS.md, explained for teams that actually ship

By the end of 2025, AI coding agents stopped being a toy. Claude Code, Codex, Cursor, Copilot and opencode are now doing real work in real repos — and teams are discovering that the difference between an agent that ships clean PRs and an agent that breaks your build is one file: AGENTS.md. If you haven't seen it yet: AGENTS.md is a markdown file, committed to your repo root, that tells AI agents how your repo actually works. Commands, conventions, architecture, gotchas. The agent reads it at session start — before it touches a single file. This post is a practical, opinionated guide: what to put in the file, what to leave out, and the exact template I use in production repos. Why AGENTS.md exists Agents don't have intuition. They have context windows. Without instruction, an agent in a fresh repo will: Guess your test command (it's probably uv run pytest -m "not e2e", not pytest) Follow some generic style that matches nothing in your codebase "Fix" a bug by deleting the code that was loading it Commit generated files, or run commands that mutate your local DB Every one of those is a context problem, not a capability problem. AGENTS.md is the cheapest fix: one file, read at the start of every session. Anthropic's Claude Code, OpenAI's Codex, Cursor, and GitHub Copilot all read it natively now. Write it once, and every agent that enters your repo starts with your team's actual knowledge. The structure that works After writing these files for a lot of different repos, I've landed on a structure that survives contact with real codebases: One-line purpose. What this repo is, in a sentence. Agents search the file; make the first line say what they need to know. Commands — the exact five. Setup, test (with the exact filter), lint, typecheck, build. Write the actual commands, not "run tests". This section alone prevents most damage. Workflow — what "done" means. "Every change must add or update a test. Run the full suite before pushing. Never force-push to main." This is your contract with the agent. Architecture map. Where the important things live, in 5-10 bullets. Not a full README — a map. "Business logic in src/domain/, DB access only through src/db/repo.py." Style rules. The two or three rules that matter to you, not a linter's worth of rules. "New code must match the surrounding file's style. No new dependencies without justification in the PR." Gotchas and don'ts. "Never run migrate on prod. localhost:8080 is the only dev host. The data/ dir is gitignored and regenerated by make seed." The kill list. What the agent is not allowed to do. Deleting code, refactoring "as a bonus", editing lockfiles by hand — whatever your team has been burned by. Keep it under 300 lines. If it's longer, agents start ignoring the end of it. What NOT to put in it The most common mistake is treating AGENTS.md like documentation: No long tutorials or architecture essays. Agents can read code; they need pointers, not explanations. No duplicate of README content. The README is for humans, AGENTS.md is for agents. Different jobs. No absolute rules you don't enforce. "Always write perfect code" is noise. An agent can't act on it, and it teaches the agent that your file is decoration. No secrets or internal URLs. This file gets committed. If a repo is ever public or shared, everything in AGENTS.md is public. The template This is the starter template I keep in agentsmd-kit, free and MIT-licensed: # AGENTS.md ## Purpose [One sentence: what this repo is and does] ## Commands - Setup: [...] - Test: [...] (include exact filter flags) - Lint: [...] - Typecheck: [...] - Build: [...] ## Workflow - [...] - [...] ## Architecture - [...] - [...] - [...] ## Style - [...] - [...] ## Gotchas - [...] - [...] ## Don'ts - [...] - [...] Copy it, fill in the brackets with your repo's actual answers, commit it. If you don't know an answer, find out — a half-true AGENTS.md is worse than none, because the agent will trust it. The 40-point hardening checklist A good AGENTS.md is the beginning, not the end. The repos where agents shine are also agent-ready: hermetic test commands, CI gates, fast feedback loops, scoped permissions. If you want the full checklist — the 40-point audit I run on repos before letting agents work in them — I put it in the Pro Pack ($29, one-time, instant delivery): 18 stack-specific templates (Python, TypeScript, Rust, Go, iOS, MCP servers, ML, monorepos…), CLAUDE.md and Cursor-rules companions, the checklist, and prompt templates for common agent tasks. Buy it once, use it in every repo. Or if you'd rather not maintain it yourself, I write custom AGENTS.md + CLAUDE.md setups for teams — hire me directly. The bottom line AGENTS.md is the cheapest productivity win available to a team using AI agents in 2026. It's one file. It takes an afternoon to write properly. And it converts your agents from "fast typists with good ideas" into team members that follow your conventions. Start with the free template, fill it honestly, and watch your agent PRs get less destructive within a week. I'm Arpit — I build AGENTS.md and agent-gate setups for teams. Get the free kit or grab the Pro Pack.