How to Structure AGENTS.md for Coding Agents

A good AGENTS.md should not try to teach a coding agent everything about a repository. It should tell the agent where the truth lives, what rules are non-negotiable, how to verify its work, and when to stop. Treat it as a compact routing layer rather than an encyclopedia.

That distinction matters more as coding agents move from short edits to multi-step work. Long instruction files consume context before the agent has even inspected the task, while vague instructions force it to rediscover project conventions repeatedly. The useful middle ground is a small durable contract backed by deeper documentation and executable checks.

This guide presents a repository pattern for that contract, including what belongs in AGENTS.md, what should live elsewhere, how nested instructions should work, and how verification turns prose into an enforceable engineering boundary.

The core rule: map, do not duplicate

The most useful mental model is a table of contents with guardrails.

OpenAI describes an agent-first repository pattern where a relatively short AGENTS.md points into a structured docs/ knowledge base rather than carrying the entire project history itself. That keeps the always-loaded instruction surface compact while letting the agent retrieve deeper context only when a task requires it. The same principle fits the broader problem discussed in Managing Context Window Limitations in AI Developer Tools: context is a budget, so durable information should be discoverable without being injected indiscriminately into every run.

A useful top-level file answers five questions:

1. What is this repository and what is the current architectural boundary?
2. Which commands establish a known-good environment?
3. Which files or directories are authoritative for specific concerns?
4. Which actions are prohibited or require explicit approval?
5. Which checks prove that a change is complete?

Everything else should usually be linked rather than copied.

Separate durable rules from changing project knowledge

Coding-agent context becomes unreliable when information with different lifetimes is mixed together.

Durable rules change rarely: supported runtimes, security boundaries, required validation commands, ownership rules, and where canonical documentation lives. Project knowledge changes more often: active milestones, feature plans, migration notes, known defects, design decisions, and operational runbooks. Task context is shorter-lived still: the current bug, acceptance criteria, failing test, or requested refactor.

Keeping these layers separate produces a cleaner retrieval path:

AGENTS.md
  -> architecture and repository map
  -> docs/design/
  -> docs/runbooks/
  -> docs/decisions/
  -> task-specific files and tests

The top-level file stays stable while deeper documents can evolve independently. An agent can load only the branch of knowledge relevant to its assignment.

This also makes stale instructions easier to detect. If the deployment process changes, there should be one canonical runbook to update instead of several duplicated paragraphs scattered through prompts and repository notes.

Put executable truth next to prose

Instructions such as “keep quality high” or “make sure tests pass” are too ambiguous to be useful automation contracts. Prefer commands and deterministic conditions.

For example:

## Verification

- Install dependencies with `npm ci`.
- Run `npm test` after behavior changes.
- Run `npm run check` before committing.
- Run `npm run build` for production-facing changes.
- Never report success while a required check is failing.

The commands are not merely documentation. They give the agent a reproducible definition of done.

OpenAI’s current Codex guidance similarly emphasizes configuring the development environment, providing repository-specific instructions, and giving agents access to the same validation tools engineers use. In practice, the strongest instruction is often not another paragraph of prompting but a test, schema, linter, or build step that makes an invalid result impossible to mistake for success.

This is the difference between asking an agent to follow a convention and giving it a harness that can verify the convention.

Make authority explicit

Large repositories usually contain several documents that appear to describe the same system. Agents need to know which one wins when they disagree.

A concise authority section can remove that ambiguity:

## Sources of truth

- `ARCHITECTURE.md`: system boundaries and dependency direction.
- `docs/product/`: product behavior and acceptance criteria.
- `docs/runbooks/`: operational procedures.
- `src/content.config.ts`: content schema; never invent enum values.
- Tests and generated schemas override stale prose when they describe executable behavior.

This pattern is especially valuable for autonomous workflows because the agent may encounter old issue descriptions, copied snippets, generated files, or external documentation during research. Without an authority hierarchy, all of those inputs can look equally trustworthy.

The repository itself should tell the agent which evidence is canonical.

Use nested instructions for local exceptions

A single global instruction file becomes bloated when every package has different tooling or conventions. Where the coding-agent environment supports hierarchical AGENTS.md discovery, keep repository-wide rules at the root and put local exceptions close to the code they govern.

For example:

repo/
  AGENTS.md
  apps/
    android/
      AGENTS.md
    web/
      AGENTS.md
  services/
    payments/
      AGENTS.md

