AGENTS.md Best Practices for Coding Agents

The best AGENTS.md files are short operating briefs for coding agents: exact commands, repo shape, architectural constraints, security gotchas, and proof expected before work is done. They are not a second README, a style handbook, or a policy enforcement layer.

This is for engineering leaders, staff engineers, and platform teams starting to run agents across real repositories. The first trial usually feels good. Then people add test commands, security warnings, frontend rules, migration notes, and personal preferences. Three months later the agent is loading a stale wall of instructions copied across AGENTS.md, CLAUDE.md, Cursor rules, and local prompts.

That is how repo instructions stop helping.

What AGENTS.md is for

AGENTS.md is best treated as a README for agents. It gives coding agents the compact context a competent new engineer would want before touching the repo.

• What kind of project is this?
• How do I install dependencies?
• How do I run one test, all tests, linting, type checks, and the build?
• Which files are generated or sensitive?
• Which architecture boundaries should not be crossed?
• What evidence should be reported before the change is considered handled?

The format is intentionally plain Markdown with no required schema. That flexibility is useful, but it means ownership matters. If nobody maintains the file, it will drift.

AGENTS.md best practices: what belongs in it

A useful root AGENTS.md usually includes project overview, setup commands, test commands, architecture constraints, security notes, git and PR workflow, conventions, external service notes, environment variables, domain vocabulary, and verification expectations.

Concrete instructions beat general advice. This helps an agent:

Run one backend test with:
pnpm test -- packages/api/src/orders/create-order.test.ts

Before opening a PR, run:
pnpm lint
pnpm typecheck
pnpm test

Do not edit packages/api/generated. Regenerate it with:
pnpm generate:api

This sounds responsible but is too vague:

Make sure code is high quality.
Follow normal conventions.
Be careful with generated files.

The first version gives the agent something it can execute and verify. The second asks the model to guess what your team means.

What to leave out

Do not put everything an agent might ever need into always-loaded repo instructions. Leave out full style guides already enforced by tools, generated file maps that go stale, one-off ticket context, long explanations of common engineering concepts, personal preferences, and duplicated guidance from other instruction files.

The reason is practical context management. Codex has a default combined project-doc limit of 32 KiB. Claude docs recommend keeping each CLAUDE.md under 200 lines. Cursor recommends splitting large rules and avoiding full style guides or rare edge cases. The common pattern is clear: short, concrete, and scoped beats long and stale.

How to handle monorepos

For monorepos, a single root file becomes either too vague or too large. Use layered instructions.

• Root AGENTS.md: global norms, shared commands, security boundaries, and review expectations.
• Package or service AGENTS.md: local commands, owners, generated files, sensitive paths, and exceptions.

Tool behavior differs. The AGENTS.md project says closest files take precedence. Cursor combines nested files with parents and lets more specific instructions win. Codex concatenates project files from root to the current directory, with later and closer guidance overriding earlier text.

Write the precedence rule for humans too:

When instructions conflict, the AGENTS.md closest to the edited file overrides the root AGENTS.md.

AGENTS.md, CLAUDE.md, and Cursor rules

AGENTS.md should be the portable baseline. Codex has first-class AGENTS.md support, including global and project scopes, AGENTS.override.md, fallback filenames, root-to-current discovery, and a configurable byte limit.

Claude Code reads CLAUDE.md, not AGENTS.md. The clean pattern is a thin CLAUDE.md that imports @AGENTS.md plus Claude-only workflow rules. The brief notes that import is preferable on Windows when symlinks require Administrator privileges or Developer Mode.

Cursor supports AGENTS.md as plain Markdown, while project rules can use metadata such as alwaysApply, description, and globs. Use those when instructions are path-specific or relevance-specific.

The trap is duplication. If the same test command lives in three places, one copy will eventually lie.

Security guidance is not enforcement

AGENTS.md should warn agents about high-cost mistakes, but it should not be your only control. Repo instructions are behavioral context, not hard policy.

Never print production secrets in logs.
Never modify terraform/prod without an explicit task.
Do not bypass payment authorization checks in tests.

Those lines are useful. They still need enforcement through hooks, permissions, CI, branch protection, deny lists, secret scanning, and code review. The brief cites an empirical study of 253 CLAUDE.md files where Build and Run appeared in 77.1 percent, Testing in 60.5 percent, and Security in only 8.7 percent. The study is about CLAUDE.md, so the comparison is not perfect, but the warning is obvious: teams document how to run code before they document what must not go wrong.

Maintenance checklist

• Keep the root overview to a few sentences.
• Use exact install, run, lint, typecheck, build, full-test, and single-test commands.
• Name generated files and sensitive directories directly.
• Include architecture constraints that reviewers can check.
• State verification evidence: tests, screenshots, changed files, risks, or rollback notes.
• Use nested AGENTS.md files where local context matters.
• Keep tool-specific files thin and avoid copied bodies.
• Move hard controls to hooks, CI, permissions, branch protection, or scanners.
• Prune stale instructions on a schedule.

The goal is not to make agents obedient by writing longer instructions. The goal is to give them the compact operational context a strong engineer would want before editing a real repository.