AGENTS.md vs CLAUDE.md vs .cursorrules: which rules file does what in 2026

Every serious AI coding agent in 2026 reads a project-level conventions file. The three big formats are AGENTS.md (the emerging cross-tool standard), CLAUDE.md (Anthropic's narrative-style file for Claude Code), and .cursorrules plus .cursor/rules/ (Cursor's modular rules system). They overlap in purpose and differ in shape. Teams that pick one and stick with it ship faster; teams that maintain three slightly-different files spend an hour a week reconciling them.

The short version

• AGENTS.md is the cross-tool default — single file, agent-agnostic, growing community support, and what most new tools read first when they encounter a repo.
• CLAUDE.md is Claude Code's primary convention file. Narrative, longer than AGENTS.md typically, with conventions plus context. Claude Code reads it on startup; other tools mostly ignore it.
• .cursorrules (the single-file format) is being deprecated in favor of .cursor/rules/*.mdc (modular, scoped rules). Cursor reads them at session start and applies them based on file scope.

The right pick depends on your tool stack. Solo on Claude Code: CLAUDE.md. Solo on Cursor: .cursor/rules/. Team with multiple agents: AGENTS.md plus tool-specific overrides.

What goes in each file

What each one is designed to do

AGENTS.md answers the question "what would I tell a new contributor on day one?" Project overview, tech stack, key directories, conventions, gotchas, the deploy story. It assumes the reader is competent but uninformed about this specific repo. The format is open-source-friendly and human-readable; many projects check it in alongside README.md.

CLAUDE.md answers the same question but with Claude Code as the audience. It can be longer and narrative — the agent reads the whole thing on every session start. Teams often duplicate AGENTS.md into CLAUDE.md (literally ln -s AGENTS.md CLAUDE.md works) and then add Claude-specific tips at the bottom.

.cursor/rules/ answers a different question: "for files matching this pattern, what's the local convention?" The frontmatter declares the scope (e.g., globs: ["app/api/**"]), and the body describes the patterns for that slice. Cursor loads only the rules that match the files in your current context, which keeps the agent's prompt lean.

Side by side with an example

The same convention written in all three formats:

In AGENTS.md:

## Conventions

- All API routes live under `app/api/<feature>/route.ts`.
- Validate input with Zod schemas defined alongside the route.
- Return `Response.json({ error })` on validation failure with status 400.
- Wrap external API calls in try/catch and log via `lib/log.ts`.

In CLAUDE.md:

## API route conventions

Every API route lives under `app/api/<feature>/route.ts` and follows the same shape:

1. Import the Zod schema for the request body.
2. Parse the body inside a try/catch.
3. On parse failure, return `Response.json({ error: result.error.message }, { status: 400 })`.
4. Wrap downstream calls (Stripe, Resend, etc.) in their own try/catch.
5. Log all errors via `lib/log.ts` — never `console.error`.

When adding a new route, copy `app/api/_template/route.ts` as a starting point.

In .cursor/rules/api-routes.mdc:

---
description: API route conventions
globs: ["app/api/**/route.ts"]
alwaysApply: true
---

API routes live at app/api/<feature>/route.ts.

Pattern:
1. Zod schema co-located with the route
2. try/catch around body parse; 400 on failure
3. try/catch around external calls
4. Log via lib/log.ts, never console.error

Reference: app/api/users/route.ts is the canonical example.

Same content, three formats. The Cursor version is scoped (only loads when editing API routes), the CLAUDE.md version is narrative (loads on every session), and the AGENTS.md version is the open-source-friendly default that other tools can also read.

How to pick

Most teams pick one of these stacks in 2026:

1. Single-tool team (e.g., everyone uses Cursor): .cursor/rules/ only. Don't write AGENTS.md unless you also want non-tool readers (recruits, AI evaluations) to see your conventions.
2. Anthropic-first team (Claude Code is the default agent): CLAUDE.md as the canonical file. Symlink AGENTS.md to it if you want cross-tool support.
3. Multi-tool team (Cursor + Claude Code + Codex): AGENTS.md as the canonical convention file. CLAUDE.md and .cursor/rules/ either symlink to it or include only tool-specific additions.
4. Solo developer: Whichever your primary tool reads. Don't maintain multiple files; one is plenty.

The sync problem and how to solve it

The pain point everyone hits: three files drift apart. Someone updates CLAUDE.md but not .cursor/rules/. The Cursor agent doesn't get the memo. A week later, an engineer pushes code that violates the new convention.

Three ways to solve it:

Option A: Single source of truth, symlinked. Pick one file (usually AGENTS.md) as canonical. Symlink the others. Tradeoff: not all tools read symlinks identically; some workflows fail.

Option B: Single source of truth, generated. Write AGENTS.md by hand. Run a small script that copies it to CLAUDE.md and to a few .cursor/rules/ files. Check in the script; rerun on changes. Tradeoff: one more thing to maintain.

Option C: Narrative + scoped split. Keep AGENTS.md as the high-level narrative (read by humans and most agents). Keep .cursor/rules/*.mdc as scoped patterns (read only by Cursor when editing matching files). Don't duplicate; each file has a different job. Tradeoff: requires discipline to know which content belongs where.

Most working teams use Option C in mid-2026. AGENTS.md for the project overview and global conventions. .cursor/rules/ for fine-grained patterns scoped to specific file ranges. CLAUDE.md as either a symlink to AGENTS.md or a tiny file with Claude-specific notes.

A real conventions file that works

# Project conventions

## Overview
Next.js 16 App Router, TypeScript strict, Tailwind v4, shadcn/ui, Drizzle ORM, Neon Postgres. Deploy to Vercel. Auth via Better Auth (Google OAuth only at launch).

## Directory map
- `app/`: App Router routes + server components + server actions
- `db/`: Drizzle schema + connection
- `lib/`: Shared utilities (auth, email, log, types)
- `components/ui/`: shadcn primitives (do not modify)
- `components/`: App-specific components

## Conventions
- Server actions live in `app/<feature>/actions.ts`. Co-locate the Zod schema.
- API routes only when an external system needs them (webhooks, OG image generator). Otherwise use server actions.
- Drizzle schema is one file: `db/schema.ts`. Never split it.
- All async functions that touch external services (Stripe, Resend, OpenAI) go through a wrapper in `lib/<service>.ts` with try/catch and logging.

## Testing
Project has no Jest/Vitest setup. Run scripts via `tsx scripts/...`. Validation scripts live in `scripts/seo/` and run in CI on PRs touching content.

## Gotchas
- `auth.api.getSession({ headers: await headers() })` is the only way to fetch the current user server-side. Anything else is stale.
- Don't run `next lint` — the project's lint config is broken (tracked in #142). Use `tsc --noEmit` instead.
- Drizzle migrations: edit `db/schema.ts`, then `npm run db:push` against your target branch. Don't generate migrations.

---
description: Server action conventions
globs: ["app/**/actions.ts"]
alwaysApply: true
---

Every server action:
1. Starts with `"use server"`
2. Calls `auth.api.getSession({ headers: await headers() })` at the top, throws on no session
3. Validates input with a Zod schema co-located in the same file
4. Wraps the DB call in try/catch
5. Returns `{ ok: true, data }` or `{ ok: false, error }` — never throws to the client

Reference: `app/actions.ts:generatePRD` is canonical.

---
description: Drizzle schema conventions
globs: ["db/schema.ts"]
alwaysApply: true
---

- All tables in one file
- Use `sql\`gen_random_uuid()\`` for primary keys
- Add `created_at` and `updated_at` on every table
- Index every foreign key
- Run `npm run db:push:local` before opening a PR

How to start fresh

If your repo has none of these files yet:

1. Write AGENTS.md. 200 to 400 lines. Project overview, directory map, conventions, gotchas, testing notes, deploy.
2. Symlink CLAUDE.md → AGENTS.md. ln -s AGENTS.md CLAUDE.md.
3. Add scoped Cursor rules only when patterns are tool-specific. Don't duplicate AGENTS.md content; add scoped patterns that the broader file can't capture (e.g., "API routes in this folder all use this 5-line shape").
4. Date the file at the top. Last updated: 2026-05-15. Update it when conventions change.
5. Check it into git. Treat it like code; review changes in PRs.
6. Test it. Open a fresh Claude Code or Cursor session and ask the agent "what are the conventions here." If the answer reflects the file, it's working. If not, the file is too long, too vague, or in the wrong format.

FAQ

Should AGENTS.md replace CLAUDE.md?

For most teams, yes, with CLAUDE.md as a symlink. AGENTS.md is the cross-tool standard that's gaining adoption faster than CLAUDE.md. Keeping AGENTS.md as canonical means new tools that read it work out of the box.

What about README.md? Do I still need that?

Yes. README.md is for humans (contributors, recruiters, users). AGENTS.md is for agents (LLM coding tools). They overlap, but the audience is different. README.md should be more polished and welcoming; AGENTS.md should be more terse and pattern-heavy.

Can I use .cursor/rules/ without AGENTS.md?

Yes. Cursor reads only its own rules and ignores AGENTS.md unless told otherwise. For single-tool teams, .cursor/rules/ alone is sufficient. The downside is that switching to another agent later means starting from scratch.

How long should the rules file be?

AGENTS.md: 200 to 800 lines. Past 800, the agent skims. Under 200, you're missing real conventions. .cursor/rules/ individual files: 20 to 150 lines each, scoped tightly. CLAUDE.md: same as AGENTS.md.

What about MCP and skills — where do those fit?

MCP servers and skills are additive, not replacements. AGENTS.md describes the project; MCP servers give the agent capabilities (database access, GitHub API, etc.); skills (Claude Code's .claude/skills/ system) capture specific workflows. All three layers compose. Start with AGENTS.md, add MCP when you need agent tools beyond file I/O, add skills when you have repeatable workflows worth codifying.