Home › Rules › AGENTS.md examples

AGENTS.md examples: 8 copy-paste files for Codex, Cursor, Copilot and more

Based on the official docs of AGENTS.md, OpenAI Codex, Cursor, GitHub Copilot, Claude Code, Devin, Google Antigravity, Bolt and Lovable, checked Oct 21, 2026. Sources below.

• Formats
• AGENTS.md
• Codex
• Cursor
• Copilot

Short answer: AGENTS.md is a plain Markdown file in the root of your project that tells AI coding agents how to work on it: what the project is, the exact commands to install, run and test it, your code style, and the rules they must follow. There are no required fields. OpenAI Codex, Cursor, GitHub Copilot's coding agent, Devin, Google Antigravity, Bolt and many more read it, and current Claude Code reads it when the project has no CLAUDE.md. Below are 8 examples you can copy (beginner, Next.js + TypeScript, Python, TypeScript library, Spring Boot, a monorepo with nested files, and a global Codex file), plus where the file goes and the best practices from the docs.

What is AGENTS.md?

The official site calls it "a README for agents": one predictable place for the instructions a coding agent needs, kept separate so your README stays short for humans. It's just Markdown, so use any headings you like. The sections the AGENTS.md site suggests are a project overview, build and test commands, code style, testing instructions and security notes, plus anything you'd tell a new teammate (commit or pull request rules, deployment steps). It's an open format, now looked after by the Agentic AI Foundation under the Linux Foundation, and the site says over 60,000 open-source projects use it.

If a rule in the file conflicts with what you type in chat, the AGENTS.md site's FAQ says your chat prompt wins, and the closest AGENTS.md to the file being edited beats ones further up.

Which tools read AGENTS.md?

Where AGENTS.md goes in Codex (location, global file, override)

Codex builds its instructions once per run (once per session in the terminal app), in this order:

1. Global: in your Codex home folder, ~/.codex by default (or wherever CODEX_HOME points). It reads AGENTS.override.md if there is one, otherwise AGENTS.md. Only one file is used at this level.
2. Project: starting at the project root (usually the Git root), it walks down to the folder you started Codex in. In each folder it takes at most one file: AGENTS.override.md first, then AGENTS.md, then any extra names you listed in project_doc_fallback_filenames.
3. Merge: files are joined from the root down, so the ones closest to your folder come last and win when they disagree.

Empty files are skipped, and Codex stops adding files at 32 KiB by default (project_doc_max_bytes in ~/.codex/config.toml). Use an override when one folder needs different rules, or for a temporary global change without deleting your normal file:

# services/payments/AGENTS.override.md
- Use make test-payments instead of npm test.
- Ask before changing anything that charges money.

Tips from the Codex docs: run /init in Codex to generate a starter AGENTS.md in the current folder, and check what loaded with codex --ask-for-approval never "Summarize the current instructions." If instructions look stale, restart Codex in that folder; there's no cache to clear.

8 AGENTS.md examples

Fill in the [brackets] and delete anything that doesn't fit. Keep the commands exact: agents run the checks you list.

1. Minimal AGENTS.md for beginners

# AGENTS.md

