AGENTS.md vs CLAUDE.md vs Cursor Rules for React

You added Claude Code to a React project that already had Cursor rules, a teammate runs Codex, and now the repo has three instruction files that disagree about button sizes. AGENTS.md vs CLAUDE.md is the question underneath: which file does each agent actually read, and where should your design system rules live so that every agent follows them? This post answers it with the loading rules from each tool's documentation as of October 2026, the layout Next.js 16.3 now writes for you, and a rules file, modeled on the one in our own repo, that keeps agents on your design tokens.

We build Wingo UI, a React component library, so the examples use its Button and UIProvider. The file layout works in any React and Tailwind CSS project. More guides on agents and UI are in Building UI with AI agents.

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

AGENTS.md is the shared, tool-neutral instruction file that Codex, Cursor and most other agents read. CLAUDE.md is Claude Code's own file, with imports, personal and organization scopes, and path-scoped rules next to it. Both hold plain Markdown instructions; what differs is who reads each file and what the loader does with it.

AGENTS.md is an open format stewarded by the Agentic AI Foundation under the Linux Foundation. The agents.md site (opens in a new tab) lists Codex, Cursor, Gemini CLI, GitHub Copilot's coding agent, Jules, Zed, Windsurf and others as tools that read it, and says more than 60,000 open source projects use it. It has no required fields. Its precedence rule is short: the closest AGENTS.md to the edited file wins, and an explicit prompt in the chat overrides everything.

CLAUDE.md is Claude Code's own memory file. It comes in four scopes: an organization policy file, ~/.claude/CLAUDE.md for you, ./CLAUDE.md for the team, and CLAUDE.local.md for your private notes. It supports @path imports up to four hops deep, and it has a companion folder, .claude/rules/, whose files can be scoped to paths.

Cursor rules are .mdc files in .cursor/rules with frontmatter that decides when each one loads. Cursor reads AGENTS.md too.

Which file does each agent read?

Each tool reads its own file, and all three read AGENTS.md in some form. Here is how loading works, as of October 2026:

Sources, checked October 9, 2026: the Claude Code memory docs (opens in a new tab), the Codex AGENTS.md guide (opens in a new tab), the Cursor rules docs (opens in a new tab) and agents.md (opens in a new tab). Gemini CLI reads GEMINI.md by default and reads AGENTS.md once you list it in context.fileName in settings.json, according to its GEMINI.md docs (opens in a new tab).

Two details in that table decide most setups. Codex documents no import syntax and builds its chain once, when it starts, so whatever Codex should know has to be in an AGENTS.md on the path from the Git root to where you launch it, or in your global one in ~/.codex. Cursor rules only reach the Agent: the Cursor docs say "Rules do not impact Cursor Tab or other AI features."

Does Claude Code read AGENTS.md now?

Yes, since v2.1.277, with one condition that catches people: by default Claude Code reads AGENTS.md only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists in the working directory or any directory above it. Your ~/.claude/CLAUDE.md and .claude/rules/ files do not count toward that check.

The trap is CLAUDE.local.md. A teammate who adds one for private notes, in a repo that relies on AGENTS.md alone, turns AGENTS.md off for their own sessions. A tool that scaffolds a CLAUDE.md does the same for everyone. Run /memory to see which files loaded, or set Project instructions to claude-md-and-agents-md in /config if you want both files read.

Some sessions cannot read AGENTS.md directly at all: versions before v2.1.277, sessions where the built-in plugin that reads it is disabled, and in some cases the first session after an upgrade. Claude Code also never reads AGENTS.override.md or AGENTS.local.md. An import works in all of these cases, which is why we use one.

Which setup works for Claude Code, Codex and Cursor at once?

Make AGENTS.md the single source of truth and give Claude Code a CLAUDE.md that imports it. Codex and Cursor read AGENTS.md natively, and Claude Code reads it through the import whatever its version or settings.

your-app/
├── AGENTS.md                  # every rule every agent needs
├── CLAUDE.md                  # @AGENTS.md, then Claude-only lines
├── .claude/rules/ui-kit.md    # Claude Code: loads when it reads files in components/ui
└── .cursor/rules/ui-kit.mdc   # Cursor: attaches when components/ui files are in context

The CLAUDE.md stays tiny. Claude reads the imported file first, then the lines below it:

@AGENTS.md

## Claude Code only

- Use plan mode before you change more than one file in `components/ui`.

