AGENTS.md, explained for teams that actually ship

Developer Arpit Uppal has published a practical guide to AGENTS.md, a markdown file that AI coding agents read at session start to understand a repository's commands, conventions, and architecture. Uppal argues that AGENTS.md is the cheapest fix for context problems that cause agents to break builds, and provides a free starter template in the agentsmd-kit repository, with an optional paid Pro Pack containing stack-specific templates and a 40-point audit checklist.

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. Agents don't have intuition. They have context windows. Without instruction, an agent in a fresh repo will: uv run pytest -m "not e2e" , not pytest 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. After writing these files for a lot of different repos, I've landed on a structure that survives contact with real codebases: src/domain/ , DB access only through src/db/repo.py ." migrate on prod. localhost:8080 is the only dev host. The data/ dir is gitignored and regenerated by make seed ."Keep it under 300 lines. If it's longer, agents start ignoring the end of it. The most common mistake is treating AGENTS.md like documentation: This is the starter template I keep in agentsmd-kit https://github.com/arpituppal2/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. 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 https://www.paypal.me/ArpitUppal2/29 $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 mailto:arpituppal2@gmail.com . 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.