Enji GuardAGENTS.md best practices: what it is and how to write one
AGENTS.md is the instructions file coding agents read before they touch your repo. This is a practical guide to what belongs in it, how to structure it, and how to keep it true as the code changes.
1 repo · setup in about 5 minutes · no card, no commitment
01
What is AGENTS.md?
AGENTS.md is a plain-Markdown file at the root of your repository that tells coding agents how to work in it: how to build and test, what conventions to follow, what to avoid, and where the important boundaries are. Cursor, Claude Code, Codex, and similar tools read it (alongside CLAUDE.md and .cursorrules) to act with context instead of guessing.
02
What to put in it
A good AGENTS.md is short, specific, and verifiable:
- How to install, build, run, and test the project
- Project conventions: structure, naming, and patterns to match
- What NOT to do (files to leave alone, commands to avoid)
- Security and review rules: no secrets, no auto-merge, human review required
- Where domain logic lives and how the main pieces fit together
03
Best practices that keep it useful
Write it like instructions a new engineer could follow on day one. Keep it concise so it does not waste the agent's context budget; prefer concrete commands over vague guidance; put narrow rules close to the code they govern (a per-folder AGENTS.md) instead of one giant root file; and link, don't duplicate.
04
Common mistakes
The biggest failure is drift: an AGENTS.md written on day one quietly stops matching the codebase by month two, and the agent keeps trusting rules that are no longer true. Other traps are bloat (so much context the agent never reaches the task), rules that contradict CLAUDE.md or .cursorrules, and secrets or sensitive paths leaked into the file.
05
Keep AGENTS.md honest with Guard
Once your file is solid, the hard part is keeping it true. Guard audits AGENTS.md, CLAUDE.md, and Cursor rules against the real repo on a schedule, flags where they have drifted, and can open a pull request that updates them to match the code.
Quick questions
Is AGENTS.md the same as CLAUDE.md or .cursorrules?
They play the same role, instructions for coding agents, but for different tools. AGENTS.md is a tool-agnostic convention; CLAUDE.md targets Claude Code and .cursorrules targets Cursor. Many repos keep more than one, which is exactly why they can drift out of sync.
Where should AGENTS.md live?
At the repository root for project-wide rules, with optional per-directory files for rules that only apply to a subsystem. Keeping narrow rules close to the code they govern keeps each one short and relevant.
How do I stop it from going stale?
Treat it like code: review it when the project changes, and audit it on a schedule. Guard can do the second part automatically, flagging drift between your rules and the actual repo.
Keep your AGENTS.md true to the code.
Connect a repo and Guard audits your agent rules against the real codebase. No card.