# What is AGENTS.md?

> AGENTS.md is a plain Markdown file at the root of a repository that tells AI coding agents how to build, test and work in the project.

Source: https://www.honeyhive.ai/learn/agents-md (updated 2026-11-08)

AGENTS.md is a plain Markdown file that gives AI coding agents the project-specific instructions they need: how to build, how to test, what conventions to follow. The [official site](https://agents.md) puts it as "a README for agents." It has no required fields, so agents read whatever text you write.

It exists because a human README is the wrong place for detail like exact test commands or lint rules, and because each coding tool used to want its own file. AGENTS.md is one file that many tools read. It is a small piece of an [agent harness](/learn/agent-harness) and a simple form of [context engineering](/learn/context-engineering) for [agentic coding](/learn/agentic-coding).

## What goes in it

The format has no schema, so contents are up to you. The [site's examples](https://agents.md) cover setup commands (install, dev server, tests), code style, testing steps such as running lint before merging, and pull request title format. The same page says that if you list test commands, agents will try to run the relevant checks and fix failures before they finish. The site [links](https://agents.md) public examples such as openai/codex, apache/airflow and temporalio/sdk-java.

Because it is context and not enforcement, a rule in AGENTS.md is a request. Anthropic's docs [say](https://code.claude.com/docs/en/memory) Claude treats these files as context, not enforced configuration, and recommend a hook when an action must be blocked.

## Which file wins

| Situation | What happens |
|---|---|
| Several AGENTS.md files in a repo | The [spec](https://agents.md) says the closest one to the edited file wins |
| A user prompt contradicts the file | Explicit chat prompts [override everything](https://agents.md) |
| Codex, global and project files | Codex [concatenates](https://developers.openai.com/codex/guides/agents-md) files from the repository root down; files closer to the working directory come later and take precedence |
| Codex, `AGENTS.override.md` | Codex [checks](https://developers.openai.com/codex/guides/agents-md) it before AGENTS.md in each directory and in `~/.codex`, and uses at most one file per directory |
| Claude Code, AGENTS.md only | Claude [reads it](https://code.claude.com/docs/en/memory) by default, on v2.1.277 or later |
| Claude Code, AGENTS.md and CLAUDE.md | Claude reads only the CLAUDE.md files by default, unless the CLAUDE.md imports AGENTS.md |

## Size limits

Keep it short. Codex's `project_doc_max_bytes` [defaults](https://developers.openai.com/codex/guides/agents-md) to 32 KiB, and once combined content reaches that, Codex stops adding files. Anthropic [recommends](https://code.claude.com/docs/en/memory) under 200 lines per CLAUDE.md file because longer files use more context and reduce adherence. Both limits are about the same problem as [context rot](/learn/context-rot): more instructions are not always better ones.

Addy Osmani [writes](https://addyosmani.com/blog/agent-harness-engineering/) that every line in a good AGENTS.md should trace back to something that went wrong, which is a useful test for what to keep.

## Using it with other tools

The [official FAQ](https://agents.md) gives a migration path for an existing file: rename it and leave a symlink under the old name, for example `mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md`. For Aider, add `read: AGENTS.md` to `.aider.conf.yml`. For Gemini CLI, set the context file name to AGENTS.md in `.gemini/settings.json`.

For Claude Code, Anthropic [recommends](https://code.claude.com/docs/en/memory) a CLAUDE.md that starts with `@AGENTS.md`, followed by any Claude-specific instructions. A symlink also works if you have nothing Claude-specific to add.

The [official site](https://agents.md) lists many tools that read AGENTS.md, among them Codex, Cursor, GitHub Copilot's coding agent, Gemini CLI, Aider, Jules, Zed, Windsurf, JetBrains Junie and goose. Check each tool's docs for exact behavior, since as the table above shows, loading rules differ.

## Who maintains it

OpenAI [released](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation) AGENTS.md in August 2025. On December 9, 2025 the Linux Foundation [announced](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation) the Agentic AI Foundation, with AGENTS.md, Anthropic's [Model Context Protocol](/learn/model-context-protocol) and Block's goose as its three founding contributions. The release says more than 60,000 open source projects and agent frameworks had adopted it.

## Tracing what the agent actually follows

An instruction file only helps if the agent follows it. If you run your own coding agents, [traces](/learn/agent-tracing) show which files and commands a session used, and [error analysis](/learn/error-analysis-llm) of failed runs tells you which line to add to AGENTS.md next. HoneyHive's [docs](https://docs.honeyhive.ai) cover how to trace agent sessions.

## FAQ

### What is AGENTS.md?

It is a plain Markdown file that gives coding agents project-specific instructions. The [official site](https://agents.md) calls it a README for agents.

### Where does AGENTS.md go?

Usually the repository root. In a monorepo you can add one per subproject, and the [spec](https://agents.md) says the closest file to the edited file wins.

### Does Claude Code read AGENTS.md?

Yes, from v2.1.277, but by default only when there is no CLAUDE.md. Anthropic's [docs](https://code.claude.com/docs/en/memory) suggest putting `@AGENTS.md` in a CLAUDE.md to share one file.

### How long should AGENTS.md be?

The spec sets no limit, but tools do. Codex [stops reading](https://developers.openai.com/codex/guides/agents-md) at 32 KiB of combined instructions by default, and Claude Code's [docs](https://code.claude.com/docs/en/memory) target under 200 lines per CLAUDE.md file.

### Who maintains AGENTS.md?

The Agentic AI Foundation, part of the Linux Foundation. OpenAI [contributed](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation) it at the foundation's launch in December 2025.