# AGENTS.md Konfigurationshandbuch

`AGENTS.md` ist für Codex, was `CLAUDE.md` für Claude Code ist. Es handelt sich um eine Markdown-Datei in Ihrem Projekt, die dem KI-Coding-Assistenten mitteilt: welche Standards in diesem Projekt gelten, wie Code geschrieben werden soll und was vermieden werden muss.

Wenn Sie bereits `CLAUDE.md` in Claude Code verwenden, wird Ihnen das Konzept von `AGENTS.md` vertraut sein. Beide verfolgen dieselbe Philosophie, unterscheiden sich jedoch in einigen Formatdetails. Dieses Handbuch behandelt die `AGENTS.md`-Konfiguration ausführlich und zeigt, wie Sie Projektstandards effizient über beide Tools hinweg wiederverwenden können.

---

> **Es ist nicht mehr nur eine Codex-Datei.** Im März 2026 gründeten Anthropic, OpenAI, Google, AWS, Microsoft
> und Salesforce die **Agentic AI Foundation (AAIF)**, die drei offene Spezifikationen als gemeinsame Basis
> übernommen hat: **MCP** (die Tool- und Kontextschicht), **AGENTS.md** (die Agent-Verhaltensspezifikation)
> und **Goose** (die Referenzimplementierung). In der Praxis bedeutet das, dass eine einzige `AGENTS.md` von
> einer wachsenden Zahl an Tools gelesen wird, nicht nur von Codex.

## AGENTS.md vs. CLAUDE.md

Bevor Sie sich in `AGENTS.md` vertiefen, hier ein Vergleich mit `CLAUDE.md`:

| Aspekt | AGENTS.md (Codex) | CLAUDE.md (Claude Code) |
|--------|---------------------|--------------------------|
| Tool | OpenAI Codex CLI | Anthropic Claude Code |
| Dateiformat | Markdown | Markdown |
| Ladehierarchie | Global / Repo-Wurzel / Unterverzeichnis (drei Stufen) | Global / Projekt-Wurzel / Unterverzeichnis (drei Stufen) |
| Globaler Speicherort | `~/.codex/AGENTS.md` | `~/.claude/CLAUDE.md` |
| Überschreibungsmechanismus | Unterverzeichnis kann übergeordnete Regeln überschreiben | Unterverzeichnis kann Regeln ergänzen/überschreiben |
| Schreibstil | Tendiert zu knappen Listen, anweisender Stil | Unterstützt ausführliche Erklärungen, auch ein umgangssprachlicher Stil funktioniert |
| Community-Adoption | Wachsend, bereits von vielen Open-Source-Projekten übernommen | Weit verbreitet, ausgereiftes Ökosystem |
| Versionskontrolle | Empfohlen, in das Repo zu committen | Empfohlen, in das Repo zu committen |
| Gegenseitige Erkennung | Liest CLAUDE.md nicht | Liest AGENTS.md nicht |

> **Wichtig**: Die beiden Dateien sind füreinander unsichtbar. Wenn Sie beide Tools verwenden, müssen Sie `AGENTS.md` und `CLAUDE.md` getrennt pflegen. Die gute Nachricht: Der Kerninhalt kann gemeinsam genutzt werden.

---

## Grundkonfiguration

### Dateispeicherort

Erstellen Sie `AGENTS.md` in der Wurzel Ihres Projekts:

```
your-project/
  AGENTS.md          <- repo-level config
  src/
  tests/
  package.json
```

### Grundlegende Syntax

`AGENTS.md` ist eine standardmäßige Markdown-Datei. Codex liest sie beim Start und folgt den darin enthaltenen Anweisungen. Das gebräuchlichste Format sind **ungeordnete Listen**:

```markdown
# AGENTS.md

- All code should be written in TypeScript with strict mode enabled
- Use Prettier for formatting, ESLint for linting
- Tests use Vitest, placed in `__tests__/` directories
- Run `npm run lint && npm test` before completing any task
- Never modify files in the `vendor/` directory
- API responses must follow the standard envelope format: `{ code, data, message }`
```

Sie können auch Überschriften verwenden, um Regeln nach Kategorie zu gliedern:

