Agents Overview

AGENTS.md files should tell Codex how to behave inside a repository. They should be practical, bounded, and stable.

flowchart TD
  handbook["Handbook guidance"] --> template["AGENTS template"]
  template --> repoAgents["Repository AGENTS.md"]
  repoAgents --> codex["Codex behavior in repo"]
  codex --> changes["Repository changes"]
  changes --> docs["Docs parity"]

What Belongs In AGENTS.md

• Repository purpose.
• Ownership boundaries.
• Important commands.
• Verification expectations.
• Documentation expectations.
• Links to authoritative docs.
• Done criteria.

What Should Stay Out

• Long architecture explanations.
• Frequently changing implementation maps.
• Full workflow manuals.
• Large prompt libraries.

Those belong in docs, templates, prompts, or future skills.

Handbook Rule

The handbook should define the standard pattern. Each repository should keep its own AGENTS.md small enough to be useful during normal Codex work.