What Belongs in AGENTS.md? A Practical Guide for Coding Agents

Put repository-specific guidance in AGENTS.md when it helps a coding agent make a decision it could otherwise get wrong: which commands to run, which contracts to preserve, where generated files come from, and how to verify a change. Keep temporary requirements with the task, link to deeper documentation when relevant, and enforce critical restrictions through tools and permissions.

The useful question for each line is: What decision does this instruction change, and how will we know it helped?

That question gives you a way to review the file without adopting a universal template or an arbitrary length limit. It also makes maintenance easier: an instruction needs a purpose beyond having sounded sensible when someone added it.

The AGENTS.md project defines an open Markdown format for supplying context and instructions to coding agents. It requires no fixed schema. The flexibility leaves the repository owner responsible for selecting useful guidance and checking how the chosen agent loads it.

Give each instruction a destination

When reviewing an existing file, classify its contents into four actions. These are editorial decisions, not a scoring system validated by a benchmark.

An instruction can need more than one action. You might automate a contract test and keep a short explanation of the contract in AGENTS.md. The test detects a violation; the explanation helps the agent understand why the behavior matters.

Keep decisions the code does not fully explain

A repository contains many observable facts. Its directory tree, dependency manifest, and existing code are available for inspection. An instruction earns its place when it helps interpret those facts or supplies something they leave ambiguous.

For example, an exported field may look awkwardly named. The code shows its name, but may not explain that another system requires it. A useful instruction identifies both the constraint and its reason:

Preserve the exported JSON keys customer_id and created_at. A downstream importer expects those names. A display-label change does not authorize a change to this export contract.

That sentence gives the agent a decision to make when a task says “clean up the labels.” A general request to “maintain backward compatibility” leaves more interpretation to the agent.

Other candidates include the supported local verification command, a fixture that must stay synthetic, or the source file and generator behind a checked-in artifact. State the working directory and prerequisites for commands. A command copied from a different project is an unverified assumption until it works here.

Choose detail according to the work. A brief note about an unusual architectural boundary may be valuable. A directory listing that must be updated after every move is harder to justify unless it helps resolve a specific navigation problem.

Move detail to the place where it becomes relevant

Long reference material can remain useful without being included in every task. Preserve a short instruction explaining when to consult it:

Before changing the exported fields, read docs/export-contract.md and check the consumer compatibility requirements.

The trigger matters. A list of twenty documentation links gives little guidance about which one is needed for a small bug fix. A relevant trigger connects a decision to its supporting material.

Put a one-time rollout sequence in the task or rollout document. Put subsystem-specific guidance near that subsystem when the agent supports the required scope. Put personal preferences in the tool's user-level configuration when they are not team requirements.

Check the implementation before relying on file placement. VS Code's current instructions documentation distinguishes Copilot, Local, and other agent harnesses. For example, nested AGENTS.md discovery in Local sessions is experimental and requires settings that do not control Copilot discovery. The same Markdown file does not establish identical loading behavior across tools.

For each agent your team uses, verify which files are loaded, when they are loaded, and how overlapping instructions are combined. Resolve contradictions at their source instead of expecting the agent to choose your intended interpretation.

Automate checks and configure access separately

Use prose to explain a requirement and identify the checks that verify it. Where practical, make the requirement observable in tests, linters, schema validation, or another appropriate check.

For the export example, a test can check the exact public keys and reject an unintended change. The instruction can point to that test and explain the compatibility concern. If the contract changes intentionally, update its specification and tests together as part of that authorized change.

Security restrictions need their own controls. Writing “do not deploy” in a repository file does not remove a deployment credential from the agent's environment. Configure the agent's permissions, available credentials, and execution environment for the intended work. Review instruction-file changes alongside other material that can influence the agent.

As a concrete implementation example, VS Code separates approvals from sandboxing: approvals govern whether actions require confirmation, while sandboxing limits filesystem and network access for terminal commands. Both have behavior and limitations you must check for the selected harness. A policy sentence does not replace those settings.

Keep sensitive values out of the instruction file. Document the approved setup procedure and the names of required configuration variables when appropriate; do not embed real credentials to make a workflow convenient.

Remove instructions you cannot defend

Review broad statements such as “write excellent code,” “always be thorough,” or “use best practices.” If a sentence represents a real project requirement, rewrite it as a decision or observable result. Otherwise, consider removing it.

Pay particular attention to instructions added after a single disappointing run. Before making a correction permanent, identify what failed. Was the command wrong? Was the task missing an acceptance criterion? Did the agent lack permission? Did the model make an implementation error despite having the relevant information? Those problems call for different responses.

Also look for obsolete commands, duplicated rules that have drifted apart, and requirements whose prerequisites no longer exist. Removing a stale instruction should include checking whether a current replacement is needed.

