# AGENTS.md vs CLAUDE.md vs Cursor-Regeln für React

> AGENTS.md vs CLAUDE.md vs Cursor-Regeln für React und Tailwind: wer welche Datei liest (Oktober 2026) und eine Regeldatei, die Agenten bei deinen Tokens hält.

- Autor: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Veröffentlicht: 9. Okt. 2026
- Kategorie: [UI mit KI-Agenten bauen](https://wingo-ui.com/de/blog/category/ai-agents)
- Lesezeit: 14 Min.
- Kanonische URL: https://wingo-ui.com/de/blog/agents-md-vs-claude-md-react
- Englische Fassung: https://wingo-ui.com/blog/agents-md-vs-claude-md-react

## Kurz gesagt

Schreib deine Regeln einmal in die AGENTS.md, die Codex, Cursor und Claude Code alle lesen, und leg eine CLAUDE.md an, die mit @AGENTS.md beginnt, denn Claude Code überspringt die AGENTS.md standardmäßig, sobald eine CLAUDE.md existiert. Nutze .mdc-Regeln in Cursor und Pfadregeln in Claude Code nur für Anweisungen, die zu einem einzelnen Ordner gehören. Für ein Design System mit React und Tailwind hältst du die Datei kurz und prüfbar, verlinkst lange Docs statt sie einzufügen und legst Komponenten-Defaults in den Code, wo ein Agent sie nicht überspringen kann.

Du hast Claude Code zu einem React-Projekt hinzugefügt, das schon Cursor-Regeln hatte, ein Kollege nutzt Codex, und jetzt liegen im Repo drei Anweisungsdateien, die sich bei den Button-Größen widersprechen. Dahinter steckt die Frage AGENTS.md vs CLAUDE.md: Welche Datei liest jeder Agent wirklich, und wo sollten die Regeln deines Design Systems stehen, damit sich jeder Agent daran hält? Dieser Artikel beantwortet das mit den Laderegeln aus der Dokumentation jedes Tools, Stand Oktober 2026, mit dem Aufbau, den Next.js 16.3 jetzt für dich schreibt, und mit einer Regeldatei nach dem Vorbild unseres eigenen Repos, die Agenten bei deinen Design Tokens hält.

Wir bauen Wingo UI, eine React-Komponentenbibliothek, deshalb nutzen die Beispiele unseren [Button](https://wingo-ui.com/components/button) und den [UIProvider](https://wingo-ui.com/components/ui-config). Der Dateiaufbau funktioniert in jedem Projekt mit React und Tailwind CSS. Weitere Guides zu Agenten und UI findest du unter [UI mit KI-Agenten bauen](https://wingo-ui.com/de/blog/category/ai-agents).

## Was ist der Unterschied zwischen AGENTS.md und CLAUDE.md?

Die AGENTS.md ist die gemeinsame, toolneutrale Anweisungsdatei, die Codex, Cursor und die meisten anderen Agenten lesen. Die CLAUDE.md ist die eigene Datei von Claude Code, mit Imports, persönlichen und organisationsweiten Ebenen und pfadbezogenen Regeln daneben. Beide enthalten einfache Markdown-Anweisungen; der Unterschied liegt darin, wer welche Datei liest und was der Loader damit macht.

**AGENTS.md** ist ein offenes Format, das die Agentic AI Foundation unter dem Dach der Linux Foundation betreut. Die [Website agents.md](https://agents.md/) nennt Codex, Cursor, Gemini CLI, den Coding-Agent von GitHub Copilot, Jules, Zed, Windsurf und weitere Tools, die sie lesen, und spricht von mehr als 60.000 Open-Source-Projekten, die sie nutzen. Pflichtfelder gibt es keine. Die Vorrangregel ist kurz: Die AGENTS.md, die der bearbeiteten Datei am nächsten liegt, gewinnt, und ein ausdrücklicher Prompt im Chat schlägt alles.

**CLAUDE.md** ist die Memory-Datei von Claude Code. Es gibt sie in vier Ebenen: eine Policy-Datei der Organisation, `~/.claude/CLAUDE.md` für dich, `./CLAUDE.md` fürs Team und `CLAUDE.local.md` für deine privaten Notizen. Sie unterstützt `@path`-Imports bis zu vier Ebenen tief und hat einen Begleitordner, `.claude/rules/`, dessen Dateien sich auf Pfade beschränken lassen.

**Cursor-Regeln** sind `.mdc`-Dateien in `.cursor/rules` mit Frontmatter, das bestimmt, wann jede davon lädt. Cursor liest außerdem die AGENTS.md.

## Welche Datei liest welcher Agent?

Jedes Tool liest seine eigene Datei, und alle drei lesen die AGENTS.md in irgendeiner Form. So funktioniert das Laden, Stand Oktober 2026:

| Merkmal | Claude Code | Codex | Cursor |
| --- | --- | --- | --- |
| Liest | `CLAUDE.md`, `.claude/CLAUDE.md`, `CLAUDE.local.md`, `.claude/rules/*.md` | `AGENTS.md`; eine `AGENTS.override.md` im selben Ordner ersetzt sie | `.cursor/rules/*.mdc`, `AGENTS.md`, User Rules, Team Rules |
| AGENTS.md | Seit v2.1.277, nur wenn im Arbeitsverzeichnis oder darüber keine `CLAUDE.md`, `.claude/CLAUDE.md` oder `CLAUDE.local.md` existiert | Nativ | Stammordner und Unterordner, verschachtelte Dateien kombiniert |
| Regeln mit Geltungsbereich | `.claude/rules/*.md` mit einer `paths`-Liste | Eine Datei pro Ordner, vom Git-Root bis zum Startverzeichnis | `.mdc`-Dateien mit `globs` oder einer `description` |
| Imports | `@path`, bis zu 4 Ebenen | Keine dokumentiert | `@file`-Erwähnungen, bei Bedarf gelesen, nicht eingefügt |
| Größe | Unter 200 Zeilen pro Datei | 32 KiB für alle Dateien zusammen | Unter 500 Zeilen pro Regel |

Quellen, geprüft am 9. Oktober 2026: die [Memory-Docs von Claude Code](https://code.claude.com/docs/en/memory), der [AGENTS.md-Guide von Codex](https://learn.chatgpt.com/docs/agent-configuration/agents-md), die [Rules-Docs von Cursor](https://cursor.com/docs/context/rules) und [agents.md](https://agents.md/). Gemini CLI liest standardmäßig die `GEMINI.md` und liest die AGENTS.md, sobald du sie in `context.fileName` in der `settings.json` einträgst, so die [GEMINI.md-Docs](https://geminicli.com/docs/cli/gemini-md/).

Zwei Details in dieser Tabelle entscheiden über die meisten Setups. Codex dokumentiert keine Import-Syntax und baut seine Kette einmal beim Start auf. Alles, was Codex wissen soll, muss also in einer AGENTS.md auf dem Weg vom Git-Root bis zu deinem Startordner stehen oder in deiner globalen Datei in `~/.codex`. Cursor-Regeln erreichen nur den Agent: Laut den [Rules-Docs von Cursor](https://cursor.com/docs/context/rules) wirken sie weder auf Cursor Tab noch auf andere KI-Funktionen.

## Liest Claude Code jetzt die AGENTS.md?

Ja, seit v2.1.277, mit einer Bedingung, über die viele stolpern: Standardmäßig liest Claude Code die AGENTS.md nur, wenn im Arbeitsverzeichnis oder einem Ordner darüber keine `CLAUDE.md`, `.claude/CLAUDE.md` oder `CLAUDE.local.md` existiert. Deine `~/.claude/CLAUDE.md` und die Dateien in `.claude/rules/` zählen bei dieser Prüfung nicht mit.

Die Falle ist `CLAUDE.local.md`. Verlässt sich ein Repo allein auf die AGENTS.md und legt ein Kollege dort eine für private Notizen an, schaltet er die AGENTS.md für seine eigenen Sessions ab. Ein Tool, das eine `CLAUDE.md` anlegt, tut dasselbe für alle. Mit `/memory` siehst du, welche Dateien geladen wurden. Willst du beide Dateien lesen lassen, setz **Project instructions** in `/config` auf `claude-md-and-agents-md`.

Manche Sessions können die AGENTS.md gar nicht direkt lesen: Versionen vor v2.1.277, Sessions, in denen das eingebaute Plugin zum Lesen deaktiviert ist, und in manchen Fällen die erste Session nach einem Upgrade. Außerdem liest Claude Code nie `AGENTS.override.md` oder `AGENTS.local.md`. Ein Import funktioniert in all diesen Fällen, deshalb nutzen wir einen.

## Welches Setup funktioniert für Claude Code, Codex und Cursor zugleich?

Mach die AGENTS.md zur einzigen Quelle der Wahrheit und gib Claude Code eine CLAUDE.md, die sie importiert. Codex und Cursor lesen die AGENTS.md nativ, und Claude Code liest sie über den Import, egal mit welcher Version oder welchen Einstellungen.

```text
your-app/
├── AGENTS.md                  # jede Regel, die jeder Agent braucht
├── CLAUDE.md                  # @AGENTS.md, dann Zeilen nur für Claude
├── .claude/rules/ui-kit.md    # Claude Code: lädt, wenn es Dateien in components/ui liest
└── .cursor/rules/ui-kit.mdc   # Cursor: hängt sich an, wenn Dateien aus components/ui im Kontext sind
```

Die CLAUDE.md bleibt winzig. Claude liest zuerst die importierte Datei, dann die Zeilen darunter:

```md
@AGENTS.md

## Nur für Claude Code

- Nutze den Plan-Modus, bevor du mehr als eine Datei in `components/ui` änderst.
```

Genau diesen Aufbau schreibt Next.js inzwischen selbst. `create-next-app` legt beide Dateien an, und ab Next.js 16.3 ergänzt `next dev` sie in einem bestehenden Projekt, wenn es einen Coding-Agent erkennt und keinen verwalteten Block findet. Die AGENTS.md bekommt einen verwalteten Block, der Agenten anweist, die mitgelieferten Docs in `node_modules/next/dist/docs/` zu lesen, und die CLAUDE.md bekommt die einzige Zeile `@AGENTS.md`. Text außerhalb der Markierungen des Blocks übersteht Updates, und `agentRules: false` in `next.config.ts` schaltet die Generierung ab ([Next.js-Guide zu KI-Agenten](https://nextjs.org/docs/app/guides/ai-agents)). Unser eigenes Repository nutzt dasselbe Setup: Die CLAUDE.md ist genau diese eine Zeile, und die AGENTS.md hat 68 Zeilen, den Next.js-Block eingerechnet.

Dass die gemeinsamen Regeln in einer Datei stehen, die immer geladen wird, ist wichtiger, als es aussieht. In [AGENTS.md outperforms skills in our agent evals](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals) (Jude Gao, Vercel, 27. Januar 2026) bestand ein 8 KB großer Docs-Index in der AGENTS.md 100 % einer Eval-Suite für Next.js 16, gegenüber 79 % für einen Skill mit ausdrücklicher Anweisung, ihn zu nutzen, und 53 % ganz ohne Docs. Ohne diese Anweisung rief der Agent den Skill in 56 % der Fälle nie auf.

Ein Symlink (`ln -s AGENTS.md CLAUDE.md`) funktioniert ebenfalls, solange du keine Zeilen nur für Claude hast. Die Docs von Anthropic nennen den Haken: Unter Windows checkt Git einen committeten Symlink als normale Textdatei aus, solange `core.symlinks` nicht aktiviert ist, und dieser Klon hat dann eine einzeilige CLAUDE.md. Beim Import gibt es dieses Problem nicht.

Eine Eigenheit unserer eigenen CLI: `npx wingo-ui@latest agents install claude codex` schreibt denselben markierten Block, etwa 1 KB groß, in die CLAUDE.md und in die AGENTS.md, sodass Claude ihn mit dem Import zweimal liest. Die beiden Kopien sind identisch, und `agents update` schreibt beide neu, also können sie sich nicht widersprechen.

## Was sollte eine Regeldatei für React und Tailwind enthalten?

Alles, was ein Agent nicht lernt, wenn er deinen Code einmal liest: wo die Komponenten liegen und wie man sie nachschlägt, welche Tokens gelten, welche Defaults an einer Stelle gesetzt sind, welche Checks laufen müssen, und die wenigen Dinge, die er nie tun darf. Startest du mit einer CLAUDE.md für React oder mit einem AGENTS.md Beispiel aus dem Netz, streich jede Komponentenliste und jede Props-Tabelle. Diese Kopie veraltet mit dem nächsten Release, und ein Agent mit einer veralteten Tabelle hat keinen Grund, die echte Datei zu öffnen.

Hier ist eine AGENTS.md für ein Next.js-Dashboard auf Basis von Wingo UI, mit gekürztem Next.js-Block. Jeder Abschnitt beantwortet eine der Fragen oben:

```md
<!-- BEGIN:nextjs-agent-rules -->
(verwaltet von next dev: lies die Docs in node_modules/next/dist/docs/, bevor du Code schreibst)
<!-- END:nextjs-agent-rules -->

# Acme Dashboard

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

## Befehle

- Dev-Server: `npm run dev` auf http://localhost:3000. Läuft er schon, nutz ihn; starte nie einen zweiten.
- Bevor du eine Aufgabe als erledigt meldest: `npx tsc --noEmit`, `npx eslint <geänderte Dateien>`, `npm run check:tokens`.

## UI-Komponenten

- Komponenten liegen in `components/ui` (Wingo UI, als Quellcode installiert, Versionen in `wingo-ui.json`). Durchsuch sie, bevor du UI schreibst: mit den `wingo-ui`-MCP-Tools oder mit `npx wingo-ui@latest search <Begriffe>`. Schreib nie eine Komponente von Hand, die es dort gibt.
- Installier mit `npx wingo-ui@latest add <slug...>`. Lies die Props einer Komponente, bevor du sie zum ersten Mal nutzt: `get_component` oder `npx wingo-ui@latest info <slug>`.
- Das app-weite Aussehen wird einmal festgelegt, in `app/layout.tsx`, mit `<UIProvider defaults>`. Wiederhol `size`, `radius` oder `tone` nicht an jedem `<Button>`; übergib ein Prop nur dort, wo eine Instanz abweicht.
- Konfigurier Komponenten über Props (`variant`, `tone`, `size`, `loading`, `leftIcon`, `classNames`), bevor du Klassen ergänzt. Ein Button im Ladezustand ist `<Button loading loadingText="Wird gespeichert">`, nie ein selbst gebauter Spinner.

## Design Tokens

- Nur semantische Klassen. Flächen: `bg-background`, `bg-surface`, `bg-card`, `bg-popover`. Hover und weiche Füllungen: `bg-foreground/5`. Text: `text-foreground`, `text-muted-foreground`. Linien: `border-border`. Farbiger Text: `text-success-soft-foreground` und die anderen Tones.
- Keine Hex-, rgb- oder Tailwind-Palettenfarben (`bg-blue-500`) im App-Code. Kein `bg-accent` oder `bg-secondary`: nutz `variant="soft"` oder `bg-foreground/5`.
- Tone ist standardmäßig neutral. `tone="brand"` ist für die eine Hauptaktion auf einem Screen.
- Radius: Controls nehmen ihn aus ihrem `radius`-Prop; Cards und Menüs nutzen `rounded-2xl`, Dialoge `rounded-3xl`.

## Jeder Screen

- Prüf ihn bei 390px und 1440px Breite, im Light und im Dark Mode.
- Dialoge, Menüs und Selects werden unter 768px von selbst zu Bottom Sheets. Erzwing nie ein Desktop-Popover auf dem Handy.

## Niemals

- Bearbeite nie `components/ui/*`, um einen einzelnen Screen umzustylen; übergib Props oder `className` vom Screen aus.
- Führ nie `npx wingo-ui@latest update` oder `add --overwrite` aus, ohne vorher zu fragen.
```

Ein paar Entscheidungen darin sind bewusst:

- **Sie nennt Befehle und Tools, nie die Props einer Komponente.** Props ändern sich mit Releases; `info` und `get_component` liefern immer die aktuellen.
- **Jede Regel ist prüfbar.** Der Guide von Anthropic nutzt denselben Test: lieber eine konkrete Vorgabe wie Einrücken mit 2 Leerzeichen als die vage Bitte, Code ordentlich zu formatieren ([Memory-Docs](https://code.claude.com/docs/en/memory)). Für UI heißt das: `bg-surface` für erhöhte Panels statt „halte dich an das Design System“.
- **Sie erklärt die shadcn-Gewohnheiten.** shadcn/ui nutzt `bg-accent` für hervorgehobene Menüeinträge und `bg-secondary` für seinen Secondary-Button, also greift ein Agent, der viel shadcn-Code gelesen hat, zu beiden. Die Regel nennt sie und gibt den Ersatz an. Die Regel für den [Dialog](https://wingo-ui.com/components/dialog) funktioniert genauso: Die Komponente wechselt unter 768px schon von selbst zu einem Sheet, also sagt die Regel dem Agent, dieses Verhalten in Ruhe zu lassen.
- **Lange Docs werden verlinkt, nie importiert.** Unsere eigene AGENTS.md verlangt, vor jedem Bauen `docs/DESIGN.md` zu lesen. Diese Datei hat 614 Zeilen und etwa 52 KB. Ein Import mit `@docs/DESIGN.md` würde all das in jede Session von Claude Code laden, und allein überschreitet sie die 32 KiB, die Codex für alle Anweisungsdateien zusammen erlaubt.

## Warum gehören Komponenten-Defaults in den Code statt in die Regeldatei?

Weil ein Agent eine Regel überspringen kann, einen Default aber nicht. Die Docs von Anthropic sagen es direkt: Claude behandelt diese Dateien als Kontext, nicht als erzwungene Konfiguration, und der Inhalt der CLAUDE.md kommt als User-Nachricht nach dem System-Prompt an ([Memory-Docs](https://code.claude.com/docs/en/memory)). Ein im Code gesetzter Default gilt, ob der Agent die Regel gelesen hat oder nicht.

In Wingo UI ist dieser Ort der UIProvider. Jede Komponente liest app-weite Defaults über `useDefaults` unter ihrem `data-slot`-Namen, also ändert ein einziges Objekt im Root-Layout jeden Button. Explizite Props gewinnen, dann der Provider, dann die eigenen Defaults der Komponente:

```tsx
// 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>
  );
}
```

Jetzt ist der kürzeste Code, den ein Agent schreiben kann, auch der richtige:

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

export function ProfileActions({ saving, onSave }: { saving: boolean; onSave: () => void }) {
  return (
    <div className="flex gap-2">
      {/* groß und voll abgerundet durch den Provider */}
      <Button variant="outline">Abbrechen</Button>
      <Button tone="brand" loading={saving} loadingText="Wird gespeichert" onClick={onSave}>
        Änderungen speichern
      </Button>
      {/* ein explizites Prop gewinnt trotzdem */}
      <Button variant="ghost" size="sm">
        Vorschau
      </Button>
    </div>
  );
}
```

Die Demo unten zeigt denselben Button zweimal: einmal ohne Provider, einmal in einem UIProvider, dessen Defaults Größe, Radius und Tone festlegen. Oben steht ein „Save changes“ in mittlerer Größe, neutral und leicht abgerundet; das Paar darunter, „Save changes“ und ein Outline-„Cancel“, ist groß, pillenförmig und orange.

> Live-Demo (UIProvider): Der obere Button hat keinen Provider. Das Paar darunter steckt in einem UIProvider mit radius full, size lg und tone brand, also wird dasselbe Button-Markup größer, runder und orange. Probier sie unter [UIProvider](https://wingo-ui.com/components/ui-config) aus und installier sie mit `npx wingo-ui@latest add ui-config`.

Die Demo setzt den Brand-Tone, damit der Unterschied sofort auffällt. In einer echten App behältst du den neutralen Default und hebst Brand für die eine Hauptaktion auf, wie es die Regeldatei sagt.

Dieselbe Aufteilung gilt für Varianten. Die Regel „kein `bg-secondary`, nutz `variant="soft"`“ funktioniert nur, weil es die Soft-Variante schon gibt, mit eigener Tönung in beiden Themes und einem Ladezustand, der ihre Breite hält.

> Live-Demo (Button): Klick auf Save draft: Die Soft-Variante zeigt einen Spinner und „Saving“ statt des Labels, in derselben Breite, und ignoriert Klicks, bis sie fertig ist. Probier sie unter [Button](https://wingo-ui.com/components/button) aus und installier sie mit `npx wingo-ui@latest add button`.

Im Ruhezustand ist diese Demo ein einzelner, dezent grauer Button „Save draft“. Die Farben hinter jedem Tone kommen aus [Tones](https://wingo-ui.com/components/tones), deshalb kann die Regeldatei „Tone“ sagen und nie eine Farbe.

## Wie schreibst du Cursor Rules für React und Tailwind?

Schreib sie nur für das, was die AGENTS.md nicht kann: Regeln an ein Glob hängen. Cursor liest die AGENTS.md ohnehin. Eine Regel, die sie wiederholt, verdoppelt nur den Text im Kontext.

Die Rules-Docs von Cursor legen ein paar harte Fakten fest. Projektregeln brauchen die Endung `.mdc`; eine normale `.md`-Datei in `.cursor/rules` wird ignoriert. Das Frontmatter entscheidet, wann eine Regel lädt: `alwaysApply: true` für jeden Chat, `globs`, damit sie sich anhängt, wenn eine passende Datei im Kontext ist, eine `description` allein, damit der Agent entscheidet, und nichts davon, damit sie nur lädt, wenn du sie per @ erwähnst.

In einem Projekt mit React und Tailwind reicht meist eine einzige Regel mit Geltungsbereich: die für Änderungen am Quellcode der Komponenten selbst. In diesen Dateien ist das Aufräumen durch einen Agent am riskantesten: Ein Refactoring, das einen einzigen `useDefaults`-Aufruf entfernt, schneidet diese Komponente unbemerkt von den app-weiten Defaults ab.

```md
---
description: Regeln für das Bearbeiten der Wingo-UI-Quelldateien in components/ui
globs: ["components/ui/**/*.tsx"]
alwaysApply: false
---

- Diese Dateien sind Bibliotheksquellcode, in den `npx wingo-ui@latest update` neue Versionen einmergt. Halte Änderungen klein und behalte `cn()`, das `className`-Prop, jedes `data-slot`-Attribut und jeden Lizenzkommentar im Dateikopf.
- Behalte den Aufruf `useDefaults("<slot>", props)` am Anfang jeder Komponente, damit `<UIProvider defaults>` weiter funktioniert.
- `ref` ist in React 19 ein normales Prop; füg nie `forwardRef` hinzu.
- Bevor du eine Datei änderst, führ `npx wingo-ui@latest diff <slug>` aus, um deine lokalen Änderungen mit dem Upstream-Stand zu vergleichen.
```

Die Version für Claude Code gehört in `.claude/rules/ui-kit.md`. Claude Code liest aus dem Frontmatter einer Regel nur das Feld `paths` und ignoriert den Rest, also ändert sich der Kopf und der Inhalt bleibt gleich:

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

(dieselben vier Punkte)
```

### Was ist mit verschachtelten AGENTS.md-Dateien?

Sie verhalten sich in jedem Tool anders, deshalb begrenzen wir UI-Regeln stattdessen mit Globs. Cursor kombiniert eine verschachtelte AGENTS.md mit ihren übergeordneten, und die spezifischere gewinnt. Codex baut seine Kette einmal beim Start auf, vom Git-Root bis zum Startverzeichnis, eine `components/ui/AGENTS.md` gilt also nur, wenn du Codex in diesem Ordner startest. Claude Code liest die AGENTS.md eines Unterordners, wenn es dort eine Datei öffnet, aber nur, solange keine CLAUDE.md im Spiel ist. Mit der Root-CLAUDE.md aus dem Setup oben liest es nur CLAUDE.md-Dateien, du bräuchtest also eine `components/ui/CLAUDE.md`, die die AGENTS.md daneben importiert.

## Welche AGENTS.md Best Practices zählen für UI-Arbeit?

Die AGENTS.md Best Practices, die in allen drei Tools tragen, drehen sich um Größe, Präzision und Durchsetzung:

1. **Halte sie klein.** Die Docs von Claude Code peilen weniger als 200 Zeilen pro Datei an und warnen beim Start, wenn eine Datei zu lang wird. Codex hört standardmäßig auf, Dateien hinzuzufügen, sobald sie zusammen 32 KiB erreichen (`project_doc_max_bytes` hebt das an). Cursor empfiehlt, jede Regel unter 500 Zeilen zu halten. Unsere hat 68 Zeilen und etwa 14 KB.
2. **Ergänz eine Regel nach dem zweiten Fehler.** Anthropic rät, die CLAUDE.md zu erweitern, wenn Claude denselben Fehler ein zweites Mal macht ([Memory-Docs](https://code.claude.com/docs/en/memory)), und die [Rules-Docs von Cursor](https://cursor.com/docs/context/rules) empfehlen Regeln erst dann, wenn der Agent denselben Fehler immer wieder macht. Vorab geschriebene Regeln decken oft Probleme ab, die der Agent nie hat.
3. **Begründe überraschende Regeln.** Unsere AGENTS.md verbietet `rounded-sm`, `rounded-md`, `rounded-lg` und `rounded-xl` in neuem Code und nennt den Grund gleich mit: Der alte `--radius` von 6px macht daraus 2 / 4 / 6 / 10px. Eine Regel mit Begründung kann ein Agent auch auf Fälle anwenden, die du nicht aufgezählt hast, und ein Kollege löscht sie nicht als Aberglauben.
4. **Beseitige Widersprüche.** Widersprechen sich zwei Anweisungen, kann Claude laut den Docs von Anthropic willkürlich eine davon wählen. Cursor führt Team, Project und User Rules zusammen, und bei einem Konflikt gewinnt die frühere Quelle. Eine gemeinsame Datei ist der einfachste Weg, sie konsistent zu halten.
5. **Setz durch, was nie brechen darf.** Eine Regel, die der Agent überspringen kann, braucht einen Check, den er nicht überspringen kann. Die Farbregeln oben passen in ein kurzes Skript, das sowohl die CI als auch der Agent ausführt:

```sh
#!/usr/bin/env sh
# scripts/check-tokens.sh: schlägt fehl, wenn App-Code die Design Tokens umgeht
# components/ui, components/blocks und components/templates sind Bibliotheksquellcode mit eigenen Farb-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 "Nutze stattdessen semantische Tokens und Komponenten-Props (siehe AGENTS.md)."
  exit 1
fi
```

Ergänz `"check:tokens": "sh scripts/check-tokens.sh"` in der `package.json`, dann kann die Regeldatei den Befehl nennen. Zwei Details sind hier wichtig. `--untracked` sorgt dafür, dass `git grep` auch die Dateien liest, die der Agent gerade angelegt hat; ein einfaches `git grep` überspringt sie, bis sie hinzugefügt sind. Und die Bibliotheksordner bleiben außen vor, weil Wingo-UI-Blocks Hex-Farben als überschreibbare Prop-Defaults behalten, ein projektweites grep schlägt also an dem Tag fehl, an dem du den ersten installierst. Für Aktionen, die blockiert werden müssen, etwa einen Befehl, der Dateien überschreibt, verweisen die Docs von Claude Code auf einen `PreToolUse`-Hook oder auf Permission-Einstellungen, die gelten, egal was das Modell entscheidet.

## Wo fange ich an?

Leg eine AGENTS.md nach dem Vorbild der Datei oben an, gekürzt auf das, was dein Projekt braucht, ergänz eine CLAUDE.md, die mit `@AGENTS.md` beginnt, und füg pro Tool erst dann eine Regel mit Geltungsbereich hinzu, wenn ein Agent einen Ordner immer wieder falsch behandelt. Verschieb dann jeden Default, den du in Prosa wiederholst, in den Code.

Nutzt du Wingo UI, schreibt `npx wingo-ui@latest agents install claude codex cursor` einen Skill für Claude Code, unseren markierten Block in CLAUDE.md und AGENTS.md, eine Cursor-Regel und die MCP-Konfigurationen, und die [Doku zu Coding-Agenten](https://wingo-ui.com/docs/agents) listet jede Datei auf, die der Befehl anfasst. Button, Dialog und UIProvider aus diesem Artikel sind kostenlos. Der [Guide zu MCP für Komponentenbibliotheken](https://wingo-ui.com/de/blog/component-library-mcp-guide) behandelt die Serverseite desselben Setups, und das [Claude Code shadcn Setup](https://wingo-ui.com/de/blog/claude-code-shadcn-mcp-setup) zeigt den CLAUDE.md-Block für ein Projekt mit zwei Registries. Das [Cursor shadcn Setup](https://wingo-ui.com/de/blog/cursor-shadcn-mcp-rules) macht dasselbe für Cursor, mit dem MCP-Server in `.cursor/mcp.json` und einer einzigen `.mdc`-Regel.

## Komponenten in diesem Artikel

- [Button](https://wingo-ui.com/components/button) (Free): The React button component every screen starts with: five variants, six tones, all sizes, and a loading state that never jumps. Installation: `npx wingo-ui@latest add button`
- [UIProvider](https://wingo-ui.com/components/ui-config) (Free): A React config provider for Wingo UI: app-wide default props for every component, the Intl locale and a reduced-motion policy. Installation: `npx wingo-ui@latest add ui-config`
- [Dialog](https://wingo-ui.com/components/dialog) (Free): A React modal dialog for focused tasks: a spring-scaled card on desktop and a bottom sheet on phones, with nesting and scrolling. Installation: `npx wingo-ui@latest add dialog`

## Häufige Fragen

### Liest Claude Code die AGENTS.md?

Ja, seit v2.1.277, standardmäßig aber nur, wenn im Arbeitsverzeichnis oder einem Ordner darüber keine CLAUDE.md, .claude/CLAUDE.md oder CLAUDE.local.md liegt. Damit jede Session sie lädt, leg eine CLAUDE.md an, deren erste Zeile @AGENTS.md ist.

### Soll ich CLAUDE.md per Symlink auf AGENTS.md zeigen lassen oder sie importieren?

Importier sie mit @AGENTS.md. Der Import lässt Platz für Zeilen nur für Claude darunter und funktioniert auch unter Windows, wo Git einen committeten Symlink als normale Textdatei auscheckt, solange core.symlinks nicht aktiviert ist.

### Liest Cursor die AGENTS.md oder die CLAUDE.md?

Cursor liest die AGENTS.md im Stammordner des Projekts und in Unterordnern und kombiniert verschachtelte Dateien mit den übergeordneten. Stand Oktober 2026 erwähnen die Rules-Docs von Cursor die CLAUDE.md nicht, also gehören gemeinsame Regeln in die AGENTS.md.

### Wie lang sollte eine AGENTS.md sein?

So kurz wie möglich. Anthropic peilt weniger als 200 Zeilen pro CLAUDE.md an, Cursor empfiehlt, jede Regel unter 500 Zeilen zu halten, und Codex hört standardmäßig auf, Anweisungsdateien hinzuzufügen, sobald sie zusammen 32 KiB erreichen.

### Wo liegen Cursor-Regeln und welche Dateiendung brauchen sie?

In .cursor/rules, mit der Endung .mdc; eine normale .md-Datei in diesem Ordner ignoriert Cursor. Die Felder description, globs und alwaysApply entscheiden, ob eine Regel in jedem Chat lädt, bei passenden Dateien, wenn der Agent sie für relevant hält, oder nur, wenn du sie erwähnst.

### Brauche ich noch einen MCP-Server, wenn ich eine Regeldatei habe?

Für eine Komponentenbibliothek brauchst du etwas, das aktuelle Fakten liefert. Die Regeldatei sagt, was zu tun ist, und ändert sich selten; ein MCP-Server oder eine CLI mit search- und info-Befehlen liefert, was sich mit jedem Release ändert, etwa Props, Defaults und verfügbare Updates.

---

Quelle: https://wingo-ui.com/de/blog/agents-md-vs-claude-md-react