Writing an Effective AGENTS.md for Coding Agents

An AGENTS.md file can tell a coding agent how to work inside a repository: where relevant code lives, which commands to run, which files have special handling, and what needs to be true before a change is complete.

The format itself is deliberately lightweight. The official AGENTS.md guidance defines no mandatory sections or fixed schema. It uses ordinary Markdown and suggests information such as project structure, build and test commands, code conventions, testing instructions and security considerations, while leaving each project to decide what its agents need.

That flexibility creates the more interesting problem. A repository can easily end up with an AGENTS.md full of accurate information that does little to improve an agent's work.

For each instruction, ask whether knowing it would change what the agent does.

If not, the information may belong somewhere else.

What problem is AGENTS.md solving?

A coding agent can already inspect source files, configuration, package manifests, tests and documentation. It can often determine which language a project uses, identify common naming patterns and find a test directory without being told.

What it cannot reliably infer is the repository knowledge behind those files.

The obvious build command might produce an incomplete binary. A directory may contain generated code that should never be edited directly. Two packages may look as though they can depend on each other even though the project's architecture forbids it. A small change may require one particular validation command that is not obvious from the test suite.

That is where AGENTS.md is useful: recording repository-specific knowledge that affects how an agent should act.

This distinction also separates it from a README or contributor guide. Those documents may explain the project, installation, contribution process and design in considerable detail. An AGENTS.md can point to them where useful without reproducing everything an agent might possibly read.

AAIF's five-run AGENTS.md experiment compared otherwise identical repository copies with and without a short AGENTS.md. On the more complex task, two of the five runs without the file spent time reorienting themselves in the repository or running an unrequested production build. None of the runs with the file did either. The experiment covered one repository and one agent, so it is useful evidence rather than a general benchmark.

A larger study by Jai Lal Lulla and colleagues tested 124 pull-request tasks across 10 repositories. Runs with AGENTS.md had a 28.64% lower median runtime and used 16.58% fewer median output tokens. The study focused on operational efficiency rather than a comprehensive evaluation of patch correctness, so those numbers should not be read as evidence that an AGENTS.md automatically produces better code.

The evidence is not uniform. Thibaud Gloaguen and colleagues evaluated context files across four coding agents using SWE-bench Lite and a new benchmark built from repositories with developer-committed context files. They found that context files did not significantly improve task success overall and consistently increased the number of steps and execution cost. LLM-generated files had a marginal negative effect on task success, while developer-written files showed a marginal gain; neither difference from using no context file was statistically significant. Developer-written files did, however, significantly outperform LLM-generated ones. The trace analysis found that agents generally followed specific instructions in the files, including recommendations to use repository-specific tools, while repository overviews did not help them reach relevant code more efficiently. The authors conclude that context files are useful for specifying non-standard coding practices, but should contain specific information not already available in the repository and should be evaluated before being adopted as a way to improve agent performance.

One of the study's ablations shows a condition in which context files did improve performance. When the authors removed all other documentation from the codebase, LLM-generated context files improved performance by 2.7% on average and outperformed developer-written ones. The authors suggest this may explain reports of agents performing better once a context file is added, since many less popular repositories contain little documentation.

Taken together, these results support a narrower case for AGENTS.md. A carefully maintained file can help, but filling one automatically with everything that can be discovered about a repository may create extra work rather than remove it.

Put in information the agent cannot safely assume

The most useful AGENTS.md files tend to combine orientation, operational commands and repository-specific constraints. The exact mixture depends on the project.

Repository structure is useful when the structure carries meaning that filenames alone do not reveal. In a monorepo, for example, an agent may need to know which package owns a feature, whether applications are independently deployable or where shared code is expected to live.

Cloudflare's Agents repository identifies the roles of its core packages, examples, guides, sites and documentation. Google Workspace's Go samples establishes an equally important fact before an agent starts making assumptions: the repository is a collection of independent samples rather than one monolithic application.

A directory listing copied into AGENTS.md adds much less. The useful information is the meaning behind the structure.

Commands deserve similar treatment.

Consider:

Run the tests before submitting.

An agent still needs to decide which tests to run, where to run them from and whether anything needs to happen first.

Compare that with:

From `services/api`, run the affected test file while iterating:

pytest tests/<affected_test>.py

Before completing a change to the API, run:

pytest tests/
ruff check .

The second version removes decisions that would otherwise require exploration or guessing.

Some repositories have an even stronger reason to record their commands. Kubo's AGENTS.md explicitly tells agents to use make build rather than go build because its Makefile supplies required linker flags. It also directs agents to the repository's make mod_tidy target instead of running go mod tidy directly because three Go modules need to remain synchronized.

That is particularly useful AGENTS.md material. An experienced Go developer could make a reasonable choice and still get it wrong for this repository.

Record the exceptions and boundaries

