What Is AGENTS.md? The AI Coding Instruction File Explained

Every AI coding tool has its own instruction file convention. Cursor uses .cursorrules. GitHub Copilot reads copilot-instructions.md. Claude Code looks for CLAUDE.md. OpenAI Codex and a growing number of agentic coding tools have settled on a different name: AGENTS.md. If you are using any agentic coding workflow in 2026, this is the file that determines whether the agent works correctly or keeps surprising you.

What AGENTS.md does

An AI coding agent entering your repository has no context. It does not know your team's naming conventions, which files are safe to modify, what your test runner expects, or why a particular architectural decision was made. AGENTS.md is how you give it that context before it starts.

When a tool like OpenAI Codex CLI picks up a task, it reads AGENTS.md first. The instructions in that file constrain what the agent does: where it can write, what commands it can run, how it should format output, and what it should ask before acting rather than assume. Without it, the agent guesses.

The file sits at the root of your repo. Some tools also support AGENTS.md files in subdirectories, where they override or extend the root-level instructions for that specific part of the codebase.

What to put in your AGENTS.md

Good AGENTS.md files are short and specific. The goal is not to write documentation for humans; it is to give an autonomous agent the minimum information it needs to behave correctly without supervision.

The most useful sections:

• Project overview: One or two sentences on what the project does and the tech stack. Keep it to the essentials: language, framework, major dependencies.
• Repository structure: Which directories the agent can and cannot touch. Explicitly list paths that are generated, vendor-managed, or off-limits.
• Test commands: The exact command the agent should run after making changes. If your CI uses a specific test runner or requires environment variables, say so.
• Coding conventions: Style rules not enforced by a linter but still important. Naming conventions, patterns to prefer or avoid, API boundaries the agent should respect.
• What to ask before doing: Actions that require human judgment. Migrations, schema changes, changes to public APIs, new external dependencies.

A minimal AGENTS.md example

# Project: Inventory API

## Stack
Node.js 22, Express, PostgreSQL 16. TypeScript throughout.

## Structure
- src/: application code (agent can modify)
- migrations/: SQL migrations (ask before creating new ones)
- dist/: generated, never modify directly

## Tests
Run `npm test` after any change. All tests must pass before committing.

## Conventions
- Use async/await, not callbacks or bare Promises
- Error handling: throw typed errors, catch at the route level
- No new dependencies without mentioning it in the PR description

## Ask before:
- Creating database migrations
- Changing any route signature
- Adding new environment variables

That is about 120 words. Longer files dilute the important instructions; agents, like humans, skim.

How AGENTS.md compares to similar files

Most AI coding tools support some version of a repo-level instruction file. GitHub Copilot reads copilot-instructions.md placed in the .github directory. Cursor agents read .cursorrules or a cursor-specific rules directory. Claude Code reads CLAUDE.md. Tools that sit on top of multiple models often read whichever file the underlying tool supports.

AGENTS.md is not controlled by a single vendor. It emerged as a convention in the agentic coding ecosystem and is now supported by OpenAI Codex, Gemini Code Assist, and most open-source agent frameworks. If you use multiple tools in the same repo, AGENTS.md is the safest choice for instructions you want every agent to see.

The case for writing one

Benchmark evaluations of AI coding agents, including SWE-Marathon's evaluation of agents at scale, consistently show that agents with well-structured repo context outperform those without it. The gap is not small. A well-written AGENTS.md can reduce back-and-forth correction cycles significantly because the agent enters with the constraints it needs rather than discovering them through mistakes.

StartupHub tracks more than 92,000 startups and the developer tooling they adopt. The fastest-growing tools in our 2026 index are agentic coding platforms, with Cursor, Windsurf, and the OpenAI Codex ecosystem each roughly doubling their startup adoption in the first half of the year. Every major agentic coding tool supports AGENTS.md or an equivalent. If you are not writing one, your codebase is being treated as context-free.

FAQ

Is AGENTS.md the same as CLAUDE.md?

No. CLAUDE.md is specific to Anthropic's Claude Code tool. AGENTS.md is a broader convention used by OpenAI Codex and other agentic coding platforms. Both serve the same purpose: giving an AI agent repo-level context before it starts working. If your team uses both Claude Code and Codex CLI, you may want both files.

Where should I put the AGENTS.md file?

At the root of your repository. Some tools also read AGENTS.md files in subdirectories, where they can override root-level instructions for a specific package or module. Start at the root, then add directory-level files if you need different rules in different parts of the codebase.

How long should my AGENTS.md be?

As short as possible while still being complete. Most effective AGENTS.md files are 100 to 300 words. Longer than that, and the important constraints get lost in the noise. If you find yourself writing a lot, break it into sections with clear headers so the agent can navigate to what is relevant.

Does AGENTS.md get committed to the repo?

Yes. Commit AGENTS.md to version control just like any other configuration file. This means all team members and all agents working in the repo see the same instructions. Update it whenever your conventions change, just as you would update a linter configuration.

Will every AI coding tool read AGENTS.md?

Not every tool supports it. GitHub Copilot uses copilot-instructions.md, Cursor uses .cursorrules, and Claude Code uses CLAUDE.md. Check your specific tool's documentation. Where AGENTS.md is supported, it is typically read before any other project context.