How to Write an AGENTS.md File That Actually Works

60,000 open-source repositories now ship an AGENTS.md file, and 28+ tools read it natively Yet the most rigorous research we have shows that most of these files make agents slower, more expensive, and slightly less likely to succeed. That’s not a niche opinion—it’s the finding of a 2026 ETH Zurich study that tested context files across real-world repositories with multiple agents and models. The problem isn’t the format. It’s how we’re writing it.

This post is about writing an AGENTS.md file that avoids the traps the research identified. The format is simple: plain Markdown, no required fields, no YAML frontmatter in the base spec. The hard part is the editorial discipline.

What AGENTS.md Actually Is (And Isn’t)

AGENTS.md is a simple, open format for guiding coding agents, described as a “README for agents”. Plain markdown with no required fields or sections. The base spec mandates exactly that: plain markdown only, no schema, no @-import syntax. It’s designed to be the cross-tool standard—one file that Codex, Copilot, Cursor, and others can all read, rather than maintaining separate .cursorrules, CLAUDE.md, and .github/copilot-instructions.md files for every tool.

Here’s where it lives: at the root of your repository, with nested files in monorepo subdirectories. The nearest file to whatever the agent is editing takes precedence. OpenAI’s own Codex repository uses 88 AGENTS.md files across its directory tree, concatenating from root downward.

The format’s deliberate minimalism is its whole point. But that same minimalism creates pressure to expand it—which is where things go wrong.

The Research That Should Change How You Write

Let’s get specific about what the ETH Zurich study found, because it’s counterintuitive and important.

LLM-generated context files reduced task success rates while increasing inference costs by over 20%. Not improved—degraded. The agents followed the instructions faithfully, but the extra constraints broadened their exploration without improving outcomes. More steps, longer reasoning, worse results.

Human-written files did better, but not dramatically: a marginal +4% success rate improvement, at a cost of up to 19% more inference spend. The researchers’ conclusion was unambiguous—unnecessary requirements in context files actively harm performance.

This creates what I’d call the Context Inflation Dynamic: the more successfully AGENTS.md standardizes across the ecosystem, the more pressure builds to expand its scope with features and structure. But every addition risks recreating the bloat the format was designed to eliminate.

What to Include (And What to Leave Out)

The ASDLC guide puts it well: if a constraint can be enforced by tooling—linters, formatters, type checkers, CI gates—it must not be restated in AGENTS.md. The tool is the constraint. Restating it creates maintenance debt and dilutes signal.

A minimal AGENTS.md should include your project stack, conventions that differ from defaults, and pre-commit checks. The recommended sections break down as: project overview, build/test commands with exact flags, code style (only deviations from standard), testing instructions, security boundaries, and commit/PR guidelines.

The critical filter: would a new senior hire need to be told this in their first week? If it’s inferable from the codebase or enforced by existing tooling, it doesn’t belong.

Here’s a pattern I use. For each item you consider adding, ask: will the agent fail without this? Not “would it be nice if the agent knew”—will it actually produce wrong output? If no, cut it.

The Pink Elephant Problem

There’s a subtler trap than bloat: the “Pink Elephant Problem” of context anchoring. Explicit negative constraints—“do not use tRPC,” “never modify files in /legacy/“—can activate the forbidden concept in the agent’s attention mechanism. The token tRPC becomes highly active, and the agent may reach for it precisely because you’ve named it.

This isn’t speculative. The ASDLC guide treats it as a known failure mode. The practical implication: frame constraints positively where possible. Instead of “do not use tRPC,” prefer “use GraphQL for all API calls, see existing patterns in src/api/.” Give the agent something to do, not something to avoid.

Tool-Specific Files: The Layered Approach

AGENTS.md is complementary to tool-specific instruction files like CLAUDE.md and .cursor/rules. The pattern that works: shared, stable project context in AGENTS.md, tool-specific behavior in the vendor file.

This is where the layered configuration model becomes valuable. AGENTS.md carries what every agent needs to know. CLAUDE.md carries Claude-specific session patterns. .cursor/rules carries Cursor-specific UI conventions. Duplication between them is a bug, not a feature—when they conflict, you get unpredictable behavior and inflated token costs.

For teams running multiple tools, this layering isn’t optional. It’s the only way to maintain consistency without maintenance hell.

The Feature Creep Warning

The base spec’s minimalism is already under pressure. Issue #167 introduced YAML frontmatter for lifecycle commands—bootstrap, post-chat—and builtin commands like read and run. Issue #179 proposes a standardized rule format for .agents/rules/ with optional YAML frontmatter and path-scoping fields.

These aren’t bad ideas in isolation. But they move AGENTS.md from “sparse constraint list” toward “full configuration system”—exactly the fragmentation and complexity the standard was designed to prevent. OpenAI’s Codex already imposes a 32 KiB default size cap on the file body. That cap exists for a reason.

My view: resist the expansion. The format’s strength is that any tool can read it with zero parsing overhead. Every structured extension erodes that advantage for marginal gain.

A Practical Starting Point

If you’re writing your first AGENTS.md, start with this structure—adapted from the minimal template guidance and the GitHub engineering analysis:

# AGENTS.md

## Stack
- Next.js 15 (App Router), TypeScript strict
- Database: Postgres via Prisma
- Auth: NextAuth.js v5

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Test: `pnpm test --run`
- Lint: `pnpm lint` (Biome — see `biome.json`)

## Conventions
- Named exports only
- API routes in `/app/api/`
- Zod for all input validation

## Boundaries
- `/legacy/` is frozen — do not modify
- Run tests before committing

Notice what’s absent: no style rules Biome enforces, no architectural essays, no negative constraints framed as “do not.” The GitHub analysis of 2,500+ repositories found that effective files prioritize copy-pasteable commands over vague tool names, real code snippets over descriptive prose, and explicit boundaries over implicit assumptions. This follows that pattern.

Where This Fits in Your Workflow

For teams already maintaining CLAUDE.md or .cursor/rules, the question isn’t whether to adopt AGENTS.md—it’s how to avoid duplicating effort. The cross-tool compatibility post covers adoption patterns in more detail, but the short version: AGENTS.md becomes your source of truth for project context, with tool-specific files bolting on tool-specific behavior.

If you’re evaluating whether your current context files are helping or hurting, the real-world examples post walks through cost tradeoffs and adoption patterns for human-curated files—when they’re done right.

The Bottom Line

AGENTS.md is standardizing faster than any previous AI coding tool convention, and that’s mostly good. But standardization without discipline produces the same bloat that made vendor-specific formats painful. The research is clear: smaller, constraint-focused files outperform comprehensive ones. The 32 KiB cap isn’t a limitation to engineer around—it’s a design constraint that protects you from yourself.

Write less than you think you need. Let your tooling enforce what it can. And treat every proposed extension to the format with the skepticism it deserves.