```markdown
# AGENTS.md

## Code Standards
- Use TypeScript strict mode
- Variables use camelCase, types use PascalCase
- Each function should be no more than 50 lines

## Testing Requirements
- Unit test coverage target: 80%
- Test files share the source file name with a `.test.ts` suffix
- Mock external dependencies; no real network requests in tests

## Prohibited Practices
- Do not use the `any` type
- Do not manipulate the DOM directly (use React state management)
- Do not use `await` inside loops (use `Promise.all` instead)
```

### Sprachwahl

Der Inhalt von `AGENTS.md` kann auf **Chinesisch** oder **Englisch** verfasst werden. Codex versteht beide Sprachen korrekt. Für die Teamzusammenarbeit gilt:

- **Persönliche Projekte**: Verwenden Sie die Sprache, in der Sie sich am wohlsten fühlen
- **Teamprojekte**: Englisch wird empfohlen (konsistent mit dem Code)
- **Chinesischsprachige Teams**: Chinesisch funktioniert einwandfrei

---
## Schichtweise Konfiguration

`AGENTS.md` unterstützt drei Konfigurationsstufen, die Regeln von global bis zu spezifischen Verzeichnissen verfeinern:

### Stufe 1: Globale Konfiguration

Speicherort: `~/.codex/AGENTS.md`

Universelle Standards, die für alle Ihre Projekte gelten:

```markdown
# Global AGENTS.md

## General Standards
- Write code comments in English
- Git commit messages follow Conventional Commits
- Never hardcode passwords, keys, or tokens in source code
- Read existing related code before generating new code to maintain consistency
- If unsure about the impact of a change, add a comment explaining it rather than making assumptions

## Output Preferences
- Prefer existing project dependencies; don't introduce new ones unnecessarily
- Error handling must be thorough; never swallow exceptions silently
- Log messages should be meaningful and include context
```

### Stufe 2: Konfiguration auf Repository-Ebene

Speicherort: `AGENTS.md` im Projektstammverzeichnis

Standards, die für ein bestimmtes Projekt spezifisch sind:

```markdown
# AGENTS.md

## Project Overview
A React + Node.js full-stack e-commerce project built with TypeScript.

## Tech Stack
- Frontend: React 19 + TailwindCSS + Zustand
- Backend: Node.js + Fastify + Prisma
- Database: PostgreSQL 16
- Testing: Vitest + Playwright

## Code Standards
- Component files use PascalCase: `UserProfile.tsx`
- Utility functions use camelCase: `formatDate.ts`
- API routes use kebab-case: `/api/user-orders`
- Database fields use snake_case: `created_at`

## Project Structure
- `src/components/` - React components
- `src/pages/` - Page components
- `src/api/` - Backend API routes
- `src/lib/` - Shared utility library
- `prisma/` - Database schema and migrations

## Commands
- `npm run dev` - Start the dev server
- `npm run build` - Build for production
- `npm test` - Run all tests
- `npm run lint` - Run linting
- `npx prisma migrate dev` - Run database migrations
```

### Stufe 3: Konfiguration auf Unterverzeichnis-Ebene

Speicherort: `AGENTS.md` in einem beliebigen Unterverzeichnis

Zusätzliche Regeln für bestimmte Module, **die auf die Regeln der übergeordneten Ebene aufbauen**:

```
your-project/
  AGENTS.md                  <- project-level rules
  src/
    components/
      AGENTS.md              <- component directory rules
    api/
      AGENTS.md              <- API directory rules
```

Beispiel `src/components/AGENTS.md`:

```markdown
# Component Standards

- All components must be function components (no class components)
- Props must have a TypeScript interface definition
- Every component must have a displayName
- Use TailwindCSS for styling; no inline styles
- Split complex components into sub-components; keep each file under 200 lines
- Reusable components go in the `ui/` subdirectory
```

Beispiel `src/api/AGENTS.md`:

```markdown
# API Standards

- All endpoints must validate request parameters (using Zod schemas)
- Uniform error format: `{ code: number, message: string, details?: any }`
- Database operations must run inside transactions
- Sensitive operations must be audit-logged
- Pagination endpoints use cursor-based pagination
```

### Überschreibungspriorität

Wenn Regeln auf mehreren `AGENTS.md`-Stufen in Konflikt stehen, **gewinnt die nächstgelegene Ebene**:

