AGENTS.md: The Small Rule File That Sets Your AI Agent's Boundaries
Because Codex and Claude Code load AGENTS.md at session start, a well-maintained rule file prevents agents from re-deriving project conventions every time and avoids unchecked commands or false completion claims. For teams using AI coding tools, a single canonical ruleset reduces wasted sessions and keeps agent behavior consistent across projects.
AI coding agents read AGENTS.md at the start of every session. The file holds long-term conventions: which commands to run, when to ask for permission, and how to verify work. Most developers still scatter those rules across one-off prompts, so agents drift between sessions. The article lays out eight things a complete rule set should cover, from declaring the tech stack to refusing to report unrun checks as passed.
Two ready-to-use templates accompany the advice. A project-level AGENTS.md goes in the root directory and asks for real commands, reference implementations, and protected files; merge it incrementally if one exists. A global template for Codex sets defaults for every project, covering command discovery, external code reuse, and a rule that checks which weren't run must be reported as unrun. The global file also keeps scope tight by forbidding unauthorized dependency changes and private data leaks.
The author suggests keeping project rules around 50–100 lines and global rules 30–60 lines, with longer flows in separate documents. Claude Code supports the same file: adding @AGENTS.md inside an existing CLAUDE.md imports it, though global settings live in ~/.claude/CLAUDE.md. After editing, a /context check and a small test confirm the agent loaded the rules.
The insistence on pulling real commands from the current project addresses a common failure where agents guess command syntax from memory, such as copying pnpm commands, instead of reading the lock file or package.json.
The rule that unrun checks cannot be reported as passed targets a frequent gap where agents claim success without actual verification, a direct consequence of the template's verification section.
The recommended file sizes, 50–100 lines for project and 30–60 for global, reflect a real tradeoff: enough guidance to constrain behavior without bloating the context that agents process every session.