What Is AGENTS.md and How to Write Your Own in 30 Minutes

Practical materials on vibe coding and working with agents: Ailoot documentation.

AGENTS.md in One Paragraph#

Below, the format is considered using agents.md, the OpenAI Codex documentation, JetBrains Junie, Cursor Rules Docs, the GitHub Copilot Coding Agent changelog, and the Linux Foundation press release about the Agentic AI Foundation. All figures and features are current as of May 30, 2026, and AGENTS.md support in Claude Code is described according to Anthropic documentation, with an update from September 24, 2026.

If you have no idea what this zoo of tools on the market is or why they need a shared file, first read the guide “What to Code With in 2026: 8 AI Tools from Claude Code to Antigravity”. This article focuses specifically on the AGENTS.md format and how to write your own in 30 minutes.

What Is AGENTS.md and Where Did It Come From?#

Previously, every AI tool had its own rules file: Anthropic had CLAUDE.md, Cursor had .cursorrules, GitHub had .github/copilot-instructions.md, Aider had .aider.conf.yml, and JetBrains had .junie/guidelines.md. If your team had three different agents, that meant three parallel files with the same content that would diverge within a week.

OpenAI was the first to get tired of this. In August 2025, it released Codex CLI and simultaneously launched agents.md as an open format. From the site:

“Think of AGENTS.md as a README for agents.”

(agents.md, translated from English)

The main point is that AGENTS.md supplements README. README is written for people: “what the project is, how to run it locally, how to contribute.” AGENTS.md is written for the agent: exact shell commands, verifiable “done” criteria, and boundaries such as “never touch this.”

From the site:

“AGENTS.md supplements README: it holds additional, sometimes detailed context that the agent needs—build steps, tests, and conventions that would clutter README or simply aren’t needed by human contributors.”

(agents.md, translated from English)

By September 2025, GitHub Copilot Coding Agent supported the format (changelog, 28.08.2025). By December, Cursor, Junie, Gemini CLI, Aider, and another dozen tools had joined. On December 9, 2025, the Linux Foundation formed the Agentic AI Foundation (AAIF): its three founding projects were AGENTS.md from OpenAI, MCP from Anthropic, and goose from Block. The founding members were AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft, and OpenAI. By February 24, 2026, the foundation already included 146 organizations, including Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, UiPath, and Hitachi.

From that point on, AGENTS.md stopped being “yet another thing from OpenAI” and became a de facto standard.

Which AI Agents Read AGENTS.md, and Which Don’t?#

Support table as of May 30, 2026; the Claude Code row was updated on September 24, 2026:

Anthropic was the last of the major players to join. In August 2025, issue #6235 requesting AGENTS.md support was opened in the official anthropics/claude-code repository.

The issue stayed open for almost a year and was closed on August 17, 2026; version 2.1.277 with AGENTS.md support came out on September 18. Anthropic’s logic is as follows: CLAUDE.md takes precedence, and AGENTS.md is read when there is no CLAUDE.md in the working folder or any parent folder. According to the documentation, it works like this:

The catch: a personal CLAUDE.local.md also counts, and with it Claude Code stops reading AGENTS.md. You can change this behavior in /config, under Project instructions—for example, to make Claude Code read both files at once. In versions older than 2.1.277, AGENTS.md will not be picked up automatically; the line @AGENTS.md in CLAUDE.md is still the workaround.

How Is AGENTS.md Different from CLAUDE.md and .cursorrules?#

Comparison of four formats as of May 30, 2026:

The key idea: AGENTS.md can hold shared project instructions, while each client’s loading path and personal settings still need separate configuration. Claude Code has CLAUDE.local.md for that, and Cursor has local .mdc files under user. AGENTS.md alone doesn’t provide that—you need either to combine it with other files or agree as a team to write personal rules in gitignored sections.

Another important detail is monorepos. Codex and Cursor implement the rule “the nearest AGENTS.md wins”:

“In a monorepo, put a separate AGENTS.md inside each package. Agents automatically read the nearest file in the directory tree, and the nearest one wins.”

(agents.md, translated from English)

agents.md mentions that OpenAI’s main monorepo contains 88 AGENTS.md files for different subpackages. If you work in a monorepo, distribute the rules across levels: general rules at the root, specific ones in subfolders.

What Should a Good AGENTS.md Contain?#

The agents.md site offers a flexible format—“any Markdown.” But 80% of good files in the wild contain the same eight sections. The main rule: every item should be an exact command or a concrete example. An abstract idea like “write clean code” will be ignored by the agent.

