AGENTS.md: What Is It and Why Does It Exist?

What is AGENTS.md, and why does it exist?

If you have ever explored a repository on GitHub, you have probably come across a README.md file.

A README.md is useful to developers trying to understand a software project. It explains what the project does, how it works, how to set it up, and sometimes what to keep in mind while developing it.

AGENTS.md serves a similar purpose, but with an important difference: it is written for AI coding agents.

AGENTS.md is an open, Markdown-based format intended to provide a standard starting point where an agent can find the information and instructions it needs while working on a project.

For example, it can describe a project’s architecture, coding standards, test commands, or critical considerations for development.

That way, we do not have to explain how the project works and what rules to follow again for every new task.

But here it shares a problem with README.md.

When a README.md is too short, it can be hard to understand the project. When it is too long, important information can be hard to find.

The same problem applies to AGENTS.md. And when we consider the context windows and token costs used by coding agents, the impact can be even greater.

So our goal should not be to create the most comprehensive AGENTS.md possible. It should be to find the right balance: enough useful information and guidance, without overloading the file.

Before discussing how an ideal AGENTS.md should be written, though, we need to understand how this file is actually used.

How does AGENTS.md actually work?

I think the first thing we need to understand is the difference between an AI coding agent and an LLM.

Coding agents such as OpenCode, Codex, and Claude Code are not just LLMs.

Behind these tools is a system that processes a user’s request, communicates with an LLM, runs the necessary tools, and sends the results back to the model.

This system is commonly called an agent harness, and its repeated work cycle is called an agent loop.

In simplified form, the process looks like this:

User Prompt
    |
    v
Agent Harness
    |
    | Prepare context
    | - System instructions
    | - AGENTS.md
    | - Conversation history
    | - Available tools
    |
    v
  LLM
    |
    v
Tool call needed?
    |
    +-- Yes --> Execute tool
    |               |
    |               v
    |          Add tool result
    |               |
    |               +----> LLM
    |
    +-- No ----> Final response

The important point is that a single message to a coding agent can turn into multiple LLM calls behind the scenes.

To make this concrete, let’s use OpenCode, an open-source coding agent, as an example.

An example with OpenCode

Imagine that we are building a membership platform and the repository contains the following AGENTS.md file:

# AGENTS.md

- Inspect existing code before making changes.
- Preserve idempotency in payment operations.
- Run relevant tests after implementation.

Now let’s give OpenCode this request:

Check whether there is a problem in membership renewals that could charge for the same payment twice, and fix it if there is.

The first LLM call

OpenCode first includes the relevant project instructions, the user’s message, and the available tools in its request to the model.

The submitted content might look roughly like this:

{
  "system": [
    "You are an AI coding agent...",
    "Instructions from: AGENTS.md\n- Inspect existing code before making changes.\n- Preserve idempotency in payment operations.\n- Run relevant tests after implementation."
  ],
  "messages": [
    {
      "role": "user",
      "content": "Check membership renewal for duplicate payment risks and fix any issues."
    }
  ],
  "tools": [
    { "name": "read" },
    { "name": "edit" },
    { "name": "bash" }
  ]
}

This and the following JSON examples are simplified illustrations of OpenCode V2’s behavior. They are not exact representations of the provider API payload.

When the model evaluates this request, it may first want to inspect the existing code.

It can produce a tool call like this:

{
  "tool_calls": [
    {
      "id": "call_001",
      "name": "read",
      "arguments": {
        "filePath": "backend/payments/renewal.go"
      }
    }
  ]
}

There is an important detail here.

The LLM does not read the file itself. It only specifies which tool should run, and with which arguments.

OpenCode receives this request, runs the relevant tool, and gets the file contents.

The second LLM call

OpenCode now prepares a new request to the model. This time, in addition to the previous request, the conversation history also contains the model’s tool call and the result returned by the tool.