Do not treat a shorter file as proof of a better file. Concision is useful for review and maintenance, but deleting a necessary constraint to meet a line count defeats the purpose.

A worked example: revising a small export project

Consider Customer Export, a synthetic Python project with a public JSON export. Its schema defines two fields, a script generates the Python field list, and tests check the export contract.

An initial instruction file might say:

# Project rules

- Write clean Python and follow best practices.
- Keep everything backward compatible.
- Be careful with generated files.
- Run the tests before finishing.
- See the docs for more information.

The intent is understandable. The agent still has to discover what compatibility means, which files are generated, and how to run the relevant checks.

A more useful version for this particular example is:

# Customer Export

## Environment and checks
- Use Python 3.14; this example uses only the standard library.
- Run commands from the repository root.
- Check changes with: python3 -m unittest discover -s tests -v
- Report the command and result, including any check that could not run.

## Export contract
- Preserve the JSON keys customer_id and created_at. The downstream
  importer expects those exact names.
- Before changing exported fields, read docs/export-contract.md.
- Treat a field addition, removal, or rename as a contract change
  requiring explicit scope in the task.

## Generated field list
- Edit schema/export-fields.json, then run:
  python3 tools/generate_fields.py
- Do not edit generated/export_fields.py by hand.
- After regeneration, run the tests and review the generated diff.

This example file is longer because it replaces vague advice with information that can be checked. Its value would come from whether those instructions help with the project's actual work.

The compatibility rule stays, with a concrete explanation. The longer contract moves into a targeted reference. Tests enforce the current output shape. The generic code-quality slogan disappears. The generator command makes the intended editing path explicit.

The test command uses Python's documented unittest discovery interface. In a local check, the fixture's generator and three contract tests were executed successfully with Python 3.14.2. That verifies the example's commands and limited behavior. It does not show that an agent follows the instructions or performs better with them.

Use the same review process on your repository, replacing every command, path, and constraint with one you have checked. The Python version and export rules above belong to this example.

What the research does and does not establish

Research gives reasons to evaluate instruction files rather than assume a predictable performance gain.

In Evaluating AGENTS.md, version 3, Gloaguen and colleagues evaluated several model/agent configurations on SWE-bench Lite and CTXbench, a Python benchmark containing developer-provided context files. They found no statistically significant aggregate success-rate improvement over no context file in the reported comparisons, while context files increased inference costs. Developer-provided files did outperform generated ones in one reported aggregate comparison. Their ablations also did not establish file length as the explanation for the overall results. The evaluation is bounded by its Python tasks and tested configurations.

A different study, On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents, version 2, used Codex with gpt-5.2-codex on 124 tasks from 10 repositories. It reported lower median runtime and output-token use with the files. The tasks were selected small changes, and the study explicitly deferred a comprehensive correctness evaluation; its manual output sanity check was narrower than that.

These experiments ask overlapping but different questions. Faster output and a higher rate of passing task tests are separate outcomes. Neither study establishes that this article's four-action review method improves an arbitrary agent or repository. Treat the method as a practical way to form changes you can evaluate.

Check the change against real work

Start with a recurring failure you can describe: the agent uses an unsupported test command, changes a public field during a cosmetic task, or edits a generated artifact directly.

Then define what would count as an improvement before changing the instructions. For example: the correct test command runs, the export remains compatible, and the agent reports an unavailable check accurately.

Use an isolated copy of the repository and a representative task. Keep the starting revision, task description, model, agent version, permissions, and acceptance checks consistent when comparing instruction changes. Start independent sessions to avoid carrying prior task knowledge into the comparison. Keep production credentials and data out of the exercise.

Inspect the resulting code and run the relevant acceptance checks. Record unwanted changes and failures as well as time and usage when those measurements are available. One successful run can reveal a useful example, but it cannot establish a reliable success rate. Repeat comparisons before claiming a general improvement, and record remaining sources of variation.

If the agent used the instructions correctly and still failed the task, adding more prose may not address the failure. Investigate the implementation problem, missing tools, task ambiguity, or model limitation instead of automatically expanding the file.

Maintain instructions with the repository

Review the instruction file when the build system changes, a public contract changes, a generator moves, or the agent's loading behavior changes. During review, check:

• Does each command work from the stated directory with the documented prerequisites?
• Does each referenced path exist, and is the linked information current?
• Can you identify the decision each instruction is intended to change?
• Is task-specific information still sitting in a permanent instruction file?
• Are repeated requirements consistent, and are critical controls actually configured?
• Have you checked the result of the latest instruction change against a representative task?

Choose one existing instruction and trace it through the repository: the decision it affects, the source that supports it, and the check that would reveal a mistake. That trace gives you something concrete to keep, move, automate, or remove.

Research note: documentation and the cited paper versions were reviewed on October 28, 2026. Customer Export is a synthetic example with local command checks, not a comparison of coding agents.