```
Global (~/.codex/AGENTS.md)
  | overridden by repo-level
Repo root (project/AGENTS.md)
  | overridden by subdirectory
Subdirectory (project/src/api/AGENTS.md) <- highest priority
```

In der Praxis:

- Regeln in `AGENTS.md` auf Unterverzeichnis-Ebene haben Vorrang vor übergeordneten Ebenen
- Regeln der übergeordneten Ebene, die nicht überschrieben werden, bleiben wirksam
- Regeln auf mehreren Ebenen sind **additiv**, keine vollständigen Ersetzungen

---

## Praxisvorlagen

Im Folgenden finden Sie mehrere erprobte Vorlagen, die Sie direkt in Ihre Projekte übernehmen können.

### Frontend-Projekt mit React

```markdown
# AGENTS.md

## Project Info
React 19 + TypeScript + TailwindCSS frontend project.

## Code Standards
- Use function components + Hooks; class components are prohibited
- State management uses Zustand; do not introduce Redux
- Styling with TailwindCSS; no CSS files
- Use `@/` path alias to reference modules under src
- Define component Props as an interface named `{ComponentName}Props`

## File Naming
- Component files: PascalCase (`UserAvatar.tsx`)
- Hook files: camelCase + use prefix (`useAuth.ts`)
- Utility files: camelCase (`formatDate.ts`)
- Constant files: camelCase (`apiEndpoints.ts`)

## Component Rules
- Export both the Props type and the component itself
- Wrap pure presentational components with `React.memo`
- Name event handlers as `handle{EventName}`
- Avoid creating new objects or functions inside render

## Testing
- Framework: Vitest + React Testing Library
- Test files go in `__tests__/` directories
- Test user behavior, not implementation details
- Run command: `npm test`

## Dependency Management
- Before adding a new dependency, check if existing ones already cover the need
- Prefer lightweight libraries
- All dependencies must have TypeScript type definitions
```

### Backend-Projekt mit Python/FastAPI

```markdown
# AGENTS.md

## Project Info
Python 3.12 + FastAPI + SQLAlchemy backend service.

## Code Standards
- Type annotations: all function parameters and return values must have type annotations
- Async first: all IO operations must use async/await
- Docstrings: all public functions use Google-style docstrings
- Import ordering: stdlib -> third-party -> local modules (managed by isort)

## Project Structure
- `app/api/` - API routes (organized by feature router)
- `app/models/` - SQLAlchemy data models
- `app/schemas/` - Pydantic request/response models
- `app/services/` - Business logic layer
- `app/core/` - Configuration, security, dependency injection
- `tests/` - Test files, mirroring the app directory structure
- `alembic/` - Database migrations

## Coding Conventions
- Route function naming: `get_users`, `create_order` (verb_noun)
- Service layer methods: correspond to route functions
- Data model fields use snake_case
- All database operations go through the Service layer; routes never touch the ORM directly
- Sensitive data (passwords, tokens) must never appear in logs or responses

## Error Handling
- Business exceptions use custom Exception classes
- Unified exception handler returns standard format: `{"code": int, "message": str}`
- Database operations are wrapped in try/except to catch IntegrityError, etc.
- Never use bare except

## Testing
- Framework: pytest + pytest-asyncio + httpx
- Use fixtures to manage test database and client
- Run command: `pytest -v --cov=app`
- Minimum coverage target: 80%

## Environment Management
- Use .env files for configuration, loaded via pydantic-settings
- Environment-specific differences are handled via environment variable overrides
- Never hardcode database connection strings, secrets, etc. in code
```

### Full-Stack-Projekt

```markdown
# AGENTS.md

## Project Info
Full-stack web app: Next.js 15 frontend + API Routes + PostgreSQL.
Monorepo structure managed with Turborepo.

## Directory Structure
- `apps/web/` - Next.js frontend
- `apps/api/` - Standalone API service (Node.js + Fastify)
- `packages/ui/` - Shared UI component library
- `packages/types/` - Shared TypeScript types
- `packages/utils/` - Shared utility functions
- `packages/db/` - Database schema (Drizzle ORM)

## General Standards
- Language: TypeScript strict mode
- Formatting: Prettier (configured at root)
- Lint: ESLint (configured at root)
- Before committing, run: `turbo lint test`

## Frontend Standards (apps/web/)
- Use App Router, not Pages Router
- Server Components first; Client Components only when necessary
- Data fetching via Server Actions or Route Handlers
- Styling with TailwindCSS
- Images use the next/image component

## API Standards (apps/api/)
- RESTful design, URLs use kebab-case
- Request validation with Zod
- Response format: `{ success: boolean, data?: T, error?: string }`
- Authentication via JWT, validated in middleware
- Rate limiting rules go in route decorators

## Database Standards (packages/db/)
- Use Drizzle ORM; schema defined in the `schema/` directory
- Migration command: `pnpm db:migrate`
- Naming: table names are plural (`users`), fields use snake_case
- All tables must have `created_at` and `updated_at`
- Soft deletes use a `deleted_at` field

## Shared Package Standards
- Packages reference each other via workspace
- Shared type definitions go in `packages/types/`
- Packages must not import from apps
```