Repository-specific boundaries can be more valuable than general coding guidance.

Generated files are a common example. "Do not edit generated files" helps only if the agent can reliably identify them. Better guidance names the relevant paths and explains what to change instead:

bash

Files under `packages/client/generated/` are generated from
`schemas/openapi.yaml`. Do not edit them directly.

After changing the schema, regenerate the client from the repository root:

pnpm generate:client

The same principle applies to architecture.

Follow the existing architecture.

does not identify an architecture rule.

A useful instruction might say:

`packages/ui` may depend on `packages/core`.

`packages/core` must not import from `packages/ui`.

Code shared by both packages belongs in `packages/core`.

Gutenberg's AGENTS.md records this type of dependency direction explicitly. Its editor packages form three layers, from block-editor through editor to edit-post and edit-site, and lower layers must not depend on higher ones. That gives an agent a constraint it might not discover until after producing an otherwise plausible implementation.

Other boundaries may concern public APIs, compatibility requirements, dependency management, migrations or actions that require human approval. The Azure SDK for Go, for example, identifies generated SDK code and lists actions agents should not perform without human approval, including approving releases and license changes.

These instructions should describe the boundary precisely enough for an agent to act on it. They should not attempt to replace access controls, CI checks or other enforcement mechanisms.

Tell the agent how to know when it is finished

"Run the tests" and "make sure everything works" are weak definitions of done.

A repository may have several layers of validation: a focused test while developing, package-level tests before finishing, formatting or lint checks, and a larger suite handled by CI.

An effective AGENTS.md explains the validation appropriate to the change.

Rails provides commands for running a component's tests, one test file, an individual test or line, and database-specific Active Record test suites. The useful information is how an agent should select the relevant validation for the work it has changed.

A repository instruction could therefore say:

For changes under `apps/web`, run the relevant Vitest file while iterating.

Before completing the task, run:

pnpm --filter web test

pnpm --filter web lint

Run the full workspace test suite only when the change touches a shared

package under `packages/`.

This is more useful than always demanding the largest possible test suite. It tells the agent how validation effort should scale with the change.

Vague instructions versus usable instructions

Specificity is useful when it removes a decision the agent would otherwise have to make.

Vague	What is missing	More usable
Run the tests.	Which tests, where and when?	From services/api, run the affected pytest file while iterating. Run pytest tests/ before completing an API change.
Don't edit generated code.	Which code is generated?	Do not edit packages/client/generated/. Change schemas/openapi.yaml, then run pnpm generate:client.
Follow existing patterns.	Which implementation is canonical?	New HTTP handlers should follow services/api/routes/users.py, including validation and error handling.
Follow the architecture.	Which boundary must be preserved?	packages/core must not import from packages/ui. Shared code belongs in packages/core.
Use the standard build process.	What is standard here?	Run make build from the repository root. Do not use go build; the wrapper supplies required build metadata.

An instruction does not need to explain everything about the repository. It needs enough detail to remove the ambiguity that causes the wrong action.

What should stay out?

The studies by Lulla et al. and Gloaguen et al. reach different results on efficiency, but Gloaguen's trace analysis provides more direct evidence for being selective about what goes into the file. Repository overviews did not help agents reach relevant code more efficiently, while context files overall increased steps and execution cost. That makes broad repository descriptions a poor default unless they provide information the agent cannot readily recover elsewhere.

Information that is obvious from the repository is an easy candidate for removal. An agent does not usually need a paragraph explaining that a project uses TypeScript if package.json, tsconfig.json and the source tree already make that clear.

Generic software advice has a similar problem:

javascript

Write clean code.
Use meaningful variable names.
Follow best practices.
Test your changes carefully.

None of these instructions tells the agent what this repository requires.

Duplicating large sections of existing documentation creates another maintenance problem. VS Code's AGENTS.md takes a deliberately small approach: it points agents to the project's existing Copilot instructions for detailed architecture, coding and validation guidance rather than maintaining another copy.

Whether references like this are handled identically across every agent is an implementation question, but the maintenance principle remains useful: avoid creating two sources of repository guidance that can quietly disagree.

Some rules should move out of prose altogether. If a formatting rule can be enforced reliably by a formatter, put it in the formatter configuration. If a dependency must never cross a boundary and static analysis can enforce that rule, add the check. AGENTS.md can tell an agent about those systems, but it should not be the only thing preventing an invalid change.

Sensitive information belongs elsewhere too. Repository instructions should never contain credentials, secrets or private operational details simply to save an agent from asking for them.

One file or several?

A small repository may need only one AGENTS.md at its root.

Larger repositories can place additional files closer to the code they describe. The official AGENTS.md guidance supports nested files and states that the closest AGENTS.md to an edited file takes precedence when instructions conflict. Explicit user instructions override repository guidance.

Consider:

