What is AGENTS.md. A Markdown file with no required fields that Codex, Cursor and Copilot read

AGENTS.md is a README for AI coding agents. What to put in it, where it goes, how nested files work and which tools read it.

Part of the guideClaude Code, the complete guide. From installation to your own skills and plugins

In this article
  1. What is AGENTS.md and why write one
  2. What format does AGENTS.md use
  3. Where AGENTS.md lives and how nested files work
  4. Which tools read AGENTS.md
  5. AGENTS.md is an instruction, not a lock

In short

AGENTS.md is a plain Markdown file in the root of a repository that holds instructions for AI agents that write code. It has no required fields, a large project can have several of them, and the one closest to the edited code takes precedence. Codex, Cursor, Gemini CLI and the GitHub Copilot coding agent are among the tools that read it.

A new developer gets access to the repository and starts an AI agent right away. The agent does not know how tests run here, so it guesses, runs the wrong command and spends fifteen minutes fixing something that was never broken. One line in an AGENTS.md file would have saved that. That is the shortest answer to what AGENTS.md is.

This article is part of our Claude Code guide. We checked the facts on the pages of the format and the tools, as of 10 November 2026.

What is AGENTS.md and why write one

The format's own site, agents.md, calls it a README for agents. A README is for people. It describes the project, says how to get started and should not drown in detail. AGENTS.md is for AI agents that write code. It holds the things that would clutter a README. Build and test commands, code style, rules for pull requests.

It is an open format, not a feature of one vendor. According to agents.md, more than 60 thousand open source projects use it, and it is looked after by the Agentic AI Foundation under the Linux Foundation.

For a company that outsources code or has a developer in house, the point is simple. You write the project rules once, and every AI tool that reads them starts with the same knowledge. Nobody has to copy them into a separate file for each program.

What format does AGENTS.md use

Nothing special. It is plain Markdown with no required fields and no headings you have to use. The agent reads the text the way a person would. What matters is that each instruction is concrete enough to check whether it was followed.

The format's site suggests starting with test commands. If they are in the file, the agent will try to run them and fix failures before it calls the task done. The file is meant to live with the project, so you update it whenever something in the project changes.

This is what an AGENTS.md could look like for a made-up project, a coffee shop built on Laravel and Vue.

AGENTS.md
# Bean Shop

Laravel 12 and Vue 3. The admin panel lives in `resources/js/admin`.

## Setup
- `composer install` and `npm install` after cloning
- `php artisan serve` and `npm run dev` start the site locally

## Tests
- `php artisan test` before every commit
- `npm run lint` after any change to Vue files
- Every bug fix gets a test that reproduces the bug

## Code style
- 4 spaces in PHP and 2 spaces in Vue
- Customer facing text only in `lang/en.json`
- New database tables only through migrations

## Pull requests
- Title format `[shop] short description`
- Do not change files in `config/payments` without asking

There is no company description here and no request for "clean code". The agent can see the code. The file tells it only what it cannot learn from the code.

Where AGENTS.md lives and how nested files work

The main file sits in the root of the repository. In a large repository with several apps, you can add a separate AGENTS.md in each app's folder. The rule on the format's site is simple. The agent reads the file nearest to the code it is editing, so a file in a subfolder takes precedence over the root one. A direct instruction in the chat beats any file.

The details differ between tools. OpenAI describes them most precisely in the Codex documentation.

WhatHow Codex does it
Global file~/.codex/AGENTS.md for all projects
OverrideAGENTS.override.md read instead of AGENTS.md
Orderfrom the repository root down to the current folder
Mergingfiles joined, closer ones come later
Limit32 KiB in total, setting project_doc_max_bytes

One practical point follows from the table. Codex takes at most one file per folder, and once the total reaches the limit, further files stop being added. A long AGENTS.md eats that budget fast, so keep it short.

Codex can also treat other file names as instructions. You list them in ~/.codex/config.toml, and Codex ignores names that are not on the list.

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

Which tools read AGENTS.md

The agents.md site lists the tools that support the format. They include Codex from OpenAI, Jules and Gemini CLI from Google, Cursor, Windsurf, Devin, Aider, Zed, Warp, VS Code, Junie from JetBrains and the GitHub Copilot coding agent. The full list on the site is longer.

Two tools on that list need one line of configuration. In Aider you add read: AGENTS.md to .aider.conf.yml. In Gemini CLI you set AGENTS.md as the context file in .gemini/settings.json.

Claude Code is not on the list. Even so, Anthropic's documentation says that from version 2.1.277 Claude Code reads AGENTS.md on its own when the project has no CLAUDE.md. When exactly that happens and how to keep both files in sync is covered in AGENTS.md vs CLAUDE.md. CLAUDE.md itself is explained in our CLAUDE.md article, and ready templates are in CLAUDE.md examples.

AGENTS.md is an instruction, not a lock

The agent reads AGENTS.md and tries to follow it, but it is text for a model, not a lock. Anthropic says plainly that Claude treats such files as context, not enforced configuration. A line saying "do not touch the payment files" stops nobody if the agent decides otherwise. Anything that must really be blocked belongs in the permission settings of the specific tool. For Claude Code we cover that in the article on permissions.

AGENTS.md goes into the repository, so anyone with access can read it. Passwords, API keys and internal server addresses do not go there.

To start, a file with four sections like the example above is enough. After that, add one sentence each time the agent makes the same mistake twice.

If you want to know where AI can take work off your company, ask for our free AI audit. We look at your tasks and tell you where to start.

Documentation for this topic

What would you like to change in your business?

Leave your number. We will talk about your process and see whether we can help. The first call is free.

When is the best time to call?
Controller: Oleksandr Bondarenko (BondSoft)Privacy PolicyTerms of Service
Legal details

The data controller is Oleksandr Bondarenko, trading as Oleksandr Bondarenko Software Solutions (BondSoft), ul. Jana Heweliusza 11, 80-890 Gdańsk, Poland, NIP 5833576264, e-mail: office@bondsoft.pl.

We process your data solely to contact you about your enquiry and to present an offer — on the basis of your consent (Art. 6(1)(a) GDPR and Art. 398 of the Polish Electronic Communications Law) and our legitimate interest in handling the enquiry (Art. 6(1)(f) GDPR).

Providing the data is voluntary but necessary for us to reply. You may withdraw your consent at any time by writing to office@bondsoft.pl — this does not affect the lawfulness of processing before the withdrawal.

You have the right to access your data, rectify it, erase it, restrict its processing, transfer it, and lodge a complaint with the President of the Polish Personal Data Protection Office.

Full information: Privacy Policy.

Send us an email

The service this text is about

Automation and AI / OCR

Automation of document re-typing, OCR and checking rules, and your data stays with you.