Write an effective AGENTS.md

How to give Codex durable repository guidance without filling its context with vague or stale rules.

AGENTS.md is a repository instruction file for coding agents. Codex loads it automatically, so it is the right place for guidance that should apply across many tasks rather than one prompt.

Include operational facts

A useful file answers the questions a capable new contributor would ask:

What does this repository contain?
Which directories matter for common work?
How do I build, test, lint, and run it?
What conventions are not obvious from the code?
Which files or systems must not be changed?
What must be verified before work is considered complete?

Prefer commands that can be copied exactly. If setup differs by platform or package, state the boundary clearly.

Use the directory hierarchy

Place shared rules at the repository root. Add another AGENTS.md inside a subdirectory when that area has different commands or constraints. Guidance closer to the current working directory overrides broader guidance.

This works well in monorepos: the root file explains the system and global rules, while each service or package documents its own verification workflow.

Keep architecture elsewhere

Do not turn AGENTS.md into a complete architecture book. Link to stable design documents and keep the agent file focused on how to work. Long background text consumes context on every task and makes practical rules harder to find.

A good pattern is:

Architecture: see ARCHITECTURE.md.
Before changing public interfaces, read docs/api-contract.md.

Write enforceable constraints

“Write clean code” is too vague. “Run npm test and npm run lint; do not add runtime dependencies without approval” is checkable.

Separate normal conventions from hard prohibitions. Explain a non-obvious rule in one sentence so the agent can apply it correctly instead of working around it.

Keep it current

Stale commands are worse than missing commands. Review AGENTS.md when build tooling, directory ownership, or release checks change. Remove duplicated rules and resolve contradictions between nested files.

The CLI command /init can scaffold a starting file, but the generated result is only a draft. Replace generic sections with the repository’s real workflow.

Learn from actual mistakes

Add a rule after repeated friction, not every hypothetical risk. If Codex keeps missing a convention, ask what instruction or automated check would have prevented it. Prefer a test or lint rule when the requirement can be enforced by software; reserve AGENTS.md for context and judgement that tools cannot encode.