Write an AGENTS.md That Actually Steers Claude Code and Codex

You ask Claude Code or Codex to add a feature. It works — but it skipped your tests, used a different formatter, hard-coded a value you keep in an env var, and named things the way it likes. You fix it, ask again, and it happens again.

The agent isn’t being difficult. It has no map of your repo. AGENTS.md is that map — a plain Markdown file that tells coding agents how your project works, read automatically by the major tools. This guide covers what it is, the five sections that actually change behavior, and a starter file you can copy and lint today.

Prerequisites

• A repo you’re working in with Claude Code or Codex.
• Five minutes. AGENTS.md is just Markdown — there’s nothing to install.

What AGENTS.md is (and isn’t)

AGENTS.md is an open, standardized convention — think of it as “a README for agents”: a predictable place to put context and instructions. Two facts make it easy to adopt:

• There’s no required schema. As the spec puts it, “AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide.” You can’t get the “format” wrong.
• It’s widely read. As of 2026-08, the spec reports 60,000+ projects using it and 20+ agents supporting it — including Claude, Codex, Cursor, Jules, Aider, and GitHub Copilot. One file, many tools.

It complements your README rather than replacing it: the README stays aimed at human contributors; AGENTS.md carries the implementation-level detail an agent needs (how to build, test, and not break things).

The five sections that change behavior

A long, aspirational AGENTS.md (“write clean code, be thoughtful”) does nothing. A short, concrete one changes what the agent does. Cover these five:

1. Setup & commands — how to install, run, and especially test. If the agent knows npm test must pass, it will run it.
2. Testing instructions — state the rule plainly: add/update a test for every change; never finish with tests failing. This is the single highest-leverage line.
3. Code style — language/versions, formatter, and “match the file you’re editing.”
4. Security & data — the non-negotiables: no secrets in the repo, tenant-scoped queries, validate input server-side. Agents will otherwise cheerfully inline a key.
5. PR / done conventions — commit style, and your definition of done — including that an author doesn’t approve its own change (a human or a second agent reviews).

The recommended areas in the spec are broader (project overview, deployment, and more), but these five are where behavior actually moves.

A starter you can copy

Here’s a short, real one for a Next.js + Supabase app. The full file is in the example directory, alongside a linter.

# Example Project — Agent Instructions

## Setup & commands
- Install: `npm install`  ·  Dev: `npm run dev`
- Test: `npm test` (must pass before any PR)  ·  Lint: `npm run lint`

## Testing instructions
- Add/update a test for every behavior change. Keep the critical path covered.
  Never mark a change done with tests failing.

## Code style
- TypeScript strict. No `any` without a comment. Match the file you're editing.

## Security & data (do not skip)
- Never commit secrets; use `.env`. Every DB query is tenant-scoped.
- Validate input on the server; parameterize all queries.

## Definition of done
Tests green, lint clean, no secrets, docs updated. A second reviewer approves —
an author does not approve its own change.

Notice it’s short. That’s deliberate — see the next section.

How the agent actually reads it

AGENTS.md isn’t magic; each tool loads it a specific way. Codex, for example, reads AGENTS.md by walking up from the working directory and includes a limited amount of that guidance in its first turn. Two consequences:

• Keep it loadable. Codex bounds how much it reads with a setting (project_doc_max_bytes). A 4,000-line manifesto gets truncated; a tight file gets read in full. Short and high-signal beats long and complete.
• Put detail behind links. State the rule in AGENTS.md; link to a longer doc for the procedure. (This site’s own AGENTS.md does exactly that.)

Monorepos: closest file wins

In a monorepo you can place nested AGENTS.md files in subprojects. The rule: the closest AGENTS.md to the file being edited takes precedence, falling back to the root. So a root file carries shared conventions, and packages/api/AGENTS.md can add API-specific ones without repeating everything.

Lint it

Because there’s no schema, it’s easy to write one that looks fine but omits the sections that matter. The example ships a tiny linter that flags missing areas:

bash verify.sh

Output:

AGENTS.md linter checks passed.
✓ AGENTS.md covers the recommended areas

It’s not a spec check (there is no spec to fail) — just a nudge to keep the file covering setup, tests, style, security, and done/review, and to keep it short enough to load.

Limitations & failure cases

• AGENTS.md guides behavior; it doesn’t enforce it. Back the important rules with CI (tests that block merges), so “run the tests” isn’t only a polite request.
• Tools differ in exactly how much they load and when. The convention is shared; the ingestion details are per-tool — check your agent’s docs for byte limits and precedence specifics.
• It can drift. Treat AGENTS.md like code: update it when conventions change.

Next step

An AGENTS.md is the first file in a production-minded repo — but not the last. The Production-Ready AI Builder Kit ships AGENTS.md and CLAUDE.md starters plus the implementation, review, and security-review prompts that turn “the agent wrote it” into “the agent shipped it safely.”