Skip to content

AGENTS.md Design

AGENTS.md is the repository-level operating contract for Codex. It should be short enough to load and apply during normal work, but specific enough to prevent Codex from crossing ownership boundaries or skipping verification.

The handbook defines the standard design. Each repository owns its own final AGENTS.md.

Use the product-main AGENTS guidance for product coordination repositories. Use the implementation AGENTS guidance for code-owning repositories.

flowchart TD
  handbook["Handbook standard"] --> template["AGENTS.md template"]
  template --> repo["Repository AGENTS.md"]
  repo --> codex["Codex session"]
  codex --> work["Repository work"]
  work --> verify["Verification"]
  verify --> docs["Docs parity"]

Design Goals

An Anuva AGENTS.md should:

  • identify what the repository owns
  • identify what the repository does not own
  • point Codex to the most important local docs
  • list the commands Codex should prefer for verification
  • explain documentation expectations
  • describe when to stop and ask for handbook-level planning
  • stay stable as implementation details evolve
Section Purpose
Repository Purpose One concise explanation of what the repository is for.
Ownership Boundaries What the repository owns and what must be changed elsewhere.
Read First The local docs Codex should inspect before major work.
Common Commands Install, development, test, lint, typecheck, build, or preview commands.
Working Rules Repository-specific rules that should affect every change.
Documentation Rules Where docs live and when they must be updated.
Change Workflow Link to local ChangeWorkflow.md or the handbook workflow.
Verification Expected checks by change type.
Escalation When to return to the handbook for cross-repository planning.

Implementation Repository Preconditions

For implementation repositories, create or refresh AGENTS.md only after these sources exist:

  • docs/bootstrap/BootstrapContext.md
  • docs/process/ChangeWorkflow.md
  • docs/core/
  • docs/state/
  • docs/process/
  • docs/changes/

Implementation repository AGENTS.md should reference those docs instead of inventing repository purpose, workflow, or architecture during AGENTS creation.

What To Keep Out

Keep AGENTS.md free of material that changes often or belongs elsewhere:

  • long architecture explanations
  • full implementation maps
  • product roadmaps
  • detailed examples
  • large prompt libraries
  • lengthy workflow manuals
  • historical change logs

Those belong in repository docs, examples, templates, prompts, or skills.

Size Guidance

Aim for a practical operating file, not an encyclopedia.

Size Signal
Under 75 lines Good for small or early repositories.
75-175 lines Good for mature repositories with real verification and docs rules.
Over 175 lines Review for content that should move into docs or skills.

Escalation Rules

Codex should pause repository-local work and return to handbook planning when:

  • the request changes repository boundaries
  • the change affects multiple repositories
  • the capability owner is unclear
  • shared contracts or standards need to change
  • the repository's local workflow conflicts with handbook guidance
  • a new skill, template, or registry entry may be needed

Relationship To Other Files

flowchart LR
  agents["AGENTS.md"] --> behavior["Repository behavior rules"]
  workflow["ChangeWorkflow.md"] --> process["How work moves"]
  docs["Local docs"] --> knowledge["Current implementation knowledge"]
  skills["Skills"] --> procedure["Reusable task procedure"]
  handbook["Handbook"] --> shared["Shared architecture and registries"]

Maintenance Rule

Update AGENTS.md when repository behavior rules change. Do not update it merely because implementation details changed; update the local docs instead.