How to write an AGENTS.md (and CLAUDE.md) file for your AI coding tool

Guide · checked against the docs on Oct 15, 2026

AI coding tools start each session without remembering your project. Cursor's rules docs say it plainly: "Large language models don't retain memory between completions." An instructions file fixes part of that. It's a short Markdown file in your repo that the tool reads before it starts work: how to run the tests, what not to touch, and what "done" means.

Each tool looks for a different file name, in different places. This guide covers four of them, quoted from each vendor's own docs as read on October 15, 2026, and ends with a sample AGENTS.md you can copy. File names and loading rules change, so treat the details below as per the docs, checked Oct 2026.

Not affiliated with or endorsed by OpenAI, Anthropic, Cursor or GitHub. Check each tool's docs before relying on these details.

Our tool pages: OpenAI Codex · Claude Code · Cursor · GitHub Copilot

Which file each tool reads

All details in this table are per the docs, checked Oct 2026.

AGENTS.md is the one name all four list, though for Copilot it depends on where you use it. Its own site, agents.md, calls it "A simple, open format for guiding coding agents" and says "Think of AGENTS.md as a README for agents".

AGENTS.md in Codex

OpenAI's docs say: "Codex reads AGENTS.md files before doing any work." Where it looks, per the docs, checked Oct 2026:

• Global: "In your Codex home directory (defaults to ~/.codex, unless you set CODEX_HOME), Codex reads AGENTS.override.md if it exists. Otherwise, Codex reads AGENTS.md."
• Project: "Starting at the project root (typically the Git root), Codex walks down to your current working directory." In each folder "it checks for AGENTS.override.md, then AGENTS.md, then any fallback names in project_doc_fallback_filenames. Codex includes at most one file per directory."

Which file takes priority: "Files closer to your current directory override earlier guidance because they appear later in the combined prompt." There's also a size cap: Codex "stops adding files once the combined size reaches the limit defined by project_doc_max_bytes (32 KiB by default)." (Per the docs, checked Oct 2026.)

CLAUDE.md in Claude Code

Anthropic's memory docs: "A project CLAUDE.md can be stored in either ./CLAUDE.md or ./.claude/CLAUDE.md. Create this file and add instructions that apply to anyone working on the project: build and test commands, coding standards, architectural decisions, naming conventions, and common workflows."

You don't have to start from a blank page: "Run /init to generate a starting CLAUDE.md automatically." The docs add that "If a CLAUDE.md already exists, /init suggests improvements rather than overwriting it."

Other places it looks, per the docs, checked Oct 2026:

• ~/.claude/CLAUDE.md for "Personal preferences for all projects".
• ./CLAUDE.local.md for "Personal project-specific preferences; add to .gitignore".

Which file takes priority: they don't override each other. "All discovered files are concatenated into context rather than overriding each other." Content runs from the top folder down, "so instructions closer to where you launched Claude are read last." Files in subfolders "load on demand."

Using AGENTS.md with Claude Code: the docs say Claude Code "can read AGENTS.md as your project instructions". But "By default, Claude reads AGENTS.md only when you have no CLAUDE.md in your working directory or above it." Reading it directly "requires Claude Code v2.1.277 or later" (per the docs, checked Oct 2026). The docs add that before v2.1.281 some sessions, such as those on Amazon Bedrock or with telemetry turned off, couldn't load it, and that in those cases you should import it from a CLAUDE.md instead. Run claude --version to check. If you keep both files, the docs suggest "putting an @AGENTS.md import in a CLAUDE.md next to it":

@AGENTS.md

## Claude Code
(Claude-only notes go here)

Keep it short. The docs say to "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence."

Cursor rules

Cursor's rules docs list four kinds. Two live in your repo:

• "Project Rules Stored in .cursor/rules, version-controlled and scoped to your codebase."
• "AGENTS.md Agent instructions in markdown format. Simple alternative to .cursor/rules."