repo/
├── AGENTS.md
├── apps/
│   └── web/
│       ├── AGENTS.md
│       └── src/
├── services/
│   └── api/
│       ├── AGENTS.md
│       └── src/
└── packages/
        └── shared/

The root file could contain information that applies everywhere:

# Repository instructions

Use pnpm from the repository root.
Do not commit generated artifacts.
Run `pnpm lint` before completing changes that span multiple packages.

The file under services/api/ can then contain instructions that make sense only there:

# API instructions

Use Python 3.13.

Run tests from this directory with:

pytest tests/

Database schema changes require a migration under `migrations/`.
Do not modify an existing applied migration. Add a new one.

There is little benefit in making every agent working on the frontend consume detailed migration instructions.

Nested files are therefore most useful where the repository itself has meaningful boundaries: different languages, build systems, validation processes, architectures or ownership rules.

The exact way applicable files are discovered and combined can differ between agent implementations, so a repository using nested instructions should still test the behavior of the agents it relies on rather than assume every tool handles the hierarchy identically.

A worked example

Imagine a repository containing a web application, a Python API and a generated TypeScript client:

acme-platform/
├── apps/
│   └── web/
├── services/
│   └── api/
├── packages/
│   └── client/
│       └── generated/
├── schemas/
│   └── openapi.yaml
├── package.json
└── AGENTS.md

A first attempt at AGENTS.md might look like this:

# AGENTS.md

This is the Acme Platform repository.

Follow the existing coding style.
Run tests before submitting changes.
Do not edit generated files.
Keep changes focused.

Nothing here is unreasonable, but it leaves most of the important repository decisions unresolved. The agent still has to identify which files are generated and how to regenerate them, work out which tests apply to the frontend and API, locate the right starting point for an API change, and determine whether changing the schema also requires updating the client.

A more useful version could be:

sql

# AGENTS.md

## Repository layout

`schemas/openapi.yaml` is the source of truth for the public API schema.
`packages/client/generated/` contains the generated TypeScript client.

## Package management

Use pnpm from the repository root.

Do not run npm install inside individual packages. Workspace dependencies
are managed from the root `pnpm-lock.yaml`.

## API changes

For API implementation changes, work under `services/api/`.

Run the affected test while iterating:

cd services/api
pytest tests/<affected_test>.py

Before completing an API change, run:

pytest tests/
ruff check .

## Web changes

For changes under `apps/web`, run:

pnpm --filter web test
pnpm --filter web lint

## Generated client

Do not edit `packages/client/generated/` directly.

When an API change affects the public schema:

1. Update `schemas/openapi.yaml`.
2. From the repository root, run `pnpm generate:client`.
3. Include the resulting generated client changes.

## Validation

Changes confined to one application do not require the full workspace
test suite.

Run `pnpm test` from the repository root when changing shared packages
or behavior used by both the web application and API.

Each addition addresses a specific ambiguity.

The layout section names only the schema file and the generated directory; the rest is evident from the repository and the commands below. The package-management rule prevents a plausible command that would conflict with the workspace. The test instructions tell the agent how much validation is appropriate. The generated-client section identifies both the protected path and the source it should edit instead.

The file is longer because this repository contains several pieces of knowledge that affect agent behavior. Another project may need much less.

A practical starting template

There is no required AGENTS.md structure. A starting file can be compact:

# AGENTS.md

## Repository layout

<!-- Include only locations or boundaries that are not obvious. -->

`src/...`:
`tests/...`:

typescript

## Setup and commands

<!-- Include exact commands and any important working-directory
     requirements. -->

Install:
Build:
Test:
Lint/format:

## Repository-specific rules

<!-- Add conventions or architecture constraints that materially
     affect changes. -->

- ...

## Generated or restricted files

<!-- Omit if there are none. Say what to edit or run instead. -->

- ...

## Validation

<!-- Explain what should be checked before a change is complete. -->

- ...

Do not fill every heading simply because the template contains it. An empty section contributes nothing, and a generic instruction added to make the file look complete can make the useful instructions harder to find.

Start with the repository facts that have consequences.

Keep the file useful

An AGENTS.md should change with the repository.

If the build moves from npm to pnpm, the commands need to change. If CI starts enforcing a rule automatically, the file may no longer need to explain that rule in detail. If a generated directory moves, an old warning about its previous path is worse than no warning.

Agent behavior can provide maintenance signals too. When agents repeatedly spend time locating the same subsystem, choose the wrong validation command or require the same correction from reviewers, check whether a small repository instruction would remove that ambiguity.

The reverse matters as well. Instructions that no longer affect decisions should be removed.

A useful AGENTS.md does not try to describe everything an agent might encounter. It records the repository knowledge that changes what the agent should do, places more specific guidance where it applies, and stays close enough to the code and tooling that the instructions remain accurate.