1. Project overview — 2–3 lines. What the project is, who it is for, and its main goal. No marketing. Example: “Telegram bot for onboarding into a paid workshop. Stack: Next.js 14, Prisma, PostgreSQL. Triggered by a new record in purchases.”
2. Setup commands — exact shell commands to run locally. npm install, npm run dev, npm run build. No “this is usually how we do it.”
3. Code style / conventions — specific rules with an example, not “write cleanly.” For example: “TypeScript strict, single quotes, no default exports, component names in PascalCase, hooks start with use.”
4. Dev environment tips — where important things live. Which variables are needed in .env, where secrets are stored, which ports are in use, and how to work with the local DB.
5. Testing instructions — how to run a specific test and what counts as “green.” For example: npm test -- --testPathPattern=user-auth; 100% pass is expected.
6. PR / commit guidelines — commit message format, pre-PR checklist (tests, linter, documentation), and who approves.
7. Security considerations — what must never happen. “Never commit .env. Secrets belong only in Vault. Don’t show users’ personal data in logs.”
8. Boundaries / Never do this — prohibitions with an alternative. “Don’t use git push --force on main. If you need to roll back, use git revert or git reset on a feature branch.”

For each section, use the principle “command instead of idea.” The agent will ignore “be careful with migrations.” It will follow “Before alembic upgrade head, run alembic check. If it reports an error, don’t apply the migration; ask me.”

Ready-to-Use AGENTS.md Template (Copy and Adapt)#

# AGENTS.md

## Project overview

<project-name> - <one phrase describing its purpose>.
Stack: <Next.js / Python / Go / ...>.
Main entities: <users, orders, posts ...>.
Details for people are in README.md.

## Setup commands

```bash
# first install
npm install
cp .env.example .env  # then fill in manually; see list below

# run
npm run dev           # dev server on :3000
npm run build         # production build
npm run start         # run production build
```

## Dev environment

- Node 20+ (via nvm: `nvm use 20`)
- PostgreSQL 16 locally on :5432 (`docker-compose up postgres`)
- Redis is optional, needed only for queues (`docker-compose up redis`)
- `.env`: `DATABASE_URL`, `STRIPE_KEY`, `RESEND_API_KEY`, `JWT_SECRET`
- Never read the entire `.env` file. If you need one variable: `grep "^VAR=" .env`

## Code style

- TypeScript strict mode
- Single quotes, no semicolons (unless ESLint requires them)
- Imports: external first, then internal via `@/`, then relative
- Components in PascalCase; hooks start with `use`
- No `any` without an explicit comment explaining “why it can’t be typed”

Example of a good module:

```ts
import { z } from 'zod'

const UserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
})

export function parseUser(raw: unknown) {
  return UserSchema.parse(raw)
}
```

## Testing

```bash
npm test                                # all tests
npm test -- --testPathPattern=auth      # auth only
npm test -- --watch                     # watch mode
```

All tests must pass (be green) before committing. If a test is red, don’t commit; ask me what to do.

## Pull request guidelines

- Commit format: `<type>(<scope>): <description>` (`feat(auth): add magic-link`)
- Before PR: `npm run build && npm test && npm run lint`
- PR description = what changes, why, and how to test
- Don’t approve your own PR—always wait for human review

## Security

- Secrets only in `.env` and Vault, never in code
- Don’t log personal data (email, phone, name)
- When working with the production DB, use read-only queries only unless explicitly authorized
- Don’t hardcode external service API keys (Stripe, OpenAI) in tests

## Never do this

- Don’t `git push --force` to main. If you need to roll back, use `git revert` or open a new PR
- Don’t run DB migrations without `alembic check` (or the equivalent in your ORM)

- Don’t use `npm install -g` or `sudo` for project dependencies
- Don’t add dependencies without approval (especially heavy ones: webpack plugins, ORM)

On average, the template is 80–120 lines. If the file exceeds 150 lines, that’s a signal to refactor: move something to docs/, link to something, or compress something into one line. In practice, files of 100–150 lines work best; beyond that point, quality gains begin to reverse.

What 5 Rules Make AGENTS.md Truly Useful?#

1. Commands instead of ideas. An agent doesn’t understand “be careful with migrations.” It will follow alembic check before alembic upgrade head. Agents work with commands and conditions, not moods. Phrase all key rules as “do X, otherwise Y.”