---
## Erweiterte Tipps

### Koexistenz mit CLAUDE.md

Wenn Ihr Projekt sowohl Codex als auch Claude Code nutzt, können Sie beide Konfigurationsdateien parallel pflegen:

```
your-project/
  AGENTS.md          <- read by Codex
  CLAUDE.md          <- read by Claude Code
  src/
  ...
```

**Kernstandards können gemeinsam genutzt werden**. Der Großteil des Inhalts beider Dateien (Tech-Stack, Namenskonventionen, Verzeichnisstruktur usw.) ist identisch -- nur die toolspezifischen Anweisungen unterscheiden sich.

Empfohlene Vorgehensweise:

1. Einen Satz Kernstandards verfassen
2. In beide Dateien `AGENTS.md` und `CLAUDE.md` kopieren
3. Das Format für die jeweilige Tool-Konvention fein abstimmen

Oder eine elegantere Vorgehensweise -- Querverweis am Anfang jeder Datei:

```markdown
# AGENTS.md

> This project uses both Codex and Claude Code. Core standards are below.
> Claude Code users, refer to CLAUDE.md.

## Core Standards
(shared content)
```

### Best Practices für die Teamzusammenarbeit

#### In die Versionskontrolle einchecken

`AGENTS.md` sollte in Ihr Git-Repository eingecheckt werden, damit alle Teammitglieder dieselben AI-Coding-Standards nutzen:

```bash
git add AGENTS.md
git commit -m "feat: add AGENTS.md for Codex configuration"
```

#### AGENTS.md in Code-Reviews einbeziehen

Änderungen an `AGENTS.md` sollten genauso durch ein Code-Review gehen wie Änderungen an Coding-Standards:

```markdown
<!-- PR description -->
## Change Summary
Updates to AGENTS.md:
- Added API pagination standard (cursor-based)
- Explicitly prohibited direct fetch calls in components
- Added logging format requirements
```

#### Schrittweise iterieren

Sie müssen nicht alles auf einmal schreiben. Empfohlene Vorgehensweise:

1. **Erster Tag**: Grundlegenden Tech-Stack und Namenskonventionen schreiben (10–20 Zeilen)
2. **Erste Woche**: Regeln basierend auf dem tatsächlichen Verhalten von Codex hinzufügen
3. **Laufend**: Immer wenn Codex etwas unerwünschtes tut, eine Regel zu `AGENTS.md` hinzufügen

### Effektive Anweisungsmuster

Diese Arten von Anweisungen funktionieren in `AGENTS.md` am besten:

```markdown
## High-Effectiveness Instructions (Codex follows these reliably)

- Explicit format requirements: Use PascalCase for component file names
- Explicit prohibitions: Do not use the any type
- Run commands: Run npm test after completing the task
- File location rules: Test files go in __tests__ directories
- Dependency constraints: Do not introduce new npm packages; use existing dependencies
```

```markdown
## Low-Effectiveness Instructions (best avoided)

- Too vague: Write good code
- Subjective: Use best practices
- Out of scope: Consider user experience (AI can't run a UI)
- Contradictory: Prioritize performance + prioritize readability (need explicit priority)
```

### Bedingte Regeln

Sie können verschiedene Regeln für verschiedene Dateitypen oder Verzeichnisse festlegen:

```markdown
## File Type Rules

### *.test.ts files
- No more than 10 tests per describe block
- Use factory functions to create test data; no hardcoding
- Async tests must have timeout settings

### *.api.ts files
- Must validate request parameters
- Must include error handling
- Return values must have type annotations

### migrations/*.sql files
- Do not modify directly; use the ORM migration tool to generate
```

