AGENTS.md: persistent project instructions

A Markdown file at the root of the repository that tells the agent how your project works: commands, conventions, and how to check changes. It is a guide, not a control mechanism.

Before you start

  • Context engineering for agentsTechnique

    What information the agent receives at each moment, why more is not always better, and how to give it just enough: the essentials up front and the rest when it needs them.

    Published

Key idea: AGENTS.md is a README for the agent. In every task, it tells the agent what a new team member would need to know on their first day. But it is a guide: the agent may not follow it, so don’t use it as a security barrier.

The problem

Without persistent instructions, every task starts the same way: the agent explores the repository, guesses which package manager you use, tries commands that don’t exist, and applies conventions that aren’t yours. You can repeat all of that in every request, but it is slow and you will eventually forget something.

AGENTS.md solves this with a file versioned alongside the code. It is an open format that, according to its website, is used by more than 60,000 open-source projects, and it is read by agents such as Codex and Claude Code.

How it works

  1. The agent looks for AGENTS.md files when it starts working.
  2. It loads their content into the context, alongside your request.
  3. It uses those instructions to plan, edit, and check its work.

Two important details:

  • There can be more than one. A monorepo can have an AGENTS.md at the root and another in each subproject. According to the official site, the agent reads the one closest to where it is working, and that one takes precedence. Each client implements this its own way: Codex, for example, combines the files from the repository root down to the current folder and stops adding once it reaches a size limit.
  • It is context, not configuration. The Claude Code documentation is clear about this: it treats these files as context, not as enforced configuration. If you need to prevent an action, use permissions or a sandbox (covered in Safe agent execution).

What to include

Think about what you would tell someone on their first day:

  • What the project is, in two or three sentences.
  • Commands to install, run, test, and check the code, written exactly as they are used.
  • Conventions that can’t be inferred from the code: folder structure, style, naming.
  • How to verify a change before calling it done.
  • What not to touch: generated files, migrations already applied, sensitive configuration.

And what should not go in it: secrets, long explanations the agent can read in the code itself, or rules that can’t be checked, like “write good code”.

Practical example

A short AGENTS.md for a small project:

# Agent guide

## Project

Reading utilities library in JavaScript (ESM).
Keep the public API and don't add dependencies without a reason.

## Commands

- Tests: `node --test`
- Formatting: `npx prettier --check .`

## Conventions

- One module per file in `src/`; tests next to the module (`*.test.js`).
- Descriptive names in English.

## Before you hand off

- Run the tests. If you can't, explain why.
- Review the diff: no credentials and no generated files.
- Summarize what you changed and what you checked.

It is short on purpose: every line competes with your request for the agent’s attention. If a rule doesn’t change its behavior, it doesn’t belong.

Common mistakes

  • Using it as a security system. “Don’t delete anything” helps, but it doesn’t prevent anything. The real barriers are permissions and isolation.
  • Turning it into an encyclopedia. A thousand-line file uses up context and buries what matters. Long procedures fit better in a Skill.
  • Letting it go stale. A command that no longer exists is worse than no command: the agent will run it with full confidence. Update the file when your scripts change.
  • Mixing requirements and preferences. Distinguish “must” from “we prefer” so the agent knows what is negotiable.

When to use it

As soon as a project has more than a couple of tasks done with agents. It is the first layer of persistent configuration and the one with the best return: a few lines save exploration and mistakes in every task. Start with a small version and add a rule each time you see the agent repeat the same mistake.

Next step

AGENTS.md covers what applies to almost every task. For procedures that are only needed sometimes —preparing a release, adding an endpoint— the next step is Skills.

Sources

Accessed on 2026-10-05.

  • Skills: reusable procedures for agentsTechnique

    A folder with instructions, and optionally scripts and references, that teaches the agent one specific kind of task. It is only loaded when needed.

    Published
  • Safe agent executionTechnique

    Why written rules are not enough to contain an agent, and which layers of the environment limit the damage even when the agent makes a mistake or someone tricks it.

    Published