Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

AGENTS.md: Konfigurieren Sie die Repo-Anweisungen

Lektion 15 von 20 Aktualisiert am 3. November 2026 Entwickler
Auf dieser Seite
  1. Beherrschung der Codex-Konfigurationsdatei
  2. Die AGENTS.md-Hierarchie
  3. Die Abschnitte, die die Datei ausmachen
  4. Zwei Muster, die Überraschungen verhindern
  5. Die Datei am Leben erhalten
  6. Wichtige Erkenntnisse

Lektion aktualisiert am 3. November 2026 basierend auf der Seite Custom instructions with AGENTS.md: Codex liest nur AGENTS.md-Dateien, die sich zwischen dem Projektroot und dem aktuellen Arbeitsverzeichnis befinden (plus die globale Datei unter ~/.codex). Eine Datei in einem Unterverzeichnis außerhalb dieses Pfades wird nicht geladen, im Gegensatz zu dem, was die vorherige Version implizierte. Quelle: AGENTS.md.

Beherrschung der Codex-Konfigurationsdatei

Sie haben AGENTS.md in Lektion 3 entdeckt. Hier tauchen wir in fortgeschrittene Muster ein – der Unterschied zwischen einer dekorativen Datei (drei Zeilen, die beim Start geschrieben und vergessen werden) und einer Datei, die das Verhalten des Agents in einem Live-Projekt tatsächlich steuert.

Die AGENTS.md-Hierarchie

Codex liest diese Dateien hierarchisch, von allgemein zu spezifisch: zuerst die globale Datei in Ihrem Codex-Ordner (~/.codex/AGENTS.md oder AGENTS.override.md, falls vorhanden), dann, beginnend beim Projektroot, die Dateien in den durchlaufenen Verzeichnissen bis hin zum aktuellen Arbeitsverzeichnis. In einem strukturierten Projekt sieht der Baum so aus:

mon-projet/
  AGENTS.md                    → Globale Regeln (niedrige Priorität)
  src/
    AGENTS.md                  → Regeln für alle Quellcode
    api/
      AGENTS.md                → Regeln, die spezifisch für APIs sind
      routes/
        AGENTS.md              → Regeln für Routen
    components/
      AGENTS.md                → Regeln für React-Komponenten
  tests/
    AGENTS.md                  → Regeln für Tests