---

## Migration von CLAUDE.md

Wenn Sie bereits eine `CLAUDE.md` haben, ist die Konvertierung in `AGENTS.md` unkompliziert. Beide sind im Markdown-Format, und der Kerninhalt lässt sich direkt übernehmen.

### Migrationsschritte

**Schritt 1: Basisinhalt kopieren**

```bash
cp CLAUDE.md AGENTS.md
```

**Schritt 2: Claude-Code-spezifische Verweise ersetzen**

Ersetzen Sie Claude Code-spezifische Konzepte durch ihre Codex-Äquivalente:

| In CLAUDE.md | In AGENTS.md |
|--------------|--------------|
| „When Claude modifies files...“ | „When modifying files...“ |
| „Use `/compact` to compress context“ | (Entfernen -- Codex hat diesen Befehl nicht) |
| „Reference files via `@`“ | (Entfernen -- Codex verwendet eine andere Referenzmethode) |
| „Hook: PostToolUse...“ | „After completing the task, run...“ |
| „Sub-agent handles...“ | „Use Cloud Exec...“ |

**Schritt 3: Format verschlanken**

Codex bevorzugt knappe Listen-Stil-Anweisungen. Wenn Ihre `CLAUDE.md` lange erklärende Absätze enthält, verdichten Sie diese zu Aufzählungspunkten:

Vor der Migration (`CLAUDE.md`-Stil):

```markdown
## Code Style

In this project, we follow the Google TypeScript style guide. All variable
names use camelCase, class names use PascalCase. Note that enum values use
SCREAMING_SNAKE_CASE. Import statements should be ordered as follows: first
Node.js built-in modules, then third-party packages, and finally local
modules. Separate each group with a blank line.
```

Nach der Migration (`AGENTS.md`-Stil):

```markdown
## Code Style
- Follow the Google TypeScript style guide
- Variables: camelCase
- Classes: PascalCase
- Enum values: SCREAMING_SNAKE_CASE
- Import order: built-in modules -> third-party packages -> local modules (blank line between groups)
```

**Schritt 4: Codex-spezifische Anweisungen hinzufügen**

```markdown
## Codex-Specific Configuration
- After all file modifications, run `npm run lint && npm test` to verify
- If tests fail, automatically fix and re-run
- Do not modify .env and .env.local files
```

### Migrations-Referenztabelle

| Konzept | CLAUDE.md-Stil | AGENTS.md-Stil |
|---------|-----------------|-----------------|
| Projektbeschreibung | Freie Absätze | Kurze Liste oder Absatz |
| Coding-Standards | Markdown-Listen | Markdown-Listen (identisch) |
| Verbotene Aktionen | „Don't do X“ | „Never do X“ oder „Don't do X“ |
| Befehle ausführen | „Please run `npm test`“ | „Run `npm test`“ oder nur als Liste |
| Dateistruktur | Code-Block mit Verzeichnisbaum | Code-Block mit Verzeichnisbaum (identisch) |
| Tool-Konfiguration | settings.json-Verweise | config.toml-Verweise |

### Beide Dateien pflegen

Wenn Sie langfristig sowohl `AGENTS.md` als auch `CLAUDE.md` pflegen müssen:

1. **Eine Datei als „primäre“ festlegen**: Üblicherweise die Datei für das Tool, das Sie häufiger nutzen
2. **Nach der Bearbeitung der primären Datei synchronisieren**: Sie können ein einfaches Skript zur Automatisierung schreiben
3. **Toolspezifische Regeln getrennt halten**: Gemeinsame Standards an den Anfang, toolspezifische Regeln ans Ende

---
## Debugging & Validierung

### Prüfen, ob AGENTS.md aktiv ist

Am einfachsten prüfen Sie das, indem Sie Codex eine Aufgabe geben, die eine Regel auslösen sollte:

```bash
# Assuming AGENTS.md requires TypeScript
codex "Create a hello world function"

# If AGENTS.md is active, Codex will generate a .ts file instead of .js
```

### Fehlerbehebung, wenn Regeln nicht greifen

