AGENTS.md Guide: Format, Examples & Coding Agent Support

AGENTS.md is a Markdown file that stores repository instructions for AI coding agents. Teams use it for commands, code conventions, directory rules, validation steps, and other project details an agent should know before it changes code.

It can be useful when your project keeps requiring instructions such as “use pnpm,” “run this test suite,” “leave generated files alone,” or “follow this local architecture rule.” Putting those rules in AGENTS.md keeps them with your repository and lets compatible coding agents load them as project context.

You can start with a short root file that records only the commands, conventions, and boundaries your coding agent needs. If different packages or services use different workflows, nested AGENTS.md files can hold those local rules closer to the code they affect.

What Is AGENTS.md?

If your repository already has a README, think of AGENTS.md as its companion file for coding agents. README.md introduces the project to people. AGENTS.md stores the operational instructions an agent needs before it edits, tests, or reviews code.

Your repository can contain decisions that source code does not explain on its own. You can have several test commands, generated files that require a generator, package-specific validation rules, or an internal convention that differs from the framework default.

A minimal file makes the idea concrete. Four lines can tell your agent how to validate a change, which directory to leave alone, and when the task is ready to finish:

# Project instructions
- Run `npm test` after changing application code.
- Do not edit files under `src/generated/`.
- Update tests when behavior changes.
- Finish after the relevant tests pass.

How AGENTS.md Works

AGENTS.md contains text instructions. The coding agent handles discovery, decides which file applies to the current task, and places the selected instructions in the model context.

The instructions shape how the agent plans, edits, runs commands, and reports results. Permissions, sandbox rules, hooks, CI, and repository protections govern access and enforce checks that must pass before a change is accepted.

At a high level, agents that recognize AGENTS.md follow this pattern:

1. The coding agent searches the repository locations it knows.
2. It selects the AGENTS.md instructions that apply to the current work.
3. Those instructions become part of the task or session context.
4. The agent uses that context while it plans, edits, runs commands, and reports the result.

What to Put in AGENTS.md

Write the information that changes how your coding agent should work in the repository. Exact commands and concrete project rules are more useful than generic software advice. When a policy already has a maintained source of truth, link to that document and keep the operational instruction in AGENTS.md concise.

Useful Instructions

Good entries answer the questions an agent faces while making a change:

• Exact install, build, test, lint, formatting, and type-check commands.
• Focused validation commands for a package, service, or test suite.
• Important source, test, documentation, migration, and generated-file locations.
• Project-specific naming, API, error-handling, architecture, and test conventions.
• Files or directories the agent should leave untouched by hand.
• Actions that require approval, such as adding a production dependency.
• Pull-request, changelog, migration, or documentation requirements.
• A concrete definition of done for repository changes.

What to Leave Out

Keep the file focused on project instructions that affect coding work. Security controls and deterministic checks belong in systems that can enforce them:

• Passwords, API keys, tokens, credentials, or private operational details.
• A copy of the entire README, contribution guide, or architecture manual.
• Generic advice such as “write clean code” or “follow best practices.”
• Commands that have not been checked against the current repository.
• Large inventories available from package files or the directory tree.
• Formatting rules already enforced by a formatter or linter.
• Security requirements that require permissions, hooks, CI, or repository policy.

A Complete AGENTS.md Example

For a small TypeScript application, a complete file can look like this. It includes enough context to locate the code, run the right checks, follow local conventions, and know when the task is finished. Replace every command and directory with facts from your own repository before using it.

# Project instructions
This repository contains a TypeScript web application.
Application code is in `src/`, and browser tests are in `tests/e2e/`.
## Commands
- Install dependencies with `npm ci`.
- Start the development server with `npm run dev`.
- Run unit tests with `npm test`.
- Run type checks with `npm run typecheck`.
- Run browser tests with `npm run test:e2e` when a user flow changes.
## Conventions
- Use named exports for modules under `src/features/`.
- Add tests for changed behavior.
- Keep public error messages free of internal service details.
- Use the existing API client in `src/lib/api.ts` for HTTP requests.
## Boundaries
- Do not edit files in `src/generated/`. Run `npm run generate`.
- Ask before adding a production dependency.
- Keep unrelated refactors out of the change.
## Definition of done
- The relevant tests pass.
- Type checking passes.
- User-visible behavior changes include documentation when needed.

AGENTS.md Format Reference

For portability, use the filename AGENTS.md. The format is standard Markdown, with no required schema, frontmatter, heading names, or section order. A small repository can use a few bullets, and a larger codebase can organize instructions under several headings.

Root and Nested AGENTS.md Files

Start with one AGENTS.md in your repository root for project-wide instructions. Add a nested file when a package, service, or directory has different commands or local rules. Keeping shared guidance in the root reduces duplication and makes local files easier to maintain.

