AGENTS.md neben CLAUDE.md, ein Repo-Kontext fuer mehrere AI-Tools

Du hast eine saubere CLAUDE.md. Dein Setup läuft. Dann steigt ein Kollege ein, der mit Codex arbeitet. Eine Woche später probiert jemand Cursor. Plotzlich erklaerst du dreimal die gleichen Setup-Commands, einmal pro Tool, in unterschiedlichen Config-Files. AGENTS.md löst das. Ein File, das von Claude Code, Codex, Cursor, Gemini CLI, Aider, Continue und VS Code Copilot gelesen wird. Laut agents.md nutzen es über 60.000 Open-Source-Projekte. Dieses Playbook zeigt, wie du AGENTS.md zusätzlich zu deinem CLAUDE.md aufsetzt, ohne dass du Inhalt doppelt pflegen musst.

Schritt 1: Verstehen was AGENTS.md eigentlich ist

AGENTS.md ist eine offene Konvention, kein Anthropic-Feature und kein Cursor-Feature. Das File liegt im Repo-Root und enthaelt das, was ein AI-Coding-Tool wissen muss, um vernuenftig in dem Projekt zu arbeiten. Setup-Commands, Test-Commands, Code-Style, PR-Regeln. Die Idee kommt aus dem OpenAI-Codex-Umfeld und hat sich 2025 und 2026 verbreitet, weil jeder Tool-Anbieter sonst seinen eigenen Config-File-Namen erfunden hätte.

Wichtig zu wissen: AGENTS.md ist nicht magisch. Es ist nur eine Datei, die Tools lesen, weil sie den Namen erkennen. Claude Code liest sie nicht automatisch (es liest CLAUDE.md), aber wenn du in deiner CLAUDE.md einen Verweis einbaust, kommt Claude trotzdem dran. Mehr dazu in Schritt 7.

Schritt 2: Wann lohnt sich AGENTS.md zusätzlich

Wenn nur du allein mit Claude Code arbeitest und nie ein anderes Tool anfasst, kannst du AGENTS.md weglassen. CLAUDE.md reicht.

Sobald aber mindestens einer dieser Punkte zutrifft, lohnt sich der zweite File:

• Mehrere Leute im Team nutzen unterschiedliche AI-Tools (Codex, Cursor, Copilot)
• Du hast Open-Source-Code und willst, dass externe Beitraeger mit ihrem eigenen Setup direkt loslegen
• Du wechselst selbst manchmal zwischen Tools (z.B. Claude Code daily, Codex in der CI)
• Dein Repo wird von Auto-Coding-Bots wie Sourcegraph Cody oder Copilot Coding Agent benutzt

Im StudioMeyer-Repo nutzen wir beides. CLAUDE.md für die Claude-spezifischen Hooks, Skills und Memory-Hinweise. AGENTS.md für alles, was tool-agnostisch ist: Build-Commands, Test-Setup, PR-Regeln.

Schritt 3: Layout entscheiden, ein File oder mehrere

AGENTS.md kann an mehreren Stellen im Repo liegen. Im Root gilt es global. In einem Unterverzeichnis ueberschreibt es das Root-File für Dateien in diesem Verzeichnis. Für Monorepos ist das wichtig.

Für ein normales Single-Package-Repo: ein AGENTS.md im Root reicht.

Für ein Monorepo mit mehreren Packages: ein AGENTS.md im Root mit den globalen Setup-Commands, plus pro Workspace ein AGENTS.md mit den Package-spezifischen Hinweisen. Mehr dazu in Schritt 9.

Schritt 4: Den ersten AGENTS.md anlegen

Im Repo-Root:

touch AGENTS.md
git add AGENTS.md

Struktur die sich bewaehrt hat:

# Project Name

Kurzer Satz was das Repo ist.

## Setup commands

- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`

## Code style

- TypeScript strict mode
- Single quotes, no semicolons
- Functional patterns wo moeglich

## Testing instructions

- Vitest mit `pnpm test`
- Fokus auf eine Test-Datei: `pnpm vitest run -t "test name"`
- CI laeuft in .github/workflows/test.yml

## PR instructions

- Title-Format: `[scope] short description`
- Vor jedem Commit: `pnpm lint && pnpm test`
- Squash-Merges only

Das ist das Skelett. Kürzer als CLAUDE.md normalerweise, weil es nur die tool-agnostischen Sachen enthaelt.

Schritt 5: Setup-Commands und Test-Commands sauber eintragen

Hier liegt der Knackpunkt. Wenn ein neues AI-Tool deinen Repo anfasst, ist der erste Befehl, den es absetzt, fast immer install + test. Steht das nicht klar in AGENTS.md, raet das Tool. Manchmal richtig, oft falsch.

Konkretes Beispiel aus unserem Academy-Repo. Vor AGENTS.md probierten neue Tools meist npm install (wir nutzen pnpm). Drei Minuten verschwendet, dann packed-lockfile-Konflikt. Mit AGENTS.md steht in Zeile zwei pnpm install, und das Tool startet richtig.

Sei explizit. Statt "tests laufen lassen" lieber den vollen Befehl mit der Datei oder dem Filter, falls relevant:

- Run all tests: `pnpm test`
- Run academy lessons tests only: `pnpm test:lessons`
- Skip e2e tests in CI fast-lane: `SKIP_E2E=1 pnpm test`

Schritt 6: Code-Style und PR-Regeln dokumentieren

Code-Style ist der Bereich, in dem AI-Tools am meisten Murks machen, wenn er nicht dasteht. Single-Quote vs Double-Quote. Semikolons. Tabs vs Spaces. Functional vs OO.

Schreib es konkret, mit einem ja/nein-Beispiel wenn möglich:

## Code style

- TypeScript strict mode, kein `any`
- Single quotes only: `const x = 'hello'` nicht `const x = "hello"`
- Keine Semikolons am Statement-Ende
- Async/await statt `.then()`-Chains
- Named exports, kein default-export

Ein anderes Tool-Team kann sich daran sofort halten. Mit "use clean code" allein eher nicht.

PR-Regeln sollten enthalten: Title-Format, Pflicht-Checks vor dem Commit, Merge-Strategy. Wenn du eine PR-Template-Datei hast, verweise darauf statt das Template hier zu duplizieren.

Schritt 7: CLAUDE.md anpassen damit nichts doppelt steht

Jetzt der kritische Schritt. Du willst keine Drift zwischen AGENTS.md und CLAUDE.md. Wenn die Setup-Commands in AGENTS.md geaendert werden und CLAUDE.md noch die alten enthaelt, lernst du das beim nächsten Bug.

Die saubere Lösung: CLAUDE.md verweist am Anfang auf AGENTS.md.

# Claude Code Instructions

Lies zuerst @AGENTS.md, da stehen alle Setup-, Test- und Code-Style-Regeln.

Ergaenzungen speziell fuer Claude Code:

- Memory-Layer: studiomeyer-memory MCP-Server
- Hooks: siehe .claude/settings.json
- ...

Das @AGENTS.md ist eine Claude-Code-spezifische Referenz, die das File inkludiert. Damit hast du die Inhalte einmal an einer Stelle und ergaenzt in CLAUDE.md nur das, was wirklich Claude-Code-spezifisch ist (Hooks, Skills, Memory-Setup, Plan-Mode-Hinweise).

Mehr Details dazu im Companion-Playbook Claude Code im Team CLAUDE.md gemeinsam pflegen.

Schritt 8: Single-Source-of-Truth oder Symlink

Falls dein Team es einfacher findet, kannst du CLAUDE.md auch als Symlink auf AGENTS.md anlegen. Dann ist es technisch die gleiche Datei, und Claude Code liest CLAUDE.md, Codex liest AGENTS.md, alle haben das gleiche Bild.

ln -s AGENTS.md CLAUDE.md
git add CLAUDE.md

Nachteil: du kannst keine claude-spezifischen Ergaenzungen mehr machen, ohne dass sie auch für andere Tools sichtbar sind. Wenn das für dich passt, ist es der bequemste Weg. Wenn nicht, bleib bei zwei separaten Files mit Verweis (Schritt 7).

Im StudioMeyer-Repo haben wir uns gegen den Symlink entschieden, weil unsere CLAUDE.md auch Memory-Hooks-Hinweise enthaelt, die für Cursor-Nutzer irrelevant sind. Zwei Files, sauber getrennt, AGENTS.md ist das Master.

Schritt 9: Monorepo, AGENTS.md pro Workspace

Wenn du ein Monorepo mit pnpm-Workspaces, Turborepo oder Nx hast, hast du das Problem, dass der Root-AGENTS.md alleine zu generisch wird. Lösung: schichten.

Im Root: globale Sachen.

# Monorepo Root

## Setup

- `pnpm install` im Root
- Apps in `apps/`, Packages in `packages/`
- Wechsel in den Workspace bevor du was baust: `cd apps/web`

In jedem Workspace ein eigenes AGENTS.md mit den Package-spezifischen Befehlen.

# apps/web/AGENTS.md

## Setup

- `pnpm dev` startet Next.js auf Port 3000
- DB-Migrationen: `pnpm prisma migrate dev`

## Testing

- Unit-Tests: `pnpm test`
- e2e: `pnpm e2e` (braucht laufende DB)

Die meisten AI-Tools lesen beide. Erst das nähere AGENTS.md, dann das im Root als Fallback. Damit hast du Kontext genau dort, wo der Agent gerade arbeitet, und vermeidest, dass das Root-File aufblaeht.

Schritt 10: Was als nächstes

Wenn AGENTS.md einmal steht, ist die Pflege simpel. Bei jedem neuen Setup-Schritt, jedem geaenderten Test-Befehl, jeder neuen Lint-Regel: rein ins File, comitten, fertig. Das ist die gleiche Disziplin wie bei der README, nur mit einem anderen Adressaten.

Drei Folge-Themen die sich lohnen:

Wenn du parallel mehrere Branches mit Claude Code bedienst, hilft Git Worktrees. Pro Worktree eine eigene Claude-Session, kein Stash-Chaos. Siehe Claude Code mit Git Worktrees.

Wenn dein Team an einem geteilten CLAUDE.md schraubt und das in PR-Reviews regelmäßig in Konflikte läuft, schau dir Claude Code im Team an.

Und wenn du dich tiefer in die offizielle AGENTS.md-Spec einlesen willst, der Einstieg liegt auf https://agents.md/ inklusive Beispielen von 60.000+ Repos.

Ein File. Mehrere Tools. Weniger Erklären.