AGENTS.md vs CLAUDE.md vs .cursorrules: which AI instruction file do you need?

AGENTS.md, CLAUDE.md, and .cursorrules are all plain text files that tell AI coding agents how to work on your project. They differ in who reads them: AGENTS.md is an open format many tools share, CLAUDE.md is for Claude Code, and .cursorrules is Cursor's older, now deprecated format.

If your team uses more than one AI coding tool, you've probably found several of these in the same repository, each slightly different from the others. This guide explains what each file is, which tools read which, and how to set things up so you maintain one set of instructions instead of three.

The files at a glance

Key takeaway: AGENTS.md is the shared format, CLAUDE.md and Cursor's rules are tool-specific, and .cursorrules is legacy.

AGENTS.md: the shared format

Key takeaway: AGENTS.md gives teams one instruction file that many coding agents can read, instead of a separate file for every tool.

Early on, each AI coding tool asked for its own file. A team using two or three tools kept several copies of the same instructions, and the copies drifted apart.

AGENTS.md was released in the second half of 2025 as a single, vendor-neutral answer. According to the official site, it came out of a joint effort between OpenAI's Codex team, Amp, Google's Jules, Cursor, and Factory. The idea was deliberately simple: one predictable file name, plain Markdown, and no required structure.

In December 2025, OpenAI contributed AGENTS.md to the newly formed Agentic AI Foundation, part of the Linux Foundation, so no single company controls the format. The official site reports that more than 60,000 open source projects on GitHub include an AGENTS.md file.

Support changes quickly, so check your tool's documentation. As of October 2026:

CLAUDE.md: Claude Code's file

Key takeaway: CLAUDE.md is Claude Code's instruction file. It can import AGENTS.md, so shared instructions live in one place.

CLAUDE.md does for Claude Code what AGENTS.md does for many tools. Claude Code reads a CLAUDE.md in your repository, and can also read a personal one in your home folder for preferences that apply to all your projects, as described in the Claude Code documentation.

Two details matter if you also use other tools:

• Claude Code reads AGENTS.md only when a folder has no CLAUDE.md, unless you change a setting.
• A CLAUDE.md can import another file. A line that reads @AGENTS.md pulls in your shared instructions, so you don't copy them.

Claude Code's /init command can generate a CLAUDE.md by reading your project. Treat the result as a first draft to cut down, for reasons the research section below explains.

.cursorrules and Cursor's Project Rules

Key takeaway: .cursorrules is deprecated. Cursor now uses .mdc files in .cursor/rules/, and also reads AGENTS.md.

.cursorrules was Cursor's original instruction file: a single file at the repository root, applied to every request. Cursor's documentation now lists it as legacy, still supported but deprecated, and recommends Project Rules instead.

If you have an old .cursorrules file, move its contents into AGENTS.md if other tools should follow them, or into .cursor/rules/ if they only make sense in Cursor.

Which file should you use?

Key takeaway: if you use one tool, use its preferred file. If you use several, make AGENTS.md the shared source and keep the rest small.

For teams using several tools, a practical setup:

1. Put shared instructions in AGENTS.md.
2. Add a tool-specific file only for rules that apply to one tool.
3. Where a tool lets one file point to another, point it at AGENTS.md instead of copying. In Claude Code, a CLAUDE.md that contains @AGENTS.md does this.
4. Delete any legacy .cursorrules file once its contents have moved.

Whatever the file, it's shared with everyone who can read your code, so never put secrets in it. Our guide What is .env? covers where those belong.

What to put in an instruction file

Key takeaway: include what an agent can't work out from your code and keeps getting wrong. Leave out anything it can already read elsewhere.

The same advice applies to all of these files. Here's a short example:

# AGENTS.md

## Commands
- Install dependencies: `pnpm install`
- Run tests: `pnpm test`
- Lint and format: `pnpm lint:fix` (run before every commit)