1. **Dateispeicherort**: Stellen Sie sicher, dass sich `AGENTS.md` im Projektstamm oder im jeweiligen Unterverzeichnis befindet
2. **Dateiname**: Der Name muss `AGENTS.md` lauten (Großbuchstaben, nicht `agents.md`)
3. **Formatierungsprobleme**: Achten Sie auf korrekte Markdown-Formatierung (z. B. eine Leerzeile vor Listen)
4. **Regelkonflikte**: Prüfen Sie, ob sich Vorgaben über mehrere `AGENTS.md`-Ebenen hinweg widersprechen
5. **Zu unspezifisch**: Ersetzen Sie die Regel durch eine konkretere Beschreibung

---

## CLAUDE.md oder AGENTS.md: Was passt zu Ihnen?

Beide Konfigurationsdateien parallel zu pflegen, klingt naheliegend, aber **zwei Kopien laufen erfahrungsgemäß auseinander**: Sie ergänzen eine Regel in `AGENTS.md` und vergessen, sie in `CLAUDE.md` zu übernehmen – schon verhalten sich die beiden Tools uneinheitlich. Die folgenden Hinweise helfen Ihnen, diese Falle zu vermeiden.

### Entscheidend ist zunächst, wie viele Tools Sie nutzen

- **Nur Claude Code (ein einzelnes Tool)**: Eine `CLAUDE.md` genügt. Claude Code liest `CLAUDE.md` nativ und ergänzt sie um globales Memory sowie pfadbezogene Regeln (verschachtelte `CLAUDE.md` / `.claude/rules`). Zusätzlich eine `AGENTS.md` zu pflegen, ist nicht nötig.
- **Team mit mehreren Tools (Claude Code + Codex / Cursor / Copilot / Cline / Gemini / Aider / Zed usw.)**: Machen Sie `AGENTS.md` zur **einzigen maßgeblichen Quelle**. Die meisten Tools außer Claude Code lesen `AGENTS.md`, während Claude Code standardmäßig nur `CLAUDE.md` liest.

### Empfehlung für Teams mit mehreren Tools: eine schlanke CLAUDE.md, die AGENTS.md importiert

Pflegen Sie nicht zwei vollständige Kopien, die auseinanderlaufen. Halten Sie die gemeinsamen Standards in `AGENTS.md` und binden Sie sie über eine **schlanke `CLAUDE.md`** ein, damit Claude Code sowohl die teamweiten Regeln als auch seine Claude-spezifischen Zusätze erhält:

```markdown
# CLAUDE.md

@AGENTS.md

## Claude Code-only extras
- Use `/model` to switch between Sonnet 4.6 / Opus 4.8 per task
- Run `/plan` before large changes
- Use `/clear` between unrelated tasks; `/compact` at logical breakpoints in long sessions
```

So haben die gemeinsamen Standards eine einzige Quelle (`AGENTS.md`), und `CLAUDE.md` enthält nur Claude-Code-spezifische Vorgaben – abweichende Duplikate werden damit von Grund auf vermieden.

### Schnelle Entscheidungstabelle

| Szenario | Was Sie pflegen | Hinweise |
|----------|------------------|-------|
| Nur Claude Code | Nur `CLAUDE.md` | Wird nativ gelesen; keine `AGENTS.md` nötig |
| Nur Codex / andere Tools | Nur `AGENTS.md` | Diese Tools lesen `CLAUDE.md` nicht |
| Team mit mehreren Tools | `AGENTS.md` (maßgebliche Quelle) + schlanke `CLAUDE.md` (`@AGENTS.md`) | Eine Quelle, keine Abweichungen |

> Informationen zu Schichtung, Vorlagen und Kontextsteuerung von `CLAUDE.md` finden Sie im [CLAUDE.md-Konfigurationsleitfaden](/docs/usage/claude-md).

---

## Nächste Schritte

- [Codex-Schnellstart](/docs/getting-started/codex-quick-start) -- Codex installieren und konfigurieren
- [Codex vs. Claude Code: Ein ausführlicher Vergleich](/docs/getting-started/codex-vs-claude-code) -- Vollständiger Vergleich beider Tools
- [Hooks-System](/docs/advanced/hooks) -- Event-Hooks von Claude Code (ähnliches Konzept)
- [CLI-Tipps & Tricks](/docs/usage/cli-tips) -- Praktische Tipps für produktiveres KI-gestütztes Programmieren