This is the layout Next.js now writes. create-next-app creates both files, and on Next.js 16.3 and later next dev adds them to an existing project when it detects a coding agent and finds no managed block. AGENTS.md gets a managed block that tells agents to read the docs bundled in node_modules/next/dist/docs/, and CLAUDE.md gets the single line @AGENTS.md. Text outside the block's markers survives updates, and agentRules: false in next.config.ts turns the generation off (Next.js AI agents guide (opens in a new tab)). Our own repository runs the same setup: CLAUDE.md is that one line, and AGENTS.md is 68 lines, the Next.js block included.

Keeping the shared rules in a file that is always loaded matters more than it looks. In AGENTS.md outperforms skills in our agent evals (opens in a new tab) (Jude Gao, Vercel, January 27, 2026), an 8 KB docs index in AGENTS.md passed 100% of a Next.js 16 eval suite, against 79% for a skill with explicit instructions to use it and 53% with no docs at all. Without those instructions, the agent never invoked the skill in 56% of the cases.

A symlink (ln -s AGENTS.md CLAUDE.md) also works when you have no Claude-only lines. Anthropic's docs list the catch: on Windows, Git checks a committed symlink out as a plain text file unless core.symlinks is enabled, which leaves that clone with a one-line CLAUDE.md. The import has no such failure.

One wrinkle with our own CLI: npx wingo-ui@latest agents install claude codex writes the same marked block, about 1 KB, into both CLAUDE.md and AGENTS.md, so with the import Claude reads it twice. The two copies are identical and agents update rewrites both, so they cannot contradict each other.

What should a React and Tailwind rules file say?

The things an agent cannot learn from one read of your code: where the components live and how to look them up, which tokens to use, which defaults are set in one place, which checks to run, and the few things it must never do. If you start from a CLAUDE.md for React or AGENTS.md examples you found online, strip out any component inventory or props table. That copy goes stale with the next release, and an agent reading a stale table has no reason to open the real file.

Here is an AGENTS.md for a Next.js dashboard built on Wingo UI, with the Next.js block shortened. Each section answers one of the questions above:

<!-- BEGIN:nextjs-agent-rules -->
(managed by next dev: read the docs in node_modules/next/dist/docs/ before writing code)
<!-- END:nextjs-agent-rules -->

# Acme dashboard

Next.js 16 App Router, React 19, Tailwind CSS v4, TypeScript strict.

## Commands

- Dev server: `npm run dev` on http://localhost:3000. If it is already running, use it; never start a second one.
- Before you call a task done: `npx tsc --noEmit`, `npx eslint <files you changed>`, `npm run check:tokens`.

## UI components

- Components live in `components/ui` (Wingo UI, installed as source, versions in `wingo-ui.json`). Before writing UI, search them: the `wingo-ui` MCP tools, or `npx wingo-ui@latest search <words>`. Never hand-write a component that exists there.
- Install with `npx wingo-ui@latest add <slug...>`. Read a component's props before you first use it: `get_component`, or `npx wingo-ui@latest info <slug>`.
- App-wide looks are set once, in `app/layout.tsx`, with `<UIProvider defaults>`. Do not repeat `size`, `radius` or `tone` on every `<Button>`; pass a prop only where one instance differs.
- Configure components through props (`variant`, `tone`, `size`, `loading`, `leftIcon`, `classNames`) before adding classes. A busy button is `<Button loading loadingText="Saving">`, never a hand-made spinner.

## Design tokens

- Semantic classes only. Surfaces: `bg-background`, `bg-surface`, `bg-card`, `bg-popover`. Hover and soft fills: `bg-foreground/5`. Text: `text-foreground`, `text-muted-foreground`. Lines: `border-border`. Colored text: `text-success-soft-foreground` and the other tones.
- No hex, rgb or Tailwind palette colors (`bg-blue-500`) in app code. No `bg-accent` or `bg-secondary`: use `variant="soft"` or `bg-foreground/5`.
- Tone is neutral by default. `tone="brand"` is for the one main action on a screen.
- Radius: controls take it from their `radius` prop; cards and menus use `rounded-2xl`, dialogs `rounded-3xl`.

## Every screen

- Check it at 390px and 1440px wide, in light and dark mode.
- Dialogs, menus and selects turn into bottom sheets below 768px on their own. Never force a desktop popover on a phone.

## Never

- Never edit `components/ui/*` to restyle one screen; pass props or `className` from the screen.
- Never run `npx wingo-ui@latest update` or `add --overwrite` without asking first.

A few choices in there are deliberate:

• It names commands and tools, never a component's props. Props change with releases; info and get_component always return the current ones.
• Every rule is checkable. Anthropic's guide uses the same test: "Use 2-space indentation" instead of "Format code properly". For UI, bg-surface for raised panels instead of "follow the design system".
• It explains the shadcn habits. shadcn/ui uses bg-accent for highlighted menu items and bg-secondary for its secondary button, so an agent that has read a lot of shadcn code reaches for both. The rule names them and gives the replacement. The Dialog rule works the same way: the component already switches to a sheet below 768px, so the rule tells the agent to leave that behavior alone.
• Long docs are linked, never imported. Our own AGENTS.md says "Read docs/DESIGN.md before building anything." That file is 614 lines and about 52 KB. An @docs/DESIGN.md import would load all of it into every Claude Code session, and on its own it exceeds the 32 KiB Codex allows for all instruction files together.

Why put component defaults in code instead of the rules file?

Because an agent can skip a rule, and it cannot skip a default. Anthropic's docs say it directly: Claude "treats them as context, not enforced configuration", and CLAUDE.md content arrives as a user message after the system prompt. A default set in code applies whether or not the agent read the rule.

In Wingo UI that place is the UIProvider. Every component reads app-wide defaults through useDefaults under its data-slot name, so one object in the root layout changes every Button. Explicit props win, then the provider, then the component's own defaults:

// app/layout.tsx
import type { ReactNode } from "react";
import { UIProvider } from "@/lib/ui-config";
import "./globals.css";

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <UIProvider locale="en-US" defaults={{ button: { size: "lg", radius: "full" } }}>
          {children}
        </UIProvider>
      </body>
    </html>
  );
}

Now the shortest code an agent can write is also the correct code:

import { Button } from "@/components/ui/button";

export function ProfileActions({ saving, onSave }: { saving: boolean; onSave: () => void }) {
  return (
    <div className="flex gap-2">
      {/* large and fully rounded from the provider */}
      <Button variant="outline">Cancel</Button>
      <Button tone="brand" loading={saving} loadingText="Saving" onClick={onSave}>
        Save changes
      </Button>
      {/* an explicit prop still wins */}
      <Button variant="ghost" size="sm">
        Preview
      </Button>
    </div>
  );
}

The demo below shows the same Button twice: once with no provider, once inside a UIProvider whose defaults set the size, the radius and the tone. In the demo, the top "Save changes" is medium, neutral and softly rounded, and the pair below it, "Save changes" and an outline "Cancel", is large, pill-shaped and orange.

The demo sets the brand tone to make the change obvious. In a real app, keep the neutral default and save brand for the one main action, as the rules file says.

The same split applies to variants. The rule "no bg-secondary, use variant="soft"" only works because the soft variant already exists, with its own tint in both themes and a loading state that keeps its width.

At rest, that demo is one soft gray "Save draft" button. The colors behind every tone come from Tones, which is why the rules file can say "tone" and never a color.

How should you write Cursor rules for React and Tailwind?

Write them only for what AGENTS.md cannot do: attach rules to a glob. Cursor already reads AGENTS.md, so a rule that repeats it only doubles the text in context.

Cursor's rules docs set a few hard facts. Project rules must use the .mdc extension; a plain .md file in .cursor/rules is ignored. The frontmatter decides when a rule loads: alwaysApply: true for every chat, globs to attach it when a matching file is in context, a description alone to let the agent decide, and none of them to load it only when you @-mention it.

In a React and Tailwind project, one scoped rule is usually enough: the one for edits to the component source itself. Those files are the riskiest place for an agent to tidy up: a refactor that drops one useDefaults call quietly cuts that component off from the app-wide defaults.

---
description: Rules for editing the Wingo UI source files in components/ui
globs: ["components/ui/**/*.tsx"]
alwaysApply: false
---

- These files are library source that `npx wingo-ui@latest update` merges into. Keep edits small, and keep `cn()`, the `className` prop, every `data-slot` attribute and any license header comment.
- Keep the `useDefaults("<slot>", props)` call at the top of each component, so `<UIProvider defaults>` keeps working.
- `ref` is a regular prop in React 19; never add `forwardRef`.
- Before changing a file, run `npx wingo-ui@latest diff <slug>` to see your local edits against upstream.

Claude Code's version goes in .claude/rules/ui-kit.md. It reads only the paths field from a rule's frontmatter and ignores the rest, so the header changes and the body stays the same:

---
paths:
  - "components/ui/**/*.tsx"
---

(the same four bullets)

What about nested AGENTS.md files?

They behave differently in each tool, which is why we scope UI rules with globs instead. Cursor combines a nested AGENTS.md with its parents, and the more specific one wins. Codex builds its chain once at startup, from the Git root down to the launch directory, so a components/ui/AGENTS.md applies only when you start Codex inside that folder. Claude Code reads a subfolder's AGENTS.md when it opens a file there, but only while no CLAUDE.md is in play. With the root CLAUDE.md from the setup above, it reads CLAUDE.md files only, so you would need a components/ui/CLAUDE.md that imports the AGENTS.md next to it.