## Conventions
- Use pnpm, not npm or yarn
- Write tests with Vitest, not Jest
- Database changes need a migration in `migrations/`

## Don't
- Don't edit files in `generated/`. Run `pnpm codegen` instead.
- Don't commit `.env` files

Agents read your README too, so don't repeat it. Our Dev Center post AGENTS.md: Why your README matters more than AI configuration files makes the case in detail.

Keep it short: what the research says

Key takeaway: context files full of instructions an agent doesn't need, especially ones an agent writes for itself, tend to make agents slower and more expensive.

It's tempting to have an agent generate a thorough instruction file describing your whole codebase. A February 2026 study from researchers at ETH Zurich and LogicStar.ai, Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?, tested that approach on several coding agents and real-world tasks. The results, as summarized in our Dev Center post:

Extra instructions led agents to explore more files and run more checks on every task. So:

1. Start with an empty or very short file.
2. Watch for mistakes the agent makes more than once.
3. Add one specific rule for each repeated mistake.
4. Remove rules that don't change the agent's behavior.

Tests, linters, and type checkers often matter more than any instruction file, because they tell an agent immediately when something is wrong. For the full breakdown, read The research is in: your AGENTS.md is probably too long on the Upsun Developer Center.

Instruction files for Upsun Cloud projects

Key takeaway: for an Upsun Cloud project, the most useful lines tell agents where the infrastructure is defined, how to check it, and what they must never touch.

Coding agents can read your code, but they can't see how your project is hosted unless something tells them. On Upsun Cloud, your apps, services, and routes are defined in one YAML file, .upsun/config.yaml. A few lines in AGENTS.md, or CLAUDE.md, can point agents to it:

## Deployment (Upsun Cloud)

- Infrastructure is defined in `.upsun/config.yaml`. Run `upsun app:config-validate` after changing it.

- Pushing to Git starts a build and deployment. Test changes in a preview environment before merging into production.

- Secrets are stored as Upsun Cloud variables. Never add them to the repository or to `.upsun/config.yaml`.

If you want agents to do more than edit code, Upsun offers two options. Upsun Skills is an open source skill that teaches coding agents to use the Upsun Cloud command line tool. Our upcoming guide What are agent skills? [ADD LINK WHEN LIVE] explains how skills work. The Upsun Cloud MCP server lets AI assistants query and manage projects, and it's read-only unless you turn on write access. If you use either, note in your instruction file which actions an agent should ask about first.

New to the configuration file itself? Our guide What is a YAML file? walks through it using a real Upsun Cloud example.

Frequently asked questions

What is the difference between AGENTS.md and CLAUDE.md?

AGENTS.md is an open format many coding agents read. CLAUDE.md is Claude Code's own file. Claude Code reads AGENTS.md when a folder has no CLAUDE.md, and a CLAUDE.md can import AGENTS.md so shared instructions live in one place.

Is .cursorrules deprecated?

Yes. Cursor still supports it but lists it as legacy. Use Project Rules in .cursor/rules/ for Cursor-specific instructions, or AGENTS.md for instructions shared with other tools.

Does Cursor read AGENTS.md?

Yes. Cursor supports AGENTS.md as a plain Markdown alternative to its Project Rules.

Can I use AGENTS.md and CLAUDE.md together?

Yes. Keep shared instructions in AGENTS.md and add @AGENTS.md to your CLAUDE.md, so Claude Code reads both without duplicate content.

Should I commit these files to Git?

Yes, so every developer and every agent gets the same instructions. Review changes to them like code changes, and never put secrets in them.

Should I let an AI agent write my instruction file?

Use generated files with care. Research published in February 2026 found that agent-generated context files slightly lowered success rates and raised costs. A short file you write yourself, based on mistakes you've actually seen, tends to work better.

Is an instruction file a security risk?

It can be. Agents treat its contents as instructions, so a malicious change could steer an agent into doing something harmful. Review changes carefully, and be wary of copying rules from unknown sources.