AGENTS MD File: A Repository Rules Template

An AGENTS MD file, conventionally named AGENTS.md, gives a coding agent repository-specific instructions it should read before working. Put the broad file at the project root. Add a narrower AGENTS.md or AGENTS.override.md inside a subdirectory when that part of the repository needs different commands or boundaries. Include setup, exact verification commands, file ownership, deployment rules, and actions that require a stop.

Do not use it as a substitute for tests, permissions, or sandboxing. It is guidance loaded into the agent's context. The practical template below makes that guidance specific enough to verify.

What An AGENTS.md File Is For

Source code explains what the system does now. It rarely explains every decision an agent needs while changing it.

An agent may not be able to infer that:

• each package has an independent lockfile;
• a generated file must never be hand-edited;
• one service uses integration tests while another uses a focused unit command;
• deployment manifests are the source of truth;
• an apparently convenient live configuration command creates drift;
• a folder naming convention matters to scripts outside the package;
• an external action needs explicit human approval.

Those constraints belong in repository guidance because they shape how work should happen, not merely how the current code happens to look.

OpenAI's current AGENTS.md documentation describes a layered instruction chain. Codex reads global guidance first, then walks from the project root toward the current working directory. Guidance closer to the working directory appears later and can override broader instructions.

That makes the file useful for a monorepo, but it also creates a responsibility. A nested rule should be narrower and intentional. If the root says "run the whole suite" and a package says "run no tests," the agent has received a conflict, not a clever optimization.

Where The File Should Go

Start with one file at the repository root:

your-project/
  AGENTS.md
  package.json
  src/
  tests/

That root file covers the repository unless a deeper instruction file refines it. In a repository with independent services, the tree might look like this:

your-project/
  AGENTS.md
  services/
    api/
      AGENTS.md
      package.json
    billing/
      AGENTS.override.md
      pyproject.toml
  deployment/
    AGENTS.md
    k8s/

When Codex works from services/api, it receives the root guidance and the API guidance. When it works from deployment, it receives the root guidance and deployment guidance instead. The billing override is not a universal policy for sibling folders.

Codex also supports global guidance under its home configuration directory. Keep personal working preferences there. Keep project facts in the repository so collaborators and automation receive the same contract.

A Root AGENTS.md Template

This template is short enough to maintain and detailed enough to change agent behavior:

# AGENTS.md

## Repository Purpose

This repository contains independent web services. Each service owns its
dependencies, lockfile, tests, and deployment configuration.

## Before Editing

- Read the nearest package manifest and existing tests.
- Check `git status --short` and preserve unrelated changes.
- Search for a local pattern before adding a new abstraction.
- Stop if the requested behavior conflicts with documented product rules.

## Boundaries

- Do not add root-level dependencies.
- Do not edit generated output or vendored code.
- Do not read secret files unless the task explicitly requires them.
- Ask before adding a production dependency or changing a public API.
- Never commit, push, deploy, send messages, or call paid services unless the
  task explicitly authorizes that action.

## Verification

- Run the focused tests for the changed package during implementation.
- Run that package's full test command before reporting completion.
- Run the production build for changes that affect rendering or bundling.
- Report exact commands, exit status, and checks that could not run.

## Naming

- Use kebab-case for folders.
- Follow the naming already used by the package for source files.

## Git

- Keep changes scoped to the requested behavior.
- Do not discard or rewrite changes you did not create.
- Use non-interactive commands where possible.

Change every line to match the real repository. A copied instruction that names a nonexistent command is worse than no command because it gives the agent false confidence.

I prefer executable facts over adjectives. "Write high-quality tests" is an aspiration. "Run npm test from services/api and preserve the authorization assertion" tells the agent what proof the project accepts.

Add A Nested Override Only When Needed

Suppose the billing service uses Python while the rest of the repository uses Node. A nested file can replace the relevant commands without repeating the entire root document:

# Billing Service Override

## Scope

These rules apply to files under `services/billing/`.

## Setup

- Use the existing virtual environment and locked dependencies.
- Do not add or update packages unless the task explicitly requires it.

## Verification

- Run `pytest tests/unit/<focused-file>.py` while iterating.
- Run `pytest` before reporting the service complete.
- Run the migration check when a model or schema changes.

## High-Risk Changes

- Treat amounts as integer minor units at persistence boundaries.
- Keep idempotency tests for repeated provider events.
- Stop before contacting a payment provider or changing live data.

The root boundaries still apply unless this file clearly and intentionally overrides one. I would not paste all root guidance again. Duplication lets the two copies drift, and then nobody knows which sentence represents the current rule.

Encode Deployment Anti-Drift Rules

Deployment is where vague repository guidance gets expensive. A command can repair production for ten minutes while leaving no durable record, then the next reconciliation or deploy removes it.

If tracked manifests are authoritative, say so directly:

## Deployment State

- Files under `deployment/k8s/` are the source of truth for persistent cluster
  objects and environment wiring.
- Edit and commit the manifest before applying a persistent state change.
- Do not use live-only edits such as `kubectl edit` or `kubectl set env`.
- Secret values do not belong in Git. Commit the reference from the workload;
  populate the secret value through the approved environment process.
- After applying a manifest, compare the live object with the committed source.
- A successful rollout does not prove the application behavior. Run the named
  health and smoke checks too.

That block gives the agent a system boundary, an approved sequence, and a verification obligation. It also distinguishes secret values from secret references, which are often confused in hurried deployment work.

Repository instructions do not technically prevent an operator from running a banned command. Back them with permissions, review, CI, policy, and restricted credentials where the consequence matters. OpenAI's Codex safety guidance treats sandbox boundaries, approvals, network policy, and logs as separate controls for good reason.