The root can define universal security and Git rules. The Android file can define Gradle commands and emulator requirements. The web file can define frontend checks. The payments service can add stricter integration-test or credential boundaries.

This reduces irrelevant context and keeps ownership local. OpenAI’s AGENTS.md documentation describes instruction discovery as a chain, allowing project-specific instructions to refine broader expectations.

The important design constraint is that nested files should specialize the global contract, not silently contradict safety-critical rules.

Design for resumable work, not perfect memory

Long-running coding tasks should assume that conversational context may be compacted, interrupted, or handed to another execution. The repository must therefore carry enough state for work to resume without reconstructing everything from chat history.

That means durable progress belongs in artifacts such as an execution plan, issue, task ledger, test output, or narrowly scoped handoff document. AGENTS.md should point to the mechanism, not contain the current task’s entire timeline.

A useful split is:

AGENTS.md        = how work must be performed
ARCHITECTURE.md  = how the system is shaped
exec plan        = what this task is doing
Git diff         = what has changed
tests            = what has been verified
commit history   = what was completed

This makes the workflow resilient to context loss and supports the Always-On AI Agent Architecture principle of separating durable state from temporary working context.

Isolate parallel agents with worktrees

When multiple agents modify the same checkout, instruction quality cannot prevent filesystem collisions. Isolation has to exist below the prompt layer.

Git worktrees provide multiple working trees attached to the same repository, allowing separate branches or tasks to operate in distinct directories. OpenAI has described using worktree-isolated application instances so agents can reproduce and validate changes independently, and Git’s own documentation defines worktrees as separate working trees linked to one repository.

A practical multi-agent layout might look like:

repo-main/          # integration or human workspace
worktrees/
  task-auth/
  task-cache/
  task-ui/

Each agent gets one writable path set and one validation environment. Review agents can remain read-only. Integration happens through commits or pull requests rather than shared mutable files.

This is a stronger boundary than telling agents to “avoid stepping on each other.”

Keep permissions out of the instruction illusion

AGENTS.md can state that production deployment is forbidden, but prose is not an access-control system. Tool credentials and repository permissions must enforce the same boundary.

If an agent should only prepare a pull request, its token should not have production deployment privileges. If it can read logs but must not mutate infrastructure, expose read-only observability tools. If a destructive action requires approval, put the approval in the execution layer rather than relying on the model to remember a sentence buried in a long file.

A useful rule is:

Instructions describe the policy; tools enforce the capability boundary.

That keeps failures bounded even when reasoning is imperfect.

A compact AGENTS.md template

The exact sections will vary, but a strong baseline is deliberately small:

# Repository agent guide

## Mission
One paragraph describing the repository and current boundary.

## Read first
- `ARCHITECTURE.md`
- relevant docs index
- package-specific `AGENTS.md` when present

## Commands
- install
- smallest relevant test
- type/static check
- production build

## Sources of truth
Map concerns to canonical files.

## Boundaries
List prohibited actions, secret handling, generated-file rules,
and approval requirements.

## Change protocol
Inspect -> edit -> smallest check -> full required checks -> review diff.

## Definition of done
State exactly which checks and evidence are required before success.

If a section starts accumulating implementation history, move that material into deeper documentation and leave a pointer behind.

Failure modes to watch for

The first common failure is the instruction encyclopedia: hundreds of lines of background material are loaded for every task. The result is expensive context with poor retrieval precision.

The second is prompt-only governance. The file says what should happen, but no tests, schemas, permissions, or CI checks enforce it.

The third is duplicated truth. Architecture, commands, and release rules are copied into several documents and eventually disagree.

The fourth is task state in global instructions. Temporary plans accumulate in a file meant to be durable, making every later task inherit irrelevant history.

The fifth is shared writable environments for parallel agents. Even excellent instructions cannot reliably prevent race conditions when several workers edit the same files.

A better repository contract for coding agents

The goal of AGENTS.md is not to make the model remember the repository. It is to make the repository legible enough that the agent can recover the right context and prove its work.

Keep the global contract short. Link to canonical knowledge. Put local rules near local code. Convert important expectations into executable checks. Isolate concurrent workers. Enforce permissions in tools rather than prose. Persist task progress outside conversational memory.

Once those pieces exist, the coding agent no longer depends on one perfect prompt. It operates inside an engineering system that continuously routes it toward the right context and rejects unverifiable work.