## About this project
A [one sentence: what it is and who it's for].

## How to work with me
- I'm new to coding. Explain changes in plain English before you make them.
- Work in small steps. After each step, tell me how to test it.
- Ask before deleting files, changing the database, login or payments.
- Never put passwords or secret keys in the code.

## Commands
- Run it: [npm run dev]
- Check before you say you're done: [npm run build]

Start here if you're new. The "how to work with me" rules matter more than code style when you can't read the code yet. Want one filled in for your project type? Use the free rules file generator.

2. Next.js + TypeScript web app

# AGENTS.md

## Project
A habit tracker web app. Next.js (App Router), TypeScript, Tailwind CSS.
Pages live in src/app, shared components in src/components.

## Setup commands
- Install: npm install
- Run locally: npm run dev
- Lint: npm run lint
- Build: npm run build

## Code style
- TypeScript strict mode. No `any` unless you explain why.
- Function components only. Reuse components in src/components before making new ones.
- Tailwind classes only. No inline styles.

## Rules
- Server-only code (database, API keys) stays in server components or route handlers, never in client components.
- Never put secret keys in files that start with NEXT_PUBLIC_.
- Run npm run lint and npm run build before you say a task is done, and fix what they report.

3. Python project

# AGENTS.md

## Project
A Python script that reads new rows from a CSV export and emails me a daily summary.
Python 3.12. Code in src/, tests in tests/.

## Setup commands
- Create the environment: python -m venv .venv
- Install: pip install -r requirements.txt
- Run: python -m src.main
- Test: pytest

## Code style
- Type hints on every function. Small functions with clear names.
- Use pathlib for file paths and logging instead of print.
- Read secrets from environment variables (.env is in .gitignore). Never hard-code them.

## Testing instructions
- Add or update a test in tests/ for every change.
- Don't call real email or outside APIs in tests. Mock them.
- Run pytest before you say a task is done.

4. TypeScript library or API

# AGENTS.md

## Project
A small TypeScript library (and a demo API) published to npm.
Source in src/, tests next to the code as *.test.ts, build output in dist/ (never edit dist/ by hand).

## Setup commands
- Install: npm install
- Type check: npx tsc --noEmit
- Test: npm test
- Build: npm run build

## Code style
- TypeScript strict mode. Export types for everything public.
- No default exports. Named exports only.
- Every public function gets a short doc comment with one example.

## Rules
- Don't change a public function's name or arguments without asking. That breaks people who use the library.
- Validate API input before using it, and return clear error messages.
- Run the type check and the tests before you say a task is done.

5. Spring Boot (Java)

# AGENTS.md

## Project
A REST API for a small booking app. Java 21, Spring Boot, Maven, PostgreSQL.
Code in src/main/java, tests in src/test/java. Layers: controller -> service -> repository.

## Setup commands
- Run locally: ./mvnw spring-boot:run
- Test: ./mvnw test
- Build: ./mvnw package

## Code style
- Constructor injection only. No field injection.
- Controllers stay thin: validation and mapping only. Business logic goes in services.
- Use DTOs for requests and responses. Don't return entities from controllers.

## Rules
- Database changes go in a new migration file. Never edit a migration that already ran.
- Never put passwords or keys in application.properties. Use environment variables.
- Run ./mvnw test before you say a task is done.

Using Gradle? Swap the commands for ./gradlew bootRun, ./gradlew test and ./gradlew build.

6. Monorepo: the root file

# AGENTS.md (repo root)

## Repo layout
- apps/web: the Next.js website
- apps/api: the Node API
- packages/ui: shared React components

## Rules for the whole repo
- Package manager: pnpm. Install from the root with pnpm install.
- Each app and package has its own AGENTS.md. Read the one closest to the file you're changing.
- Don't add a dependency to the root package.json unless every app needs it.
- Run pnpm lint and pnpm test from the root before you say a task is done.

7. Monorepo: a nested AGENTS.md for one app

# AGENTS.md (apps/web)

## This app
The public website. Next.js and Tailwind. Uses components from packages/ui.

## Commands (run from the repo root)
- Dev server: pnpm --filter web dev
- Test: pnpm --filter web test

## Rules
- Change shared components in packages/ui, not copies here.
- Every page needs a title and a meta description.

The AGENTS.md site recommends one file per package in a big repo, and notes the main OpenAI repo had 88 of them when it was written. Codex, Cursor and Copilot all pick the nearest one. In VS Code's own (Local) agent, nested files are an experimental setting, chat.useNestedAgentsMdFiles, which is off by default.

8. Global AGENTS.md for Codex (every project)

# ~/.codex/AGENTS.md

## How I like to work (every project)
- I'm a beginner. Use plain English and explain new terms the first time.
- Work in small steps and tell me how to test each one.
- Ask before installing new packages or deleting files.
- Never put secret keys in code. Use environment variables.
- When you finish, list what changed in 3 bullet points.

Create the folder first with mkdir -p ~/.codex. Every project's own AGENTS.md is added after this one, so project rules win if they disagree. Antigravity's global file is ~/.gemini/AGENTS.md instead.

Real AGENTS.md examples on GitHub

To see how big projects write theirs, open apache/airflow (Python) or temporalio/sdk-java (Java), two of the examples the AGENTS.md site links to. They're written for experienced teams, so they're long. For beginner projects, our free vibe-coding-rules repo has ready-made rules files by project type.

AGENTS.md best practices

• Write down what you'd otherwise repeat. Claude Code's docs put it well: add a rule when the agent makes the same mistake a second time.
• List exact commands. The AGENTS.md site says agents will try to run the checks you list and fix failures before finishing. "Run npm run build" beats "make sure it works".
• Keep it short, important rules first. Codex reads up to 32 KiB by default; Devin automatically includes only the first 16 KiB of each file. Long how-to guides belong in skills (below).
• Use nested files in a monorepo. One per app or package, closest one wins.
• One shared file, not copies. If you also use Claude Code with a CLAUDE.md, put @AGENTS.md at the top of it instead of pasting the same rules twice. Copies drift apart.
• No secrets. It's a normal file in your repo. Never put keys or passwords in it.
• Treat it as living documentation. The AGENTS.md FAQ says to update it whenever things change.
• Check that it loaded. Codex: ask it to summarize the current instructions. Claude Code shows "AGENTS.md loaded" in the session when it reads the file.

AGENTS.md vs CLAUDE.md, skills and copilot-instructions.md

The short version: AGENTS.md is for facts and rules that always apply; skills are for procedures. Claude Code's docs say a skill's body loads only when it's used, so long reference material costs almost nothing until you need it, and Codex likewise starts with only each skill's name and description. Not sure which you need? The generator gives you AGENTS.md, CLAUDE.md and Cursor rules in one go.

AGENTS.md not being read? Check these

• Codex: the file isn't empty, you started Codex inside the right repo, and there's no AGENTS.override.md higher up (or in ~/.codex) replacing it. Check echo $CODEX_HOME if you set a custom home.
• Claude Code: a CLAUDE.md or CLAUDE.local.md anywhere from your folder up stops it from reading AGENTS.md. Add @AGENTS.md to that CLAUDE.md. Versions before v2.1.277 don't read it at all.
• VS Code (Local agent): the chat.useAgentsMdFile setting turns AGENTS.md support on or off.
• Bolt: the name must be agents.md, and the main instructions must be in that file, not only in files it links to.

Related

• AGENTS.md vs CLAUDE.md (which one you need)
• Cursor rules vs AGENTS.md
• copilot-instructions.md examples (7 copy-paste files)
• Claude Code skills examples (7 SKILL.md files)
• CLAUDE.md examples and best practices
• Google Antigravity rules
• Every rules file format
• Free rules file generator

Sources

• AGENTS.md: the open format (site and FAQ)
• OpenAI Codex docs: Custom instructions with AGENTS.md
• OpenAI Codex docs: Advanced config (project instructions discovery)
• OpenAI Codex docs: Slash commands (/init)
• OpenAI docs: Build skills
• Cursor docs: Rules (AGENTS.md, nested AGENTS.md)
• GitHub Docs: Adding repository custom instructions
• GitHub Docs: Support for different types of custom instructions
• VS Code docs: Custom instructions (AGENTS.md settings)
• Claude Code docs: How Claude remembers your project (AGENTS.md)
• Claude Code docs: Skills
• Devin docs: AGENTS.md
• Google Antigravity docs: Rules
• Bolt docs: Manage project context (agents.md)
• Lovable docs: Knowledge (AGENTS.md)

Checked Oct 21, 2026. These tools change often; if something here no longer matches, tell us at [email protected].