2. Prohibitions with an alternative. A bare “don’t force push” is quietly ignored by the agent after two or three prompts. The “don’t do X; do Y instead” pairing works. Example: “don’t use git push --force on main; if you need to roll back, use git revert or open a new PR.”

3. Exactly one source of truth. The root AGENTS.md is the source of truth for the whole project. If you have a monorepo, use nested AGENTS.md files in subfolders, following the “nearest one wins” rule. No parallel files with conflicting instructions.

4. Verifiable “done” criteria. “Tests must pass” is useless. An exact criterion is: npm test returns exit code 0 and does not print FAIL to stdout. “The code should be clean” is also useless. An exact criterion is: npm run lint passes with no warnings. An agent understands what “done” means only when you explicitly describe the condition.

5. A file shorter than 150 lines. Beyond 150 lines, metrics begin to deteriorate: the agent spends more context reading and misses important rules. If it doesn’t fit, move the details to docs/architecture.md and link to it from AGENTS.md, leaving only commands and boundaries in the file.

What 10 Mistakes Turn AGENTS.md into Garbage?#

1. Vague rules without commands. The agent will ignore “be careful with migrations”—that sentence is empty to it. Only a specific command with a condition works: “Run alembic check before alembic upgrade head. If there’s an error, don’t apply the migration; ask me.”

2. “Clean code.” A useless phrase. Replace it with a specific pattern: “Use functional components with hooks. Example: function LoginForm() { const [email, setEmail] = useState(''); ... }”

3. Unstructured prose. If AGENTS.md is 300 lines of prose without headings, the agent will spend 80K context tokens on irrelevant passages and miss what matters. Use H2/H3 headings, short sections, and bullet lists.

4. A file longer than 150 lines. Quality metrics degrade past this threshold. Split it into a main file plus links to details in docs/.

5. 30+ prohibitions without alternatives. If the file has a long list of “don’t do X, don’t do Y” without explaining “do Z instead,” the agent will stumble around blindly.

6. Duplicating README.md. If you’ve already written “how to install and run” in README, don’t copy it into AGENTS.md. Instead, refer to README in one line and describe in AGENTS.md what the agent needs but human contributors don’t.

7. Hard-coding secrets. AGENTS.md may be public (it’s in git). No real API keys, tokens, or passwords. Only references to secret stores: “See Vault: secret/staging/db.”

8. Conflicting priorities without ranking. “Move fast” + “maintain 90% test coverage” leaves the agent unsure what to choose. Rank them explicitly: “Test coverage ≥80% first, then speed. If they conflict, tests take priority.”

9. Stale documentation. An architecture description that says REST+polling when reality is already WebSockets. The agent follows the stale description and breaks the architecture. Rule: update AGENTS.md in the same PR as the code whenever the architecture changes.

10. Architectural overkill for a simple task. If someone asked to change two lines in a config, the agent shouldn’t have to read the full topology of 14 microservices. Move “deep” architecture to docs/architecture.md; in AGENTS.md, leave only “if the task is architectural, read docs/architecture.md.”

GitHub Blog’s study of more than 2,500 AGENTS.md repositories states the main conclusion:

“Most agent files fail because they’re too general. ‘You are a helpful coding assistant’ doesn’t work.”

(GitHub Blog, translated from English)

How to Keep AGENTS.md and CLAUDE.md in One Repository?#

The main practical question is how to live with both files without duplicating content. Three scenarios:

Scenario 1: Claude Code only. Keep CLAUDE.md and use all of Claude Code’s features: ~/.claude/CLAUDE.md for user-level instructions, CLAUDE.md for the project, CLAUDE.local.md for personal overrides, @import to include other files, and .claude/skills/ for specialized skills. AGENTS.md isn’t needed.

Scenario 2: Several coding clients. Keep shared rules in AGENTS.md, then connect and verify each client separately. Gemini CLI supports a configured context filename; Aider can load a file through its read configuration. These are explicit loading paths, not identical automatic discovery.

Start a fresh session in a harmless test repository, add a unique harmless instruction such as “include the marker instructions-loaded in the test reply,” and inspect the client’s documented loaded-file view or logs as well as its response. Repeat for each client/version you actually use. A generated claim that the file was read is not independent proof of loading; do not infer support in every other tool from one successful check.

Scenario 3: A mixed team (Claude Code + others). This is the most common setup in 2026. The solution is to make AGENTS.md primary. If you have no rules just for Claude Code, don’t create CLAUDE.md at all: since version 2.1.277, Claude Code reads AGENTS.md when there is no CLAUDE.md in the project. If you do have such rules, make CLAUDE.md either a symlink or a short wrapper with an @AGENTS.md import.

