AGENTS.md for Codex and AI Coding Agents: Examples, Best Practices & Claude Code Comparison

Aug 24, 2026

Problem

When I first added an AGENTS.md to a project, I wrote things like “Try to test your changes when possible” and “Write clean code.” The agents read the file, but they still skipped tests, edited generated files, and reported work as done before validation ever ran. One rule said “inspect state before acting” while another said “immediately perform the operation” — and in a Reddit discussion one developer described an agent looping on such conflicting instructions and burning through roughly $50 in API calls.

The real problem is that most AGENTS.md files are vague, generic, or contradictory. This post shows what to actually put inside, with a template you can copy into any repository.

Direct Answer

A useful AGENTS.md lives at the root of a repository and tells an AI coding agent, in plain operational language:

what the project is,
where the important code lives,
how to build and test it,
which conventions are mandatory,
what it must not change,
how to verify that its work is complete.

It is best kept short, specific, and testable. A small, well-structured file almost always beats a giant prompt. Here is a minimal example you can drop in right away:

# AGENTS.md

## Project

This is a Next.js application using TypeScript.

## Commands

Install dependencies:

npm install

Run development server:

npm run dev

Run tests:

npm test

Run lint:

npm run lint

## Rules

- Always run tests after modifying production code.
- Never edit generated files.
- Do not change public APIs without explicit approval.
- Follow the existing TypeScript style.

This works because it gives the agent exact commands and hard operational constraints instead of abstract advice, so the agent can verify its own work.

What Is AGENTS.md?

AGENTS.md is an open format designed as a dedicated, predictable place for context and instructions given to AI coding agents. It is a general project-instructions file for agents that support the convention, such as Codex, OpenCode, and similar coding agents. It complements README.md, which is written for human contributors.

Think of the difference this way:

README.md  -> for humans  -> overview, usage, screenshots
AGENTS.md  -> for agents  -> commands, rules, what NOT to touch

Supported coding agents load the applicable AGENTS.md instructions when working in the repository, giving them persistent project-level guidance across tasks. Note that different tools may handle discovery, precedence, and scope differently, so behavior can vary across agents. A well-scoped file reduces wasted API calls, prevents destructive edits, and makes agent output verifiable.

Two things worth noting up front:

The AGENTS.md convention is meant to work across many agent tools (Codex CLI, Cursor, OpenCode, and similar).
Claude Code natively uses CLAUDE.md. If your team works with both Codex and Claude Code, keep general rules in AGENTS.md, put Claude Code–specific rules in CLAUDE.md, and do not assume Claude Code reads AGENTS.md automatically.

What Should You Put in AGENTS.md?

Keep the sections operational. Here are the parts that matter most, with short examples.

Project Overview

Include only what an agent actually needs. A one-line summary plus the main modules is usually enough.

## Project Overview

This repository contains a Spring Boot REST API.

Main modules:

- api: HTTP controllers
- service: business logic
- repository: database access
- integration-tests: integration tests

The repository layout helps the agent find files faster and reuse existing patterns instead of guessing.

Build and Test Commands

Give exact, deterministic commands. “Build the project before committing” is useless to an agent; ./gradlew build is not.

## Commands

Build:

./gradlew build

Run unit tests:

./gradlew test

For npm projects:

npm install
npm run build
npm test
npm run lint
npm run typecheck

Deterministic commands let the agent verify its own work instead of guessing whether it succeeded.

Code Style and Conventions

State only the conventions the agent must follow, and prefer rules that tooling can enforce.

## Code Style

- Use TypeScript strict mode.
- Follow existing naming conventions.
- Prefer existing utilities over adding new dependencies.

Anything the linter or formatter can catch belongs in tooling, not in this file.

Files the Agent Must Not Modify

Protect the areas where mistakes are expensive.

## Do Not Modify

- generated/
- database/migrations already released to production
- vendor/

Definition of Done

This is the section agents need most. Without it, an agent may stop and call the task complete while tests are still failing.

## Before Finishing

Always:

1. Run unit tests.
2. Run the linter.
3. Run type checking.
4. Fix failures before reporting completion.

Connect this to a real failure mode: an interrupted or timed-out test should never be described as passing. If a test did not actually complete, the agent must say so.

