How to Write AGENTS.md Without Creating an Instruction Dump

What AGENTS.md Is For

AGENTS.md gives Codex durable instructions about how to work in a repository. OpenAI describes it as a place for coding conventions, business logic, known quirks, dependencies, test commands, and repository practices that cannot be inferred reliably from source code alone.

The file should answer high-value questions:

• What is this product and what must never be misrepresented?
• What runtime, package manager, and framework rules apply?
• Which architectural boundaries should changes respect?
• Which commands prove a change is healthy?
• Which security, analytics, or data rules are non-negotiable?
• When must documentation be updated with behavior?

It should not try to teach every subsystem in one place.

Keep the Root File Small

OpenAI's harness engineering guidance warns against a single giant AGENTS.md. A monolithic file consumes context, makes every rule appear equally important, becomes difficult to verify, and tends to rot.

Use the root file as a navigation layer:

AGENTS.md
docs/
  architecture.md
  billing.md
  analytics.md
  release-runbook.md
src/
  billing/AGENTS.md
  analytics/AGENTS.md

The root file should contain company-wide and repository-wide rules. A deeper AGENTS.md can describe a sensitive subsystem such as billing. Detailed architecture belongs in maintained docs linked from the root.

Make Rules Verifiable

Weak instruction:

Make sure analytics is safe.

Strong instruction:

Never send names, emails, phone numbers, addresses, message bodies, or raw search terms to analytics. Run the analytics sanitization unit tests whenever event payloads change.

The second rule names the boundary and the evidence. Prefer instructions that can be checked through code, tests, schema validation, or a repeatable manual path.

Useful categories include:

• Commands: exact lint, typecheck, test, and build commands
• Completion: what evidence is required before handoff
• Data: fields that may or may not leave the system
• Commerce: which server-side event grants access
• UX: required loading, empty, partial, error, and gated states
• Deployment: branch, environment, and verification rules

Prevent Context Rot

Treat AGENTS.md as code-adjacent product memory. Update it in the same change whenever pricing, data flows, entitlements, providers, launch assumptions, or verification commands change.

Review the file periodically:

1. Remove rules that are now enforced automatically.
2. Link to the source of truth instead of duplicating it.
3. Separate current behavior from future direction.
4. Add ownership for operational runbooks.
5. Test that every documented command still works in a clean environment.

Good context compounds because future changes start from correct assumptions. Stale context compounds in the opposite direction.

Official references

• Introducing Codex
• How OpenAI uses Codex
• Harness engineering with Codex