Regeln akkumulieren: Codex fügt Dateien vom Root bis zum aktuellen Verzeichnis zusammen, und die Dateien, die diesem Verzeichnis am nächsten liegen, werden zuletzt gelesen und überschreiben allgemeine Anweisungen. Ein Punkt, der leicht missverstanden wird: Nur Verzeichnisse auf dem Pfad zwischen dem Root und dem aktuellen Verzeichnis werden gelesen. Wenn Ihre Root-Datei any verbietet, während tests/AGENTS.md lockere Assertions in Mocks erlaubt, gilt diese Toleranz nur, wenn Codex aus tests/ oder einem seiner Unterordner gestartet wird; gestartet vom Root wird tests/AGENTS.md nicht gelesen. Für eine Regel, die überall gelten muss, platzieren Sie sie am Root, auch wenn Sie die Ausnahme dort benennen müssen. GitHub-Code-Reviews funktionieren anders: Codex durchsucht das gesamte Repository nach AGENTS.md-Dateien und wendet die Review-Regeln (## Code Review Rules) aus der Datei an, die dem fraglichen Code am nächsten liegt. Die Zusammenführung stoppt standardmäßig bei 32 KiB (project_doc_max_bytes): Eine Datei, die zu lang ist, wird abgeschnitten.

Die Abschnitte, die die Datei ausmachen

Kontext kommt zuerst, da er jede folgende Entscheidung prägt. Eine SaaS-Anwendung, die der DSGVO (General Data Protection Regulation) unterliegt, wird nicht wie ein internes Tool für fünf Personen programmiert:

## Kontext
SaaS-Rechnungsmanagement-Anwendung für französische KMUs.
DSGVO-Konformität ist zwingend erforderlich. Daten werden in Frankreich gehostet (OVH).
Stack: Astro 6, React, Strict TypeScript, Prisma, PostgreSQL.
Authentifizierung: Better Auth mit Server-Sitzungen.

Da bekannt ist, dass es Daten verarbeitet, die der DSGVO unterliegen, fügt Codex die erwarteten Schutzmaßnahmen hinzu, ohne dass Sie diese in jeder Anfrage spezifizieren müssen. Als Nächstes kommen die Konventionen, die eine Frage beantworten: Wie sieht korrekter Code hier aus?

## Konventionen
- Strict TypeScript (kein any, kein implizites any)
- Nur funktionale React-Komponenten
- Benennung: kebab-case für Dateien, PascalCase für Komponenten, camelCase für Variablen
- Imports: @/ für Pfad-Aliases
- Validierung: Zod für alle Benutzereingaben
- Fehler: benutzerdefinierte Fehlerklassen in src/lib/errors.ts
- Logging: verwenden Sie src/lib/logger.ts (kein console.log)

Der Abschnitt für Befehle wird am häufigsten weggelassen, und sein Fehlen ist kostspielig: Ohne diese Befehle kann Codex seine eigene Arbeit nicht verifizieren und liefert Code zurück, den es noch nie ausgeführt oder getestet hat.

## Befehle
- `npm run dev` — Entwicklungsserver (Port 4321)
- `npm run build` — Produktionsbuild
- `npm run test` — Vitest-Tests
- `npm run test:e2e` — Playwright-Tests
- `npm run lint` — ESLint + Prettier
- `npm run db:migrate` — Prisma-Migrationen
- `npm run db:seed` — Datenbank-Saatgut

Strenge Regeln bilden das Sicherheitsnetz. Ausgedrückt als „NIEMALS” und „IMMER” verhindern sie Fehler, die einen ganzen Abend kosten, um zu beheben: eine gelöschte Prisma-Migration, die Sie aus der Produktion rekonstruieren müssen, ein committeter Geheimwert, der widerrufen werden muss, oder ein innerHTML, das in eine Komponente gerutscht ist und eine XSS-Schwachstelle öffnet.

## Strenge Regeln (NIEMALS verletzen)
- NIEMALS das Prisma-Schema ändern, ohne eine Migration zu erstellen
- NIEMALS Geheimwerte im Code speichern (verwenden Sie .env)
- NIEMALS innerHTML verwenden (XSS-Risiko)
- NIEMALS eine existierende Prisma-Migration löschen
- NIEMALS interne IDs in öffentlichen URLs offenlegen
- IMMER Benutzereingaben mit Zod validieren
- IMMER Prisma-Transaktionen für Mehr-Tabelle-Operationen verwenden

Schließlich beschreibt die Architektur den erlaubten Fluss zwischen den Schichten. Ohne sie produziert Codex Code, der funktioniert, aber Ihre Struktur umgeht – beispielsweise eine Route, die Prisma direkt abfragt, weil dies der kürzeste Weg war.

## Architektur
Schichten:
1. Routen (src/pages/) → erhalten Anfragen
2. Services (src/services/) → Geschäftslogik
3. Repositories (src/repositories/) → Datenzugriff

Regel: Routen DÜRFEN PRISMA NICHT direkt zugreifen.
Alles läuft über einen Service, der über ein Repository läuft.

Zusätzlich dazu werden pro Projekt Anweisungen für jede verwendete Technologie hinzugefügt:

## React
- Server-Komponenten standardmäßig bevorzugen
- Client-Komponenten nur, wenn notwendig (Interaktivität)
- Kein useEffect für Datenabfragen (Server Actions verwenden)
- Lokaler Zustand mit useState, globaler Zustand mit Zustand

## Prisma
- Relationen: erforderliche Felder immer explizit einbeziehen
- Paginierung: cursor-basiert verwenden, nicht offset-basiert
- Soft Delete: deletedAt verwenden statt DELETE

Zwei Muster, die Überraschungen verhindern

Das Deklarieren erwarteter Umgebungsvariablen verhindert, dass Codex beim Schreiben eines Skripts Schlüsselnamen erfindet oder versehentlich einen sensiblen Wert in einem Debug-Trace protokolliert:

## Erforderliche Umgebungsvariablen
- DATABASE_URL — PostgreSQL-Verbindungs-URL
- AUTH_SECRET — Geheimwert für Better Auth (mindestens 32 Zeichen)
- SMTP_HOST — SMTP-Server für E-Mails
- STRIPE_SECRET_KEY — Stripe-API-Schlüssel (niemals protokollieren)

Das Benennen Ihrer bevorzugten Bibliotheken, und insbesondere jener, die Sie ablehnen, löst ein wiederkehrendes Ärgernis: Der Agent installiert eine Abhängigkeit, die an sich völlig gültig ist, die Ihr Team aber vor zwei Jahren nach einer schlechten Erfahrung abgelehnt hat.

## Abhängigkeiten
Wenn Sie benötigen:
- Validierung → Zod (NICHT Joi, NICHT Yup)
- Datumsformate → date-fns (NICHT moment, NICHT dayjs)
- HTTP-Client → ofetch (NICHT axios)
- Tests → Vitest (NICHT Jest)
- E2E → Playwright (NICHT Cypress)

Die Datei am Leben erhalten

AGENTS.md entwickelt sich mit Ihrem Code weiter, genau wie ein Test oder ein README. Aktualisieren Sie sie, sobald Sie eine neue Konvention übernehmen, Bibliotheken oder Frameworks wechseln, und insbesondere, sobald Sie einen wiederkehrenden Codex-Fehler identifizieren: In diesem letzten Fall signalisiert dies immer eine fehlende Anweisung, nicht ein Modellversagen. Ein vierter, subtilerer Auslöser, auf den Sie achten sollten, ist, wenn ein neuer Entwickler eine Frage stellt, die AGENTS.md beantwortet haben sollte; diese Antwort gehört in die Datei.

Wichtige Erkenntnisse

  • Die Hierarchie von AGENTS.md ermöglicht zunehmend spezifische Anweisungen
  • Befehle sind kritisch, damit Codex seine Arbeit verifizieren kann
  • NIEMALS-Regeln sind am wichtigsten, um Fehler zu vermeiden
  • Dokumentieren Sie bevorzugte Abhängigkeiten, um schlechte Entscheidungen zu verhindern
  • Halten Sie AGENTS.md als lebendigen Code aufrecht