{
  "system": [
    "You are an AI coding agent...",
    "Instructions from: AGENTS.md\n- Inspect existing code before making changes.\n- Preserve idempotency in payment operations.\n- Run relevant tests after implementation."
  ],
  "messages": [
    {
      "role": "user",
      "content": "Check membership renewal for duplicate payment risks and fix any issues."
    },
    {
      "role": "assistant",
      "tool_calls": [
        {
          "id": "call_001",
          "name": "read",
          "arguments": {
            "filePath": "backend/payments/renewal.go"
          }
        }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "call_001",
      "content": "func RenewMembership(...) { ... }"
    }
  ],
  "tools": [
    { "name": "read" },
    { "name": "edit" },
    { "name": "bash" }
  ]
}

Notice that the AGENTS.md instructions are still present in the second call.

The previous tool call and its result are also sent to the model.

Based on the file’s contents, the model may now decide to make a change. It can call the edit tool, and after OpenCode makes the change, another LLM call can follow.

The third call may include the earlier messages as well as the edit tool call and its result.

This process continues until the agent finishes the task.

Of course, a real implementation is more complex. It can involve multiple tool calls, retries, context compaction, and mechanisms specific to different providers.

But the key point we need to understand about AGENTS.md is this:

AGENTS.md is not a file saved in the LLM’s permanent memory. It is a set of instructions that the coding agent adds to the context used by the model.

Is AGENTS.md sent again with every LLM call?

When we look at the OpenCode V2 source code, we can see that the initial instructions are included in the system context whenever a new model request is prepared.

That does not mean AGENTS.md is read from disk on every call and added to the conversation history as a new message each time.

OpenCode V2 tracks the state of its instructions. When the root-level AGENTS.md changes, it can detect that change and apply it to the next model request.

AGENTS.md files in subdirectories can be loaded when the agent explores the relevant directory. There is also a mechanism to avoid adding the same instructions unnecessarily more than once.

Not every coding agent behaves this way. Codex, for example, can discover AGENTS.md files through its own directory hierarchy and present them to the model differently.

So how AGENTS.md is processed depends on the implementation of the coding agent we use.

That brings up another topic: context cost.

Suppose AGENTS.md adds 3,000 tokens to the model’s initial context, and a task involves 20 LLM calls.

In that case, content originating only from AGENTS.md could theoretically account for 60,000 input tokens across those requests.

That does not mean all of it is processed again at the same cost. Optimizations such as prompt caching can reduce the cost.

But the example shows why unnecessary instructions can matter.

Instead of carrying information that does not help with a task into every LLM call, it may be better to make the relevant documentation available only when needed.

Source: OpenCode V2 — Instructions

What should an ideal AGENTS.md contain?

I think the first question we need to answer is this:

If a developer joined this project today, what would they need to know first to work on it correctly?

Of course, developers and coding agents do not work in the same way. But this is a useful starting point for deciding what belongs in AGENTS.md.

The project’s purpose, relevant documentation sources, current architecture, development standards, verification commands, and important decision boundaries can all be useful here.

But that does not mean every detail needs to be explained in AGENTS.md.

For example, we could create a file like this for a membership platform:

# AGENTS.md

## Project
Membership and subscription management platform.

## Documentation
- README.md: Project setup
- docs/product/: Product requirements
- docs/architecture/: Architecture decisions

Read documentation relevant to the current task.

## Engineering
- Inspect existing patterns before introducing new ones.
- Follow documented domain and architecture constraints.
- Do not change billing semantics without approval.
- Do not modify previously deployed migrations.

## Verification
- Run relevant tests after implementation.
- Use `go test ./...` for backend-wide verification.
- Report tests that could not be executed.

## Completion
Summarize changes, verification results,
and any remaining risks.

This example keeps AGENTS.md fairly simple.

It also points to the existing documentation when describing specific development standards.

That way, we do not have to move the whole project’s architecture and business rules into AGENTS.md.

There is another point we should consider here.

Should business rules go in AGENTS.md?

Remember the example we started with:

- Preserve idempotency in payment operations.

When we add this instruction to AGENTS.md, we are not only telling the agent how to work. We are also defining a technical behavior that our payment system must preserve.

Is that wrong?

I don’t think so.

In fact, the official AGENTS.md documentation and coding agent providers’ guides show that project-specific constraints and engineering rules can belong in this file.

But we need to be careful.

For example, if we put every subscription rule, payment state, and failure scenario in our membership platform into AGENTS.md, we could create a second source of information that repeats the existing technical documentation.

Over time, the two documents could contradict each other.

It may be more sustainable to briefly call out a critical behavior and point to its detailed explanation.

For example:

## Payment Operations

- Payment webhooks may be delivered multiple times.
- Before changing payment flows, read
  docs/architecture/payments.md.
- Preserve documented idempotency guarantees.
- Add regression tests for duplicate delivery.

This example highlights an important characteristic of the payment system and points to the current technical documentation.

But pointing to documentation is not enough by itself. If a critical behavior must be preserved, we should also verify it with automated tests wherever possible.

Because AGENTS.md is a source of instructions; it is not a replacement for tests, authorization, or security mechanisms.

So I do not think business rules should never appear in AGENTS.md.

The real question is which rules an agent needs to be reminded of all the time, and which are sufficient to read only when they become relevant.

When should AGENTS.md be created? Is writing it once enough?

I think it makes sense to create AGENTS.md at the start of a project.

It is also possible to use tools such as OpenCode’s /init command to inspect an existing repository and prepare a starting file.

But using the generated file without reviewing it may not be a good idea. We need to verify that the agent’s descriptions match the current architecture and the real development commands.

Is the work done once AGENTS.md has been created?

Definitely not.

Software projects keep changing. We add services, update architecture decisions, or move on from approaches we used in the past.

When AGENTS.md is unaware of these changes, it can keep giving the agent instructions that are no longer valid.

For that reason, it is better to see AGENTS.md not as a one-time configuration but as a working document that evolves with the project.

That does not mean adding new instructions to the file after every development task.

For example, if we fix a conditional bug in a function, adding an instruction like “write conditions correctly” to AGENTS.md is not very useful.

But if we notice that the agent repeatedly misinterprets the same architecture decision or ignores an important development standard, we should investigate.

Maybe a technical document is missing. Maybe AGENTS.md does not point to the right document. Maybe what is missing is an automated test.

I think one of the best ways to make AGENTS.md part of the day-to-day development process is to ask this question when meaningful tasks are complete:

Did we learn something during this task that future tasks will also need to know?

If so, we can make that knowledge persistent in the right place.

It also makes sense to track AGENTS.md files in Git and include significant changes in code review.

After all, we are not talking about just another documentation file. We are talking about something that can affect an agent’s behavior.

How can we test whether AGENTS.md is actually useful?

After creating AGENTS.md, we should verify that the agent is actually using it.

We can start with a simple test.

For example, let’s add a project-specific test command to AGENTS.md:

## Verification
- The project's verification command is
  `make verify-memberships`.

Then, in a new OpenCode session, we can ask:

opencode run \
  "What is the project's verification command?"

We would expect the agent to answer make verify-memberships.

But this result alone does not prove that AGENTS.md was used.

The same information might also appear in README.md, Makefile, or another document.

For a more reliable check, we need to inspect the prepared model request using suitable logging or request-tracing mechanisms.

That lets us see whether the AGENTS.md instructions were actually sent to the LLM.

But there is a second—and, in my view, more important—test here:

Does reading AGENTS.md actually lead to better results?

To evaluate this, we can run the same development task in two separate environments, one with AGENTS.md and one without it.

For example, consider an idempotency problem in membership renewal.

We should use the same model, the same starting code, and the same user request in both environments. Repeat the test several times while keeping the conditions as similar as possible.

Then compare the results.

Did the agent implement the correct behavior? Did it preserve the existing architecture? Did regression tests pass? How many LLM calls did it make? How many tokens did it use? How long did the task take?

We could even create a third environment with a short AGENTS.md containing only the essential rules.

This would let us evaluate not only whether the file exists, but also how its content and length affect the results.

For this kind of experiment, it is important to isolate the tests and evaluate the results against criteria chosen in advance. Otherwise, we risk treating one successful agent run as proof that AGENTS.md works.

Does AGENTS.md always help?

So far, we have discussed how AGENTS.md works, how it can be written, and how it can be tested.

But the main question is:

Does using AGENTS.md always make coding agents more successful?

Two studies published in 2026 report some interesting findings on this question.

The first study, Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?, examines how repository-level context files affect coding agent performance.

Its results are not as positive as we might expect.

Across the evaluated agent and model combinations, these files tended to reduce task success rather than improve it, while increasing inference costs by more than 20%.

More interestingly, agents tended to follow the instructions, but that did not lead to better results.

In other words, an agent applying the instructions in AGENTS.md does not necessarily mean it will complete the task more accurately.

On the other hand, another study, On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents, examines the effect of AGENTS.md across 10 repositories and 124 pull requests.

In the conditions where AGENTS.md was used, the study reports a 28.64% reduction in median runtime and a 16.58% reduction in output token usage. Task completion behavior remained at a comparable level.

The evaluation methods in these studies differ, so it would not be right to compare their results directly.

But I think these different findings start an important discussion.

Does it matter that AGENTS.md exists, or what it contains?

For example, how useful is it to repeat information that an agent could easily learn from the source code?

And does asking the agent to read all the architecture documents for every development task actually lead to better results?

A recent OpenAI article on AGENTS.md and prompt design also points out that asking agents to read unnecessary documents before every small change can increase context costs.

My takeaway is not that AGENTS.md should be as short as possible.

Every instruction in it should have a purpose.

It may be useful to define critical technical rules clearly in a complex payment system. But it may be unnecessary to process those same rules constantly for a simple frontend change.

So we cannot explain the impact of AGENTS.md with one correct structure or an ideal number of lines.

I think the right approach is to start small based on the needs of our project and the agent we use, measure the results, and improve the instructions accordingly.

Conclusion

I think AGENTS.md can be a very useful tool when working with AI coding agents.

But we should not treat it as a huge prompt where we put all of the project’s information.

When we look at how a coding agent works, we can see that AGENTS.md is not just a documentation file; it is part of the context presented to the LLM.

That means every piece of information we add has a cost and can potentially affect the agent’s behavior.

It is important to state critical rules, point to the right documentation, and define boundaries for the work.

But we also need to verify that all of this is actually useful.

To me, a good AGENTS.md is not the file with the most instructions.

It is the file that helps an agent use the information it needs to make the right decisions, at the right time and in the right way.

And perhaps the most important question to ask when writing AGENTS.md is:

Which decision will this instruction help the agent make better?

If we cannot answer that, perhaps we do not need the instruction.

Sources

• AGENTS.md — Open format and examples
• OpenCode V2 — Instructions
• OpenCode — GitHub repository
• OpenAI — Using AGENTS.md with Codex
• OpenAI — Rethinking Skills and Prompts for GPT-6 Astra
• Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?
• On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents

Working on an AI project?

If you’re working on an AI project and want to talk it through, book a call.