Before changing either file, inspect and back up both. If both exist, merge their non-conflicting shared instructions into AGENTS.md and keep Claude-specific instructions in CLAUDE.md with an @AGENTS.md import. Preserve existing symlinks rather than replacing them.

For a regular CLAUDE.md only when AGENTS.md is absent, this macOS/Linux shell guard refuses to overwrite either an existing target or an existing symlink:

if [ -e AGENTS.md ] || [ -L AGENTS.md ]; then
  printf '%s\n' 'STOP: AGENTS.md exists; merge both files first.' >&2
elif [ -f CLAUDE.md ] && [ ! -L CLAUDE.md ]; then
  mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md
else
  printf '%s\n' 'STOP: inspect the existing CLAUDE.md path first.' >&2
fi

After a successful rename, CLAUDE.md is a symlink to AGENTS.md. All agents that read AGENTS.md see the same content. Claude Code, which reads CLAUDE.md, sees the same thing through the symlink.

On Windows, creating a symlink requires Developer Mode (or Admin), which may not be convenient for the whole team. An alternative is a short CLAUDE.md that imports AGENTS.md:

# CLAUDE.md

@AGENTS.md

## Claude Code specific

- Use .claude/skills/ for specialized prompts
- When working with Skills, consult .claude/skills/INDEX.md
- Use Plan Mode before major changes (Shift+Tab)

In Claude Code, this syntax pulls in AGENTS.md with one line and adds Claude Code-specific extras below. If you later want to remove AGENTS.md, just delete the import. This line doesn’t cause double-reading: according to Claude Code documentation, it doesn’t load the same AGENTS.md twice, even if it can read it on its own.

Canonical layout for a multi-tool team in 2026:

repo-root/
├── AGENTS.md                              # source of truth, ≤150 lines
├── CLAUDE.md                              # only if there are Claude-specific rules: symlink → AGENTS.md OR @AGENTS.md + extras
├── .cursor/rules/                         # targeted overrides for Cursor only
├── .github/copilot-instructions.md        # “See AGENTS.md,” if used
└── docs/architecture.md                   # deep architecture referenced by AGENTS.md

More about CLAUDE.md is in the guide “How to Configure CLAUDE.md Properly”. For more context on why an agent needs a large instruction file, read “What Is Context Engineering”.

What Changed in 2026: Why Did AAIF Bring AGENTS.md Under the Linux Foundation?#

The main political story of May 2026 in AI coding wasn’t another model release, but the consolidation of formats. Previously, every vendor had its own rules file, which was convenient for vendors but painful for teams working with several tools.

In a press release dated December 9, 2025, the Linux Foundation announced the Agentic AI Foundation as an umbrella for three formats:

• AGENTS.md from OpenAI — an instruction file format for agents
• Model Context Protocol (MCP) from Anthropic — a protocol for connecting external tools to agents
• goose from Block — an open-source agent framework

From the Linux Foundation press release:

“Bringing these projects together under the AAIF umbrella ensures they can develop with the transparency and stability that only open governance provides.”

(Linux Foundation press release, December 9, 2025, translated from English)

By February 24, 2026, 146 organizations belonged to the AAIF (97 new members in two months). New Gold members included Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, Hitachi, UiPath, American Express, and Autodesk. Anthropic is at the Platinum level, promoting MCP. OpenAI is at the Platinum level, promoting AGENTS.md. Block is at the Platinum level with goose.

This changes how AGENTS.md is positioned: from an “OpenAI format” to an industry standard. In spring 2026, Claude Code was still on the sidelines, but in September, with version 2.1.277, it learned to read AGENTS.md on its own. CLAUDE.md hasn’t gone away, and by default it still takes precedence if it’s in the project.

A practical starting point is shared project rules in AGENTS.md, plus the import, wrapper or explicit read configuration required by each client you use. For Claude Code, check its installed version and instruction-file precedence before deciding whether a CLAUDE.md import or symlink is needed. Verify loading in every client; no coverage percentage is established here.

What’s Next#

AGENTS.md is the first building block in “how to agree with an agent so it works predictably.” Next comes a project knowledge folder with business context, audience, products, and prices. Then context engineering brings everything together: which files the agent sees at each step, how state is preserved between sessions, and how to switch between different models.

Practical materials: Ailoot documentation.

More materials and tools: Ailoot.