Test Which Instructions Win

Do not assume the hierarchy works because the filenames look right. Test it from the directories where agents actually start.

Create a harmless, deliberate distinction:

# Root AGENTS.md
- Use `npm test` for JavaScript packages unless a nested file says otherwise.

# services/api/AGENTS.md
- In this package, run `npm run test:api` instead of the root JavaScript test.

Start a Codex session whose read-only boundary is enforced by the sandbox, with approval escalation disabled:

codex --sandbox read-only --ask-for-approval never exec \
  "Summarize the instructions that apply in this working directory. Name the verification command, edit boundaries, and stop conditions. Do not run commands."

The flags create the boundary. The sentence inside the prompt explains the task; it is not the access control.

Ask the same questions in the session output:

Summarize the instructions that apply in this working directory.
Name the verification command, edit boundaries, and stop conditions.
Do not run commands.

Repeat from services/api. The root session should report the root command. The API session should report the narrower command and retain compatible root boundaries.

Use a small matrix to record the result:

This is a precedence test, not a code test. Rerun it after moving instruction files, changing the working directory used by automation, or adding a fallback instruction filename.

What To Put In The File

For most projects, the useful categories are stable:

1. Repository purpose and architecture boundaries.
2. Setup commands that actually work from a named directory.
3. Focused and full verification commands.
4. File ownership, generated paths, and directories to avoid.
5. Naming and style rules that tools do not already enforce.
6. Security, privacy, external-action, and destructive-action stops.
7. Deployment source of truth and post-deploy proof.
8. Git expectations for dirty worktrees, commits, and branches.

Do not put credentials, private business details, or long onboarding essays in it. Link to a durable internal document when the agent needs deeper context. Keep the action-changing rules near the top.

The best file answers the questions an agent would otherwise guess. It does not try to teach the entire product history.

Common AGENTS.md Failures

Commands Without A Working Directory

npm test may be correct in one package and fail at the root. Name where the command runs.

Rules That Cannot Be Verified

"Be careful" has no observable pass condition. Name the risky paths, required test, and stop point.

Nested Files That Repeat Everything

Copies drift. Let the root own shared policy and the nested file own the difference.

Guidance That Pretends To Be Enforcement

An instruction can be ignored or misunderstood. Use technical restrictions for secrets, destructive access, production credentials, and protected branches.

Stale Architecture Facts

Agents follow explicit text even when the repository evolved. Review the file alongside build, test, dependency, and deployment changes.

Too Much Context

A giant file buries the one command that matters. Put concise operating rules in AGENTS.md and link to deeper design records.

How I Would Audit A Real File

I would review AGENTS.md when the repository's operating contract changes, not on an arbitrary calendar reminder alone. A new package manager, renamed test script, moved deployment folder, split service, generated client, or new approval boundary can make yesterday's precise instruction actively wrong. The code may still build while every agent session starts from a stale map.

My first audit question is simple. Can I execute every command from the directory the file implies? I would run setup and verification in a clean environment where practical, because a command that works only with an old global package or forgotten shell variable is not a repository instruction. It is a local accident.

Then I would trace every boundary to an enforcement layer:

The file does not need to describe every enforcement mechanism, but I want to know that consequential rules exist somewhere beyond prose. If "never commit secrets" is the only control protecting a production credential, the repository has a security gap that a better paragraph cannot close.

I would also remove instructions the agent can discover reliably and cheaply. Listing every source folder turns the file into a second, stale directory tree. Naming the unusual boundary is more useful, such as explaining that migrations live with deployment rather than the service, or that a generated API client must be rebuilt through one command. I want the file to spend context on surprises.

Finally, I would rerun the precedence check from every entry point used in practice. A developer may launch from the root, a task runner from one package, and a review job from a worktree subdirectory. If they receive different instruction chains, that difference should be intentional and documented. I would save the summaries beside the change review so a later maintainer can see what was actually loaded.

Separate Facts, Preferences, And Stops

One way to make the file easier to challenge is to label the kind of instruction being given.

A fact describes the repository. "The API package owns its lockfile" can be checked in the tree. A preference guides implementation when several valid choices exist. "Prefer the existing request helper" still allows a task to justify another design. A stop condition prevents the agent from crossing into a materially different action. "Stop before applying the migration to production" should not be softened into a suggestion.

I would not mix those categories in one long bullet list. When a preference sounds like an absolute ban, agents may avoid a justified change. When a stop condition sounds optional, an agent may cross an external boundary while trying to be helpful.

Write the exception path too. "Do not add dependencies" is clearer when followed by "unless the task explicitly approves one after reviewing the existing options." The exception does not weaken the rule. It tells the agent who can change the decision and what evidence is needed.

This distinction also improves review. If an agent violates a repository fact, its context or reasoning was wrong. If it chooses against a preference, the diff may contain a valid tradeoff. If it crosses a stop condition, the process failed even when the code itself is correct.

Does AGENTS.md Work With Every Coding Agent?

Support differs by product and version. The format is associated with several coding tools, but this article's discovery and precedence behavior is specifically grounded in current Codex documentation. Check the other agent's official guidance before assuming it reads the same filenames or applies the same hierarchy.

For a product-level workflow comparison, use the Codex vs Claude Code test. The broader AI coding agents guide explains why repository access and command execution make these rules consequential.

Keep It Short, Specific, And Tested

Put the root AGENTS.md where every repository task can inherit it. Add nested guidance only for a real local difference. Name exact commands, protected boundaries, deployment source of truth, and stop conditions. Then test the instruction chain from each important working directory.

The file is successful when an agent stops guessing about how the repository expects work to happen. The tests, permissions, review, and deployment checks still decide whether that work is safe to accept.