AGENTS.md Example: A Complete Real-World File

Here is a complete but compact example for a TypeScript/Node.js project, around 60 lines rather than hundreds.

# AGENTS.md

## Project Overview

This is a Node.js REST API written in TypeScript, exposing a small set of JSON endpoints.

## Repository Layout

- src/routes: HTTP route handlers
- src/services: business logic
- src/lib: shared utilities
- tests: unit and integration tests

## Development Commands

Install:

npm install

Build:

npm run build

Run tests:

npm test

Run linter and type check:

npm run lint
npm run typecheck

## Code Style

- Use TypeScript strict mode.
- Follow the existing module structure.
- Prefer existing utilities over adding new dependencies.

## Dependencies

- Do not add a dependency unless one is required and no existing one fits.

## Files Not to Modify

- dist/
- generated/
- package-lock.json (regenerate via npm install)

## Git / PR Rules

- Keep PRs focused on a single change.
- Add a short summary of what changed and why.
- Run the full test, lint, and typecheck suite before opening a PR.

## Definition of Done

Before finishing any task:

1. Run npm test, npm run lint, and npm run typecheck.
2. Fix all failures.
3. Summarize which files changed.
4. Report any tests that could not be run.

After the example, note that you do not need a comment for every line. Keep the rules readable and let the sections speak for themselves.

Using Nested AGENTS.md Files

For tools that support directory-level AGENTS.md files, such as Codex, you can set more specific rules per directory instead of cramming everything into one root file:

repo/
├── AGENTS.md
├── backend/
│   └── AGENTS.md
└── frontend/
    └── AGENTS.md

The root AGENTS.md holds repository-wide rules.
A subdirectory AGENTS.md holds rules specific to that module.
Rules in a more specific directory generally take precedence over higher-level rules.
This is easier to maintain than stuffing every rule into one huge root AGENTS.md.

Here is a short example:

# /AGENTS.md

- Run tests before finishing.
- Do not change public APIs.

# /frontend/AGENTS.md

- Follow existing React component patterns.
- Run `npm run lint` after frontend changes.

Bad AGENTS.md vs Good AGENTS.md

Vague preferences cause agents to guess. Specific operational rules do not.

Example 1 — testing

Try to test your changes when possible.

Always run `npm test` after modifying production code.
Do not report the task complete if tests fail.

Example 2 — code structure

Write clean code.

Follow the existing module structure.
Do not introduce a new abstraction unless at least two existing call sites require it.

Specific rules win because they tell the agent exactly what to run and what “done” means. “Clean code” is subjective; “follow the existing module structure” is checkable.

Should You Use MUST, ALWAYS and NEVER?

In one analysis of popular GitHub repositories, about 90% of root AGENTS.md files used hard constraint language like must, always, and never. The discussion reported that as descriptive data rather than a universal rule. Strong language makes sense when the constraint is a safety boundary.

Use strong language for:

safety constraints,
required validation,
protected files,
mandatory tooling,
irreversible operations.

Avoid strong language for subjective preferences. NEVER create a new utility is too rigid if a legit exception exists, whereas:

Prefer existing utilities.

leaves room for judgment.

Do Not Turn AGENTS.md Into a Giant List of Prohibitions

Here is the key principle:

If a rule can be enforced deterministically by tooling, prefer tooling.

Instead of writing many never rules, run the actual checks:

- Never leave unused imports.
- Never use incorrect formatting.
- Never introduce lint errors.
- Never violate TypeScript type checks.

## Validation

After changing code, run:

npm run lint
npm run typecheck
npm test

Fix all failures before finishing.

Linters, type checkers, formatters, tests, and CI provide deterministic checks that are more reliable than expressing the same constraints only in natural-language instructions. They cannot be skipped or misinterpreted, and they do not consume agent context. Treat AGENTS.md as an operational map, not as the encyclopedia of your codebase.

Avoid Contradictory Rules

Contradictions happen when rules accumulate with no cleanup. One rule might say “always inspect state before taking action,” while another says “immediately perform the requested operation.” The agent cannot satisfy both and may loop or waste budget.

Techniques to stay consistent:

reduce duplicate rules,
keep one authoritative instruction per topic,
set priorities when rules overlap,
remove obsolete instructions,
periodically refactor AGENTS.md,
prefer fewer clear rules over an append-only history of past mistakes.

The main takeaway here:

AGENTS.md should evolve, but it should not become an append-only log of every mistake an agent has ever made.

How Long Should AGENTS.md Be?

There is no single ideal length. Shorter is generally easier to maintain, but completeness matters.

Guidelines:

keep the root file focused on repository-wide rules,
move specialized instructions closer to the relevant modules where supported,
avoid duplicating README documentation,
avoid long architectural essays,
keep examples only when they prevent recurring mistakes.

In one analysis of popular GitHub repositories, the discussion reported a median around 1,100 words in the studied sample. Treat that as descriptive data, not a target to hit.

AGENTS.md vs CLAUDE.md

File	Main purpose	Typical scope	Tool specificity
AGENTS.md	General repository instructions for AI agents	Root of the repo, cross-tool	Generic convention shared by many tools
CLAUDE.md	Instructions read specifically by Claude Code	Project root (or nested, tool-specific)	Tied to Claude Code

AGENTS.md is the more general convention; CLAUDE.md is specific to Claude Code. Many teams keep shared rules in one canonical file and put tool-specific instructions in a separate file. Claude Code natively uses CLAUDE.md; if you also use Codex, keep general rules in AGENTS.md and Claude Code–specific rules in CLAUDE.md, rather than expecting Claude Code to auto-read AGENTS.md. Avoid claiming that every tool parses both files identically — behavior does differ across agents.

AGENTS.md for Codex CLI

A short Codex-specific section keeps the workflow explicit:

## Codex Workflow

Before modifying code:

1. Inspect relevant files.
2. Reuse existing project patterns.

After modifying code:

1. Run targeted tests.
2. Run lint/type checking.
3. Summarize changed files.
4. Report any tests that could not be executed.

The rule to remember: never claim tests passed unless they actually completed.

AGENTS.md for Claude Code

A common pattern when a team uses both Codex and Claude Code:

put general, cross-tool rules in AGENTS.md,
put Claude Code–specific behavior in CLAUDE.md.

Claude Code natively uses CLAUDE.md; keep general rules in AGENTS.md for the agents that support it, and reserve CLAUDE.md for Claude Code–specific behavior. Keep the two in sync and avoid duplicating the same rule in both, since duplicates are a common source of contradictions.

Common AGENTS.md Mistakes

Here are the mistakes I see most often, with short fixes:

Vague instructions → use exact commands and concrete rules.
Hundreds of don't rules → move lintable rules into tooling and CI.
Duplicating README content → keep only agent-operational info.
Contradictory instructions → keep one authoritative rule and remove obsolete ones.
Missing exact build/test commands → always include deterministic commands (npm, Gradle, Maven, pytest).
Putting lintable rules in prompt text → enforce via linters and CI.
No Definition of Done → add a “Before Finishing” section.
Keeping outdated rules forever → refactor periodically; do not make it an append-only mistake log.
Assuming every tool reads it identically → separate general AGENTS.md, CLAUDE.md, and user/global config.
Granting dangerous permissions without safeguards → restrict what agents may change and add safe validation steps.

Copy-Paste AGENTS.md Starter Template

The section above gives a complete real-world example; this template is a blank starting point you can copy and fill in with your own placeholders:

# AGENTS.md

## Project Overview

[What this repository does]

## Repository Layout

- src/...
- tests/...

## Development Commands

Install:

npm install

Build:

npm run build

Test:

npm test

## Coding Rules

- ...
- ...

## Do Not Modify

- ...

## Validation

Before completing a task:

1. ...
2. ...
3. ...

## Git / PR Rules

- ...

Summary

In this post, I showed how to write a practical AGENTS.md for AI coding agents. The key point is that a concise file with exact commands, mandatory conventions, protected files, and a Definition of Done saves API budget, prevents destructive edits, and makes agent output verifiable. Copy the template, adapt it to your repository in about 10 minutes, and iterate as you learn.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 AGENTS.md - Open Format Specification
👨‍💻 Claude Code Documentation

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!