AGENTS.md Specification

AGENTS.md is an emerging industry standard markdown file placed at the root of a project workspace to orient AI coding agents (such as Hermes, Claude Code, Cursor, and Codex) as soon as they inspect a repo.

The Core Philosophy: “Never Run /init”

Auto-generated agent initialization files typically produce hundreds of lines of generic prose describing basic language syntax and obvious git commands. High-signal AGENTS.md files are strictly hand-crafted, concise, and focused exclusively on non-obvious project reality.

Essential Sections of AGENTS.md

1. Layout & Entry Points: The high-level file tree and where persistent vs ephemeral files live.
2. Toolchain & Non-Obvious Commands: The exact build, test, and typecheck commands (e.g. uv run ... or pnpm test), highlighting environment quirks like PEP 668 or package manager constraints.
3. Architecture Seams & Decisions: References to CONTEXT.md and ADR records.
4. Pitfalls & Hard Guardrails: Things the agent must NEVER do (e.g. “Do not push directly to main”, “Do not mock database calls in unit tests”).

AGENTS.md vs System Prompts

AGENTS.md belongs in the project filesystem, not baked into a static system prompt. This allows agent behaviour to evolve dynamically with repository commits and branch checkouts.

Related

context engineering, prompt bloat, progressive disclosure, ai coding taxonomy.