contenox

What is AGENTS.md? What to put in it, with an example

Updated

BASICS AGENTS.md explained

AGENTS.md is a plain Markdown file in your repository that tells AI coding agents how to work on your project: which commands install, build and test it, which conventions to follow, and what not to touch. Agents such as Codex, OpenCode, Cursor, GitHub Copilot and Claude Code read it at the start of a session, so you stop repeating the same instructions in every prompt. Think of it as a README for agents.

What it looks like

A short file that pays for itself:

# AGENTS.md

## Commands
- Install: `pnpm install`
- Test one file: `pnpm vitest run path/to/file.test.ts`
- Before finishing: `pnpm lint && pnpm test`

## Layout
- API handlers in `server/routes/`, shared types in `packages/types/`.

## Rules
- Use `date-fns` for dates, not `moment`.
- Do not edit anything under `generated/`. Run `pnpm codegen` instead.
- No new dependencies without asking.

Without it, the agent guesses npm test, runs the whole suite to check one file, and edits a generated file that gets overwritten on the next build. With it, the agent runs the right command the first time.

What should I put in AGENTS.md?

Only what the agent can’t work out by reading the code, and would get wrong:

  • Commands: install, build, test, lint, and how to run a single test. This is the most useful part, because a wrong guess costs a full agent turn.
  • Where things live: two or three lines, not a tour.
  • Rules it can’t see: which library to use for dates or HTTP, error-handling patterns, what not to import.
  • What not to touch: generated files, vendored code, commands not to run, such as migrations.
  • Done means: “lint and tests pass, no new warnings”.
  • Secrets: where they live and that the agent must not read or print them. See keep secrets away from AI agents.

Leave out:

  • Anything a linter or formatter already enforces.
  • Architecture essays. Link to them.
  • Things that change every week. The agent will follow the stale version.

How long should it be?

Short. The file is added to the model’s context in every session, and a longer file gives the model more to follow, not more to know. Claude Code’s docs suggest keeping its instruction files under 200 lines. Codex stops reading project instruction files once they add up to 32 KiB by default (the project_doc_max_bytes setting).

Add a line when an agent repeats a mistake. Delete a line when it no longer matters.

Should I let the agent write it?

Be careful. Claude Code’s /init and similar commands draft a file from your code, and that is a fine start, but cut it down by hand. A February 2026 study of several coding agents found that context files written by a model tended to lower task success, while files written by developers helped slightly. Both made agents explore more and cost more. The authors’ advice: describe only minimal requirements.

Does Claude Code read AGENTS.md?

Yes, in current versions, with one catch. Claude Code reads AGENTS.md when your project has no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above it. If you have one of those, it reads only the CLAUDE.md files.

To keep one shared file and still have a CLAUDE.md, put this line at the top of CLAUDE.md, with any Claude-only instructions below it:

@AGENTS.md

This also covers sessions where Claude Code can’t read AGENTS.md directly, which its docs describe for older versions and a few setups. A symlink from CLAUDE.md to AGENTS.md works too, but on Windows creating symlinks needs Developer Mode or administrator rights, so the import is simpler.

How do other tools read it?

  • Codex reads ~/.codex/AGENTS.md for your personal defaults, then one file per directory from the project root down to where you are. Files closer to your current directory come later and win. A file named AGENTS.override.md replaces AGENTS.md in its directory.

  • OpenCode reads AGENTS.md in the project root, and ~/.config/opencode/AGENTS.md for your personal rules. If a project has no AGENTS.md, it falls back to CLAUDE.md, so a Claude Code project works without changes.

  • Gemini CLI, which Google now keeps for Gemini Code Assist licenses, reads GEMINI.md by default. Add this to .gemini/settings.json:

    { "context": { "fileName": "AGENTS.md" } }

  • Aider needs read: AGENTS.md in .aider.conf.yml.

  • Cursor, VS Code, Zed, Jules, goose, Junie, Warp, Devin, Amp and many others are listed on agents.md as supporting it. Check a tool’s own docs if it seems to ignore the file.

Does it work in a monorepo?

Yes. Put shared rules at the root and package-specific commands next to each package:

AGENTS.md                  shared rules
apps/web/AGENTS.md         web build and test commands
services/billing/AGENTS.md billing rules

The agents.md FAQ says agents use the file nearest to the code being edited, so the closest one wins when rules conflict, and an instruction you type in chat overrides them all. Tools differ in the details: Codex combines the files from root to current directory, and Claude Code loads the files above your working directory at start and a subdirectory’s file when it opens a file there.

How do I know the agent read it?

Ask. Start a session and type “Summarize the instructions you were given for this project.” Codex’s docs suggest exactly this check. In Claude Code, an interactive session shows a line naming the AGENTS.md it loaded when there is no CLAUDE.md.

If the agent ignores a rule, the rule is usually too vague or buried. “Run make test” works better than “make sure tests pass”. “Do not edit generated/” works better than “we usually avoid generated files”.

What AGENTS.md can’t do

It is advice, not enforcement. The model can still ignore a line, especially late in a long session. If an action must never happen, such as pushing to main or reading .env, block it with your agent’s permission rules or hooks. See AI agent permissions.

Where AGENTS.md came from

AGENTS.md started in 2025 as a shared convention, so teams could stop keeping one instruction file per tool. In December 2025 OpenAI contributed it to the new Agentic AI Foundation under the Linux Foundation, alongside Anthropic’s MCP and Block’s goose. There is no required structure and no schema: it is just Markdown.

Related

Esc to close