AGENTS.md: The Complete Field Guide

What is AGENTS.md?

AGENTS.md is a Markdown file placed at the root of a repository that gives AI coding agents persistent instructions about the codebase, coding conventions, architecture decisions, and how to work within the project. It is the primary mechanism for encoding engineering judgment into the environment the agent operates inside.

The file is read by agents like OpenAI Codex, GitHub Copilot Workspace, and similar tools at the start of each session. Unlike a one-off prompt, it persists across every agent run — meaning any rule you write there is enforced on every line the agent produces, without repeating it each time.

Think of it as the onboarding document for a new engineer who never forgets, never shortcuts the conventions, and scales their work across every file in the codebase simultaneously.

Why it exists and where it came from

The term gained widespread traction in February 2026 when Ryan Lopopolo at OpenAI published a detailed account of building a production product entirely with AI agents — zero lines of application code written by hand. The AGENTS.md file was a central mechanism in what they called harness engineering: the discipline of building the environment the agent operates inside, rather than writing the code directly.

Thoughtworks Distinguished Engineer Birgitta Böckeler then analysed the experiment on Martin Fowler's blog, identifying the AGENTS.md as the entry point to a structured knowledge architecture — and noting the key failure mode: teams creating a single sprawling file that rots and stops being followed.

Before AGENTS.md was formalised, the same role was played by README sections titled "For AI assistants," .cursorrules files, system prompt preambles, and custom instructions in various tools. AGENTS.md is the converging convention.

What goes in AGENTS.md

The file should contain three categories of content:

The single-file problem

Context is a scarce resource. An agent has a finite context window, and every token spent on AGENTS.md is a token not spent on the actual code being changed. A 2,000-line AGENTS.md becomes noise — the agent effectively ignores instructions buried in the middle because they fall outside the attention window or are washed out by surrounding content.

The specific failure modes of a monolithic AGENTS.md:

• Staleness compounds silently. When the codebase evolves but the file doesn't, the agent follows outdated conventions. No one notices until a PR review catches a pattern you thought was prohibited.
• Rules conflict. Different engineers add sections over time without reading the existing content. The agent receives contradictory instructions and resolves them unpredictably.
• Specificity is lost. A rule like "use structured logging" is too vague to enforce consistently. A rule with an example, a counter-example, and a pointer to the logging module is actionable. Monolithic files trend toward vague.
• No ownership. Nobody reviews the AGENTS.md in PRs because it's treated as documentation, not as code that runs on every agent session.

The table-of-contents pattern

The solution the OpenAI harness engineering team landed on: treat AGENTS.md as an index, not a document. The file itself stays short — one to two pages — and its primary job is to tell the agent where to find the authoritative truth for any given domain.

# About this codebase
[2-3 sentence description]

# Tech stack
- Runtime: Node.js 22, TypeScript 5
- Framework: Next.js 15 (App Router)
- Database: Postgres via Drizzle ORM

# How to run
[minimal getting-started steps]

# Conventions (summary)
See docs/conventions/ for full rules.
Short version:
- Structured logging (see docs/conventions/logging.md)
- No file over 300 lines (see docs/conventions/file-size.md)
- All errors typed (see docs/conventions/errors.md)

# Architecture
See docs/architecture/ for ADRs.
Key decisions: docs/architecture/adr-001-database.md

# Testing
See docs/testing/strategy.md
Coverage target: 80% on business logic paths

# What to avoid
See docs/conventions/anti-patterns.md

The AGENTS.md never contains the full rules. It contains stable pointers to the files that do. When a convention changes, you update one targeted doc file — not hunt through a monolith.

What goes in the docs directory

The docs directory referenced from AGENTS.md is the actual harness. Each file should be narrow, owned, versioned, and written for a system reader — not a human skimming during onboarding.

Each doc file should open with a one-sentence rule statement, followed by examples, then counter-examples. Agents perform best when the rule is stated before the reasoning, not after.

What not to put in AGENTS.md

• Business context and product decisions. The agent doesn't need to know the company's mission or OKRs to write code consistently. That's noise.
• Full inline examples for every rule. Examples belong in the referenced docs files, not in the index. Inline examples in AGENTS.md inflate the token cost of every agent session.
• Aspirational rules not yet enforced. If a convention isn't actually applied to the existing codebase, telling the agent to follow it creates inconsistency. Only document what is true today, with a clear path to what will be true.
• Instructions that belong in CI. If a rule can be enforced by a linter or a CI check, it should be. Writing it in AGENTS.md without a mechanical backstop means it's enforced only when the agent happens to follow it.
• Vague preferences. "Write clean code" and "prefer simple solutions" are not rules. They take up tokens without giving the agent anything actionable to check against.

Keeping it fresh: the staleness problem

A stale AGENTS.md is worse than no AGENTS.md. The agent follows it confidently, producing code that matches outdated conventions — and the output looks correct on the surface because it follows the rules.

Three mechanisms that reduce staleness:

• Treat docs as code. Add docs/ changes to the PR review checklist. Any PR that changes a convention without updating the relevant doc file should fail review.
• Run a garbage collection agent. Schedule a weekly background agent run that reads AGENTS.md, scans the codebase for divergence from its rules, and opens targeted PRs. If the agent keeps flagging the same pattern as a violation, the convention may need updating, not the code.
• Version the AGENTS.md index. Add a "Last reviewed" date and an owner to each section. Sections not reviewed in 90 days should be flagged for audit. Stale sections are more likely to be wrong than fresh ones.

AGENTS.md vs CLAUDE.md vs .cursorrules

The practical answer for most teams: maintain one canonical docs/ directory with your conventions, then have each tool-specific file (AGENTS.md, CLAUDE.md, .cursorrules) point to it. You write the rules once; each agent reads them via whichever entry point it supports.

Frequently asked questions