For example, your root file can contain repository-wide rules while services/payments/AGENTS.md holds instructions for the payment service:

storefront/
├── AGENTS.md
├── apps/
│   └── web/
│       └── src/
└── services/
    └── payments/
        ├── AGENTS.md
        └── src/

How Precedence Works

The AGENTS.md convention places local instructions close to the code they affect. Coding agents use their own discovery logic, which becomes important when a repository relies on nested files or local overrides.

• Put repository-wide commands and conventions in the root AGENTS.md.
• Put directory-specific instructions in a nested AGENTS.md when that area has different requirements.
• Avoid conflicting wording when several coding agents work in one repository.

Which Coding Agents Recognize AGENTS.md?

Coding agents handle AGENTS.md in several ways. Codex, Cursor, and several other agents recognize the file as repository instructions. Gemini CLI can load it through configuration. Claude Code uses CLAUDE.md for project instructions and can import a shared AGENTS.md.

AGENTS.md vs README.md, CLAUDE.md, and GEMINI.md

These files can contain related information, and each one has a distinct job. Keeping shared coding-agent rules in one place reduces duplication, while product-native files handle instructions tied to a specific coding agent.

Using AGENTS.md with Claude Code

Claude Code uses CLAUDE.md for project instructions. A repository that already keeps shared rules in AGENTS.md can import that file from CLAUDE.md, then place Claude-specific instructions underneath.

A project that needs one Claude-specific rule can keep the file this small:

@AGENTS.md
## Claude Code
- Use plan mode before changes under `src/billing/`.

Real AGENTS.md Examples

If you want to see how mature projects use AGENTS.md, these repositories show three different levels of detail:

• OpenAI Codex AGENTS.md contains Rust conventions, testing requirements, review rules, API constraints, and change-size guidance for a large coding-agent codebase.
• Apache Airflow AGENTS.md contains naming rules, environment setup, validation, architecture boundaries, and contributor safeguards for a mature monorepo.
• Temporal Java SDK AGENTS.md contains module locations, Java compatibility, Gradle commands, tests, pull-request questions, and a review checklist in a more compact file.

Common AGENTS.md Mistakes

Your AGENTS.md becomes less useful when instructions are vague, duplicated, stale, or impossible to enforce. These are the mistakes worth checking first:

• Writing rules such as “follow best practices” without naming the expected command or convention.
• Copying the whole README or contribution guide into AGENTS.md.
• Listing commands without saying where or when they should run.
• Repeating root instructions in every nested file.
• Putting secrets or private operational data in a file committed to the repository.
• Using natural-language instructions for security requirements that belong in permissions, hooks, CI, or repository policy.
• Leaving old commands or directory names in place after the repository changes.
• Assuming every coding agent discovers nested files or resolves conflicts in one uniform way.

How to Create Your First AGENTS.md

Start with one short root file and write down the instructions you keep repeating to coding agents or the project facts they tend to get wrong. A useful first version does not need to describe the whole repository. It needs enough context to improve the next task without becoming another maintenance-heavy handbook.

1. Check the README, package files, contribution guide, and CI configuration for the canonical setup and validation commands.
2. Create AGENTS.md in the repository root.
3. Add the exact build, test, lint, type-check, or formatting commands the agent should use.
4. Add a few non-obvious repository conventions, generated-file boundaries, and approval requirements.
5. Define what must be true before the agent reports that a change is complete.
6. Run a small coding task and inspect which commands, files, and tests the agent chooses.
7. Update AGENTS.md when the agent repeats a preventable mistake or when the repository workflow changes.
8. Keep rules that require guaranteed enforcement in CI, hooks, permissions, or repository protections.

Related AGENTS.md and AI Coding Resources

• AGENTS.md explains the shared format, examples, nested files, and current ecosystem.
• Codex AGENTS.md Guide explains how Codex discovers project instructions and handles directory scope.
• Claude Code Memory explains CLAUDE.md, imports, and project instruction discovery.
• CLI AI Coding Agents compares terminal coding agents including Codex, Claude Code, OpenCode, Copilot CLI, and other options.
• Agent Skills Specification See SKILL.md Format, Fields, and Directory Structure.
• AI Coding Agent Resources collects coding agents and projects available on ScriptByAI.
• Mistral Vibe is a CLI coding agent that loads local project instructions from AGENTS.md.

Keep AGENTS.md Small, Specific, and Current

A useful AGENTS.md should reflect the repository you have now, not the project as it looked several months ago. Start with the commands and rules that prevent recurring mistakes, then revise the file when the build process, directory structure, or team conventions change.

Treat each addition as a maintenance commitment. If a rule no longer affects coding work, remove it. When an avoidable mistake keeps returning during review, add the missing instruction and make the next agent task easier to verify.