Watch the file extension: "Project rules must use the .mdc extension. A plain .md file in .cursor/rules is ignored by the rules system… If you prefer plain markdown, use AGENTS.md instead." (Per the docs, checked Oct 2026.)

Each rule picks when it applies: Always Apply, Apply Intelligently, Apply to Specific Files, or Apply Manually ("When @-mentioned in chat").

Which file takes priority: Cursor supports AGENTS.md "in the project root and subdirectories", and "nested AGENTS.md files are combined with parent directories, with more specific instructions taking precedence." Team Rules, on Team and Enterprise plans, "take precedence to ensure organizational standards are maintained".

Cursor's tips: "Keep rules under 500 lines", "Avoid vague guidance", and "Reference files instead of copying their contents."

GitHub Copilot custom instructions

GitHub's docs say you can "Create repository custom instructions files that give Copilot additional context on how to understand your project and how to build, test and validate its changes." Where they go, per the docs, checked Oct 2026:

• Whole repo: "a copilot-instructions.md file in the .github directory of the repository."
• Specific paths: "one or more NAME.instructions.md files within or below the .github/instructions directory", with an applyTo line that sets which files they cover.
• Agents: "You can create one or more AGENTS.md files, stored anywhere within the repository." Or "Alternatively, you can use a single CLAUDE.md or GEMINI.md file stored in the root of the repository."

Which file takes priority: "the nearest AGENTS.md file in the directory tree will take precedence." When a path-specific file matches and a repo-wide file exists, "the instructions from both files are used."

Support varies by where you use Copilot. GitHub's support table lists AGENTS.md, CLAUDE.md or GEMINI.md for Copilot cloud agent and Copilot CLI, but only AGENTS.md for Copilot Chat in Visual Studio Code. Check the table for your editor (per the docs, checked Oct 2026).

What to put in the file

The four docs ask for much the same things. Anthropic lists "build and test commands, coding standards, architectural decisions, naming conventions, and common workflows." GitHub frames it as how "to build, test and validate its changes." A useful file answers four questions:

1. How do I run it? Install, test and build commands, exactly as you type them.
2. What must I not touch? Secrets, dependencies, tests.
3. How big should a change be? Small, and only the files the task needs.
4. What does done mean? Which checks must pass, and what to report back.

Leave out anything the tool can read from the code itself. Cursor's tip is to point at files rather than paste them in.

A sample AGENTS.md to copy

This is a starting point for a small Node.js project. Swap in your own commands. We haven't measured how well any tool follows it.

# AGENTS.md

## About this project
A small Node.js web app. Source code is in src/, tests are in tests/.

## Commands
- Install: `npm install`
- Test: `npm test`
- Build: `npm run build`

## Rules
- Don't edit `.env` or any file with keys or passwords in it.
- Don't add, remove or upgrade dependencies without asking first.
- Don't delete, skip or weaken tests to make them pass.
- Change only the files the task needs. If another file needs to change, stop and ask.
- Keep changes small. One task per change.

## Done means
- `npm test` passes.
- `npm run build` passes.
- You've listed every file you changed and why, in one line each.

To use the same rules in more than one tool:

• Codex, Cursor and Copilot's agent features: keep it as AGENTS.md in the project root.
• Claude Code: it reads AGENTS.md by default only if there's no CLAUDE.md or CLAUDE.local.md in your project folder or above it. If there is, add @AGENTS.md at the top of your CLAUDE.md.

Keep it short and keep it current

Long files get skimmed. Anthropic suggests under 200 lines per CLAUDE.md, and Cursor says under 500 lines per rule. When the tool repeats a mistake, add one clear line about it. When a rule stops being true, delete it.

Next step

An instructions file is one habit out of several. Our guide on how to stop AI coding tools breaking your code covers the others: commit first, ask for a plan, read the diff and undo with git. A prompt pack built on these habits is coming soon.

We haven't published hands-on test results for these tools. This guide collects what each vendor's docs say, not how the tools performed for us.

Not affiliated with or endorsed by OpenAI, Anthropic, Cursor or GitHub. Check each tool's docs before relying on these details.