What is AGENTS.md?

AGENTS.md meaning

`AGENTS.md` is a Markdown file that gives AI coding agents predictable, machine-readable project instructions. It can describe setup commands, test commands, code style, file ownership, deployment notes, and safety rules. OpenAI originated the format in August 2025 for the Codex CLI, and within months most major agent tools adopted it, including Cursor, Claude Code, GitHub Copilot, Devin, Windsurf, and Gemini CLI. The agents load it automatically at the start of a session.

The idea is simple: a README is written for people, so it often hides the build and test details an agent needs. AGENTS.md is the dedicated, predictable place for that operational context, which keeps the README clean while still giving agents what they need.

What to include in AGENTS.md

Keep it operational and specific. A useful AGENTS.md usually covers:

• Setup and install commands
• Test, lint, and build commands the agent should run
• Code style and formatting rules
• Important file locations and entry points
• What not to change (generated files, vendored code, secrets)
• Review, commit, and deployment expectations
• Hard boundaries and safety constraints

A short AGENTS.md example

# AGENTS.md

## Setup
```bash
npm install
```

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

## Style
- Use TypeScript, 2-space indent
- Prefer named exports

## Do not touch
- `dist/` and `*.generated.ts` are build output

Notice that every instruction is concrete and runnable. Agents follow clear commands far better than vague guidance.

Why AGENTS.md improves AI output

Teams that add an AGENTS.md report noticeably fewer hallucinations and corrections within the first session, because the agent stops guessing at commands and conventions. Giving the model the right build steps, test rules, and boundaries reduces wasted iterations and makes generated changes safer to merge. It is one of the cheapest ways to improve the quality of AI-assisted development.

AGENTS.md vs README.md

README.md explains the project to humans. AGENTS.md tells AI coding agents how to work inside the project. README.md can be broad and product-focused; AGENTS.md should be direct, operational, and specific.

AGENTS.md vs CLAUDE.md

AGENTS.md is a cross-agent instruction file. CLAUDE.md is specifically used by Claude Code for persistent project memory. Some teams keep both: AGENTS.md for shared agent instructions and CLAUDE.md for Claude-specific preferences. See how it compares to GEMINI.md, Cursor rules, and others in the AI agent instruction files guide.

How to write AGENTS.md with Markdown Docs

Draft the file in Markdown Docs online editor, preview the headings and command blocks, then save it as `AGENTS.md` in your project root. Use the desktop editor when you want local file association and autosave.

Related references

• OpenAI Codex AGENTS.md guide for official Codex behavior.
• AGENTS.md open format for the broader agent-instructions format.