Which AGENTS.md best practices matter for UI work?

The AGENTS.md best practices that hold up across all three tools are about size, precision and enforcement:

1. Keep it small. Claude Code's docs target under 200 lines per file and warn at startup when a file runs long. Codex stops adding files once the combined size reaches 32 KiB by default (project_doc_max_bytes raises it). Cursor suggests keeping each rule under 500 lines. Ours is 68 lines and about 14 KB.
2. Add a rule after the second mistake. Anthropic suggests adding to CLAUDE.md when "Claude makes the same mistake a second time", and Cursor's docs say to add rules "only when you notice Agent making the same mistake repeatedly". Rules written in advance tend to cover problems the agent never has.
3. Give the reason for surprising rules. Our AGENTS.md says never to use rounded-sm, rounded-md, rounded-lg or rounded-xl in new code, "the legacy 6px --radius turns them into 2 / 4 / 6 / 10px". A rule with its reason is one an agent can apply to cases you did not list, and one a teammate will not delete as superstition.
4. Remove contradictions. If two instructions conflict, Anthropic's docs say Claude "may pick one arbitrarily". Cursor merges Team, Project and User Rules, and the earlier source wins a conflict. One shared file is the easiest way to keep them consistent.
5. Enforce what must never break. A rule the agent can skip needs a check it cannot skip. The color rules above fit in a short script that CI and the agent both run:

#!/usr/bin/env sh
# scripts/check-tokens.sh: fail when app code bypasses the design tokens
# components/ui, components/blocks and components/templates are library source with their own color defaults
PATTERN='#[0-9a-fA-F]{6}|-(slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-[0-9]{2,3}|bg-(accent|secondary)'
if git grep --untracked -nE "$PATTERN" -- 'app/*.tsx' 'components/*.tsx' \
  ':!components/ui' ':!components/blocks' ':!components/templates'; then
  echo "Use semantic tokens and component props instead (see AGENTS.md)."
  exit 1
fi

Add "check:tokens": "sh scripts/check-tokens.sh" to package.json and the rules file can name it. Two details matter here. --untracked makes git grep read the files the agent just created, which a plain git grep skips until they are added. And the library folders stay out of the scan because Wingo UI blocks keep hex colors as overridable prop defaults, so a project-wide grep fails the day you install one. For actions that must be blocked, such as a command that overwrites files, Claude Code's docs point to a PreToolUse hook or permission settings, which apply whatever the model decides.

Where should I start?

Create AGENTS.md from the file above, trimmed to what your project needs, add a CLAUDE.md that starts with @AGENTS.md, and add one scoped rule per tool only when an agent keeps getting a folder wrong. Then move every default you find yourself repeating in prose into code.

If you use Wingo UI, npx wingo-ui@latest agents install claude codex cursor writes a Claude Code skill, our marked block in CLAUDE.md and AGENTS.md, a Cursor rule and the MCP configs, and the coding agents docs list every file it touches. The Button, the Dialog and the UIProvider from this post are free. The component library MCP guide covers the server side of the same setup, and the Claude Code shadcn setup shows the CLAUDE.md block for a project that runs two registries.

FAQ

Does Claude Code read AGENTS.md?

Yes, since v2.1.277, but by default only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or any directory above it. To cover every session, add a CLAUDE.md whose first line is @AGENTS.md.

Should I symlink CLAUDE.md to AGENTS.md or import it?

Import it with @AGENTS.md. The import leaves room for Claude-only lines below it and works on Windows, where Git checks a committed symlink out as a plain text file unless core.symlinks is enabled.

Does Cursor read AGENTS.md or CLAUDE.md?

Cursor reads AGENTS.md in the project root and in subdirectories, and combines nested files with their parents. As of October 2026 its rules docs do not mention CLAUDE.md, so keep shared rules in AGENTS.md.

How long should AGENTS.md be?

As short as you can make it. Anthropic targets under 200 lines per CLAUDE.md, Cursor suggests keeping each rule under 500 lines, and Codex stops adding instruction files once their combined size reaches 32 KiB by default.

Where do Cursor rules go and which extension do they need?

In .cursor/rules, with the .mdc extension; Cursor ignores a plain .md file in that folder. The description, globs and alwaysApply fields decide whether a rule loads in every chat, for matching files, when the agent finds it relevant, or only when you mention it.

Do I still need an MCP server if I have a rules file?

For a component library, you need something that supplies current facts. The rules file says what to do and rarely changes; an MCP server, or a CLI with search and info commands, returns what changes with every release, such as props, defaults and available updates.