AGENTS.md is a plain Markdown convention for giving coding agents durable project context. Its value is not the filename alone. The value is placing useful instructions at the right scope and backing them with executable checks.
The practical field guide
Start with AGENTS.md for website development. It covers the root file, nested instructions, design-system constraints, content rules, validation commands, security boundaries, and the difference between guidance and enforcement.
The agent directory explains how individual tools consume repository context. That distinction matters: Codex and several other agents read AGENTS.md directly, while Claude Code uses CLAUDE.md and can import a shared file.
The system needs four layers: architecture boundaries, design and content rules, exact verification commands, and approval requirements for deployments, billing, secrets, or destructive Git operations. The detailed guide below shows how to keep those layers navigable rather than turning one file into a permanent wall of instructions.
Keep the file navigable
One enormous instruction file creates its own failure mode. Put universal rules at the root, add narrower files near specialized code, and route detailed procedures into focused documentation or skills. The technical guides show how that hierarchy supports real Astro work.