# AGENTS.md vs CLAUDE.md vs Cursor Rules: A Next.js Guide with a Free Rules Pack

**AGENTS.md vs CLAUDE.md** comes down to scope: `AGENTS.md` is an open, tool-neutral Markdown file that many coding agents read, while `CLAUDE.md` is Claude Code's own project memory file. Cursor rules (`.cursor/rules/*.mdc`) and GitHub Copilot instructions (`.github/copilot-instructions.md`) are tool-specific formats that add scoping by file pattern. Most Next.js teams need more than one of them.

> **Free and open source:** I packaged production rules for Next.js, TypeScript, React, Node.js, NestJS, Prisma, Drizzle, Tailwind CSS and shadcn/ui into one repo that renders every format from a single source. Get it here: **[github.com/fabwaseem/agent-rules](https://github.com/fabwaseem/agent-rules)** (MIT).

This guide explains what each file does, which agent reads which file, how they interact (Claude Code has specific rules for when it reads `AGENTS.md`), and gives you real rule snippets you can copy. Everything below was checked against the official docs linked in each section.

## What is AGENTS.md?

**AGENTS.md is a plain Markdown file at the root of a repository that tells AI coding agents how to work in that codebase:** build and test commands, conventions, and things to avoid. It has no required fields or frontmatter. Agents read the nearest `AGENTS.md` in the directory tree, so a nested file in a subproject takes precedence over the root one.

The format is documented at [agents.md](https://agents.md/), which describes it as "a simple, open format for guiding coding agents" used by more than 60,000 open-source projects. Think of it as a README for agents: the README is for humans, `AGENTS.md` is for the tool that edits your code.

A minimal example:

```markdown
# AGENTS.md

## Workspace
- Package manager: `pnpm`. Do not add a second lockfile.
- Run `pnpm test` and `pnpm typecheck` before you finish.
- Do not hand-edit generated output (`dist/`, `.next/`, generated database clients).
```

## What is CLAUDE.md?

**CLAUDE.md is the project instructions file for Claude Code.** Claude reads it at the start of every session from `./CLAUDE.md` or `./.claude/CLAUDE.md`, plus your personal `~/.claude/CLAUDE.md`. It is plain Markdown, can import other files with `@path/to/file`, and Anthropic recommends keeping each file under 200 lines because longer files cost context and reduce adherence.

Those details come straight from the [Claude Code memory docs](https://code.claude.com/docs/en/memory). Two things matter most in practice:

1. **Imports.** A line like `@AGENTS.md` in `CLAUDE.md` pulls that file into context at launch, up to four hops deep. This is how you share one source of truth between Claude and every other agent.
2. **Instructions are context, not enforcement.** The docs say so directly: to block an action no matter what, use a hook, not a sentence in `CLAUDE.md`.

## Does Claude Code read AGENTS.md?

**Yes, but only in one situation by default.** Claude Code reads `AGENTS.md` as project instructions when there is no `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` in your working directory or above it. If a `CLAUDE.md` exists, Claude reads only the `CLAUDE.md` files, unless that file imports `AGENTS.md` or you change the Project instructions setting.

Here is the behavior from the official docs, summarized:

| Your repository has | Claude Code reads |
| --- | --- |
| `AGENTS.md` only | `AGENTS.md` |
| `AGENTS.md` and `CLAUDE.md` | `CLAUDE.md` only |
| `CLAUDE.md` that contains `@AGENTS.md` | `CLAUDE.md` with `AGENTS.md` included |

Reading `AGENTS.md` directly also needs a recent Claude Code version (v2.1.277 or later per the docs). The safest setup for a mixed team is a short `CLAUDE.md` that imports `AGENTS.md` and adds only Claude-specific notes. That is exactly what the [agent-rules](https://github.com/fabwaseem/agent-rules) installer writes.

## AGENTS.md vs CLAUDE.md vs Cursor rules vs Copilot instructions: what is the difference?

**They differ in who reads them and how they are scoped.** `AGENTS.md` is shared by many agents and scoped by directory. `CLAUDE.md` is Claude Code only. Cursor `.mdc` rules can attach to specific file globs or load when the agent judges them relevant. Copilot path instructions use an `applyTo` glob. Use `AGENTS.md` for shared rules and the others for targeted ones.

![Diagram: one source rule rendered into AGENTS.md, CLAUDE.md, Cursor rules, Copilot instructions, Claude skills and Windsurf/Devin rules](https://res.cloudinary.com/wasicloudinary/image/upload/v1792135029/fabwaseem/blog/agents-md-vs-claude-md/diagram-formats.jpg)

| | AGENTS.md | CLAUDE.md | Cursor `.mdc` | Copilot instructions | Claude Code skill | Windsurf / Devin |
| --- | --- | --- | --- | --- | --- | --- |
| Path | `AGENTS.md` (nested allowed) | `CLAUDE.md`, `.claude/CLAUDE.md` | `.cursor/rules/*.mdc` | `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md` | `.claude/skills/<name>/SKILL.md` | `.devin/rules/*.md`, `.windsurf/rules/*.md` |
| Frontmatter | None | None | `description`, `globs`, `alwaysApply` | Path files: `applyTo` | `name`, `description` | `trigger` plus `globs` or `description` |
| Scope | Nearest file in the tree | Claude Code sessions | Always, by glob, agent-selected or `@` mention | Repo-wide or matching `applyTo` | Loaded on demand | Always, glob, model decision or manual |
| Best for | Rules every agent shares | Claude-specific additions | Rules tied to certain files | Copilot Chat, review and coding agent | Multi-step procedures | Cascade / Devin workspace rules |

Sources: [agents.md](https://agents.md/), [Cursor Rules docs](https://cursor.com/docs/rules), [Claude Code memory](https://code.claude.com/docs/en/memory), [Claude Code skills](https://code.claude.com/docs/en/skills), [GitHub Copilot repository instructions](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions) and [Windsurf / Devin rules](https://docs.devin.ai/desktop/cascade/memories).

## How do Cursor rules work in a Next.js project?

**Cursor reads `.mdc` files from `.cursor/rules/`, and the frontmatter decides when each rule loads.** `alwaysApply: true` includes it every session. `alwaysApply: false` with `globs` attaches it when a matching file is in context. A `description` with no globs lets the agent pull it in when relevant. With neither, it loads only when you `@` mention it.

One gotcha: Cursor ignores a plain `.md` file inside `.cursor/rules/`. The extension must be `.mdc`. Here is the real App Router rule from the repo, trimmed:

```markdown
---
description: "Next.js App Router structure, Server Components, routing files, and proxy.ts."
globs: "app/**/*.ts,app/**/*.tsx,src/app/**/*.ts,src/app/**/*.tsx,next.config.*,proxy.ts,middleware.ts"
alwaysApply: false
---

# Next.js App Router

- New UI goes in the App Router. Do not add a `pages/` route.
- Components are Server Components by default. Add `"use client"` only on the leaf
  that needs state, effects, or browser APIs.
- Read `params` and `searchParams` as promises and `await` them.
- Set document metadata with the Metadata API. Do not add `next/head`.
- Import `server-only` in modules that read secrets or talk to the database.
- On Next.js 16, request interception lives in `proxy.ts` and exports `proxy`.
- Do not flip `cacheComponents` on as a drive-by.
```

Because it has globs, this rule costs nothing when you are editing a Prisma schema or a README. That is the main advantage of Cursor rules over one giant `AGENTS.md`.

## What should go in AGENTS.md for a Next.js app?

**Put the things every agent must know in every session:** the package manager and scripts, how to run tests and typecheck, which folders are generated, and short, specific conventions. Keep stack details that only matter for some files in scoped rules. Short and concrete beats long and vague, because agents follow specific instructions more reliably.

A good checklist for a Next.js `AGENTS.md`:

- **Commands:** install, dev, test, typecheck, lint, build.
- **Package manager:** one, named explicitly, with "do not add a second lockfile".
- **Generated paths:** `.next/`, `dist/`, coverage, Prisma client.
- **Conventions:** Server Components by default, Zod validation at boundaries, server actions that authorize inside the action.
- **Git:** commit format and what not to do (no force-push on shared branches).
- **Definition of done:** tests pass, types check, no new warnings.

Avoid generic advice like "write clean code". It costs tokens and changes nothing.

## How do GitHub Copilot instructions differ?

**Copilot uses a repo-wide `.github/copilot-instructions.md` plus optional path-specific files in `.github/instructions/` that end in `.instructions.md` and declare an `applyTo` glob.** Copilot Chat, code review and the Copilot coding agent read them. Copilot also reads `AGENTS.md` files, with the nearest one taking precedence, but `applyTo` files are how you scope rules to certain paths.

A real path-specific file from the repo's NestJS example:

```markdown
---
applyTo: "**/*.controller.ts,**/*.service.ts,**/*.module.ts,**/*.guard.ts,**/*.dto.ts"
---

# NestJS

- A feature is a module: `*.module.ts`, a controller, a service, and DTOs.
- Controllers translate HTTP. Services hold business rules. A controller does
  not import Prisma or Drizzle directly.
- Do not read `process.env` inside a service. Inject `ConfigService`.
- Authentication is a guard. Resource authorization happens in the service.
```

## When should you use a Claude Code skill instead of a rule?

**Use a rule for a constraint and a skill for a procedure.** A rule says "never do X in these files". A skill is a step-by-step workflow, like making a commit or adding a server action, that Claude loads only when its `description` matches the task or when you type `/name`. Skills live in `.claude/skills/<name>/SKILL.md` with `name` and `description` frontmatter.

Per the [skills docs](https://code.claude.com/docs/en/skills), `name` is lowercase letters, numbers and hyphens. Here is the commit skill from the pack:

```markdown
---
name: git-commit
description: Use when creating a git commit or pull request and the change should follow this repository's commit conventions.
---

# Commit a change

1. Inspect `git status` and `git diff`. Stage only the files that belong to this change.
2. Run typecheck and the tests that cover the change. Do not commit a known failure.
3. Write a Conventional Commit subject: `type(scope): imperative summary`.
4. Do not add `Co-authored-by` or other trailers unless the user asked.
5. Do not amend or force-push a commit that is already on a remote.
```

## What is agent-rules and what does it include?

**[agent-rules](https://github.com/fabwaseem/agent-rules) is an MIT-licensed pack of production rules for AI coding agents, written once as `.mdc` source files and rendered into AGENTS.md, CLAUDE.md, Cursor rules, Copilot instructions, Claude Code skills and Windsurf/Devin rules.** You pick the stacks you use, and the installer writes only those, so the formats never drift apart.

Stacks covered:

| Stack | What the rules argue for |
| --- | --- |
| Core | Strict TypeScript, no `any` or `enum`, Zod at runtime, Conventional Commits, WCAG 2.2 AA, Vitest |
| Next.js | App Router only, Server Components first, `params` as promises, `proxy.ts` on Next.js 16, server actions that validate and authorize |
| React | Composition, derived state, `ref` as a prop on React 19 |
| Node.js | Validate env once at startup, handle `SIGTERM`, timeouts on outbound calls |
| NestJS | Feature modules, thin controllers, whitelist validation, guards for auth |
| Prisma | Follow the installed major (Prisma 7 driver adapters), new migration per change, one client per process |
| Drizzle | Schema in TypeScript, `drizzle-kit generate` then `migrate`, bound parameters only |
| Tailwind CSS | v4 `@import "tailwindcss"` and `@theme` tokens, `cn()` for conditional classes |
| shadcn/ui | `components/ui` is source you own, semantic colors, compose what the CLI added |

It also ships 12 Claude Code skills (commit, add tests, security review, accessibility pass, Next.js server action, Next.js cache, React component, Node service, Prisma change, Drizzle change, NestJS feature and shadcn compose) and two committed examples: a Next.js SaaS setup and a NestJS API.

## How do you install the rules into your project?

**Clone the repo, build the installer and point it at your project.** It detects your stacks from `package.json` and `components.json`, asks you to confirm, then writes each format. Re-running updates only its own marked blocks in `AGENTS.md`, `CLAUDE.md` and `copilot-instructions.md`, so text you wrote outside them stays.

```bash
git clone https://github.com/fabwaseem/agent-rules.git
cd agent-rules && npm install && npm run build

# preview what would be written
node dist/cli.js --target ../my-next-app --dry-run

# install chosen stacks and formats
node dist/cli.js --target ../my-next-app \
  --stacks core,nextjs,react,prisma,tailwind,shadcn \
  --agents agents,claude,cursor,copilot
```

Prefer no tooling? Copy files by hand from [`examples/nextjs-saas`](https://github.com/fabwaseem/agent-rules/tree/main/examples/nextjs-saas): take `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/`, `.github/` and `.claude/skills/` and drop them into your repo. An `npx` one-liner is coming soon once the package is published to npm.

The installer needs Node.js 20.19 or later. It also includes a `validate` command that checks Cursor frontmatter keys, Copilot `applyTo`, skill names and Windsurf triggers, including the 12,000-character Windsurf workspace rule limit.

## Should you keep one file or several?

**Keep one shared source and generate the rest.** Hand-maintaining five formats means they drift: someone updates Cursor rules and forgets `AGENTS.md`. A single `AGENTS.md` plus a `CLAUDE.md` that imports it works for small repos. Larger repos benefit from glob-scoped Cursor and Copilot files so each conversation only carries relevant rules.

| Repo size | Recommended setup |
| --- | --- |
| Solo or small app | `AGENTS.md` + `CLAUDE.md` with `@AGENTS.md` |
| Team Next.js app | Above + glob-scoped `.cursor/rules/*.mdc` and `.github/instructions/*` |
| Monorepo | Root `AGENTS.md` + nested `AGENTS.md` per package + scoped rules |

If you run your own agent tooling, the same idea applies to servers too. I wrote about exposing tools to agents in [How to Build an MCP Server in Next.js](https://www.fabwaseem.com/blog/build-mcp-server-nextjs), and about getting content cited by AI engines in [Next.js SEO for AI Search](https://www.fabwaseem.com/blog/nextjs-seo-ai-search). You can see more of what I build on the [projects page](https://www.fabwaseem.com/projects).


**Related:** when a section of AGENTS.md grows into a multi-step procedure, move it into an Agent Skill that loads only when needed. See [Agent Skills: how to write a SKILL.md for Claude Code, Cursor, Codex and Copilot](https://www.fabwaseem.com/blog/agent-skills).

## Key takeaways

- `AGENTS.md` is the open, shared format. Use it for rules every agent should follow.
- Claude Code reads `AGENTS.md` only when no `CLAUDE.md` exists, so add `@AGENTS.md` to your `CLAUDE.md` if you keep both.
- Cursor needs `.mdc` files in `.cursor/rules/`, and globs keep rules out of unrelated conversations.
- Copilot path rules use `.instructions.md` files with an `applyTo` glob.
- Generate every format from one source so they never drift. [agent-rules](https://github.com/fabwaseem/agent-rules) does this for the Next.js and TypeScript stack.