Welche Verzeichniskonventionen und Code-Stile befolgen Codex und Claude Code gut?

Codex und Claude Code bevorzugen nicht von sich aus eine bestimmte Programmiersprache, ein Framework, eine Einrückungsbreite oder ein Ordnerlayout. Umgebungen, denen sie vergleichsweise zuverlässig folgen können, sind solche, in denen bestehende Repository-Konventionen konsistent sind, der Geltungsbereich erforderlicher Regeln klar ist und Änderungen automatisch validiert werden können. Das Ziel besteht daher nicht darin, eine Struktur zu erfinden, die einer KI gefallen könnte, sondern Projektkonventionen kurz, verständlich und überprüfbar zu gestalten – für Menschen und neue Mitwirkende. openai.com↗code.claude.com↗

Codex und Claude Code bezeichnen hier Coding-Agent-Tools, die Dateien in einem Repository lesen, Anweisungen konsultieren, Code ändern oder Befehle ausführen können. Solche Tools erhalten viele Hinweise aus dem Code selbst, können aber Fachterminologie des Produkts, verbotene Änderungen, Prüfungen vor dem Deployment oder Ausnahmeregeln für bestimmte Ordner nicht immer korrekt ableiten. Repository-Struktur, Anweisungsdateien und ausführbare Validierungsverfahren schließen diese Lücke. cdn.openai.com↗

Warum ist Konsistenz wichtiger als die „richtige Ordnerstruktur“?

Ein Team kann beispielsweise src/payments/ und src/users/ nach Features organisieren, während ein anderes src/controllers/, src/services/ und src/repositories/ nach Schichten ordnet. Es gibt keine Grundlage für die abschließende Behauptung, dass einer dieser Ansätze automatisch besser für Codex oder Claude Code ist. Entscheidend ist, dass Verantwortlichkeiten derselben Art im Repository an ähnlichen Stellen liegen, neue Dateien nach denselben Kriterien abgelegt werden und Tests sowie Importstile bestehenden Mustern folgen.

Dasselbe gilt, wenn ein Agent eine neue Zahlungsfunktion hinzufügt. Wenn das bestehende Zahlungsmodul zeigt, wie Request-Validierung, Fehlerbehandlung, Datenzugriff und Tests angeordnet sind, ist es sicherer, dieses Muster fortzuführen. Führt dagegen jedes neue Feature neue Dateinamen und Schichten ein oder vermischt ein einzelner Ordner Domain-Code mit Build-Artefakten und temporären Dateien, fällt es sowohl Agents als auch Menschen schwer zu erkennen, wo Änderungen vorgenommen werden müssen und was sie beeinflussen.

Verzeichniskonventionen sind daher nicht bloß Regeln des Erscheinungsbilds. Sie sind ein Navigationssystem, das zeigt, wo Code zu finden ist, was gemeinsam geändert werden sollte und welche Validierung auszuführen ist. Je stabiler Namen und Grenzen sind, desto weniger müssen lange Erläuterungen in Anweisungsdateien wiederholt werden.

Wo sollte die grundlegende Anleitung des Repositorys liegen?

In Codex dient AGENTS.md im Allgemeinen als Projektanweisungsdatei. Anweisungen zu Code-Stil, Struktur, Benennung und Tests in dieser Datei gelten für das Verzeichnis, in dem sie liegt, und dessen Unterbaum; Anweisungen an tieferen Stellen können bei Konflikten spezifischere Vorgaben liefern. Auch Anweisungen für persönliche Umgebungen und Überschreibungen über AGENTS.override.md werden unterstützt. openai.com↗

In Claude Code können CLAUDE.md oder .claude/CLAUDE.md als Zentrum für Projektspeicher und Anleitungen dienen. Eine CLAUDE.md in einem übergeordneten Pfad kann beim Start als Kontext bereitgestellt werden, während Dateien in Unterverzeichnissen bei der Bearbeitung von Dateien an diesen Pfaden bei Bedarf geladen werden. Darüber hinaus können Sie CLAUDE.local.md für benutzerspezifische Einstellungen und Dateien auf Ebene des Home-Verzeichnisses verwenden. code.claude.com↗

Obwohl die beiden Dateien ähnliche Namen haben, ist ihr Verhalten bei der automatischen Erkennung nicht identisch. Gehen Sie insbesondere nicht davon aus, dass Claude Code AGENTS.md automatisch als gemeinsame Anweisungen liest. Wenn Sie beide Tools einsetzen, importieren Sie die gemeinsame Datei in CLAUDE.md mit @AGENTS.md, oder definieren Sie ausdrücklich eine Verbindung, die zum Betriebsmodell des Teams passt. code.claude.com↗

Am besten bleibt die Anleitungsdatei im Root eher eine Einstiegskarte als eine Enzyklopädie, die das gesamte Repository ausführlich beschreibt. Es genügt, die Befehle zu zeigen, die neue Mitwirkende zuerst benötigen, die oberste Struktur, zentrale Invarianten und die Speicherorte detaillierter Dokumentation. Eine lange, einzelne Anweisungsdatei verbraucht Kontext, der für den eigentlichen Code und die Aufgabenanforderungen genutzt werden sollte, und kann kritische Einschränkungen schwerer erkennbar machen. Ein Codex-bezogenes Beispiel von OpenAI zeigt ebenfalls eine Kombination aus einer kurzen, kartenartigen Datei mit rund 100 Zeilen und separater Dokumentation. openai.com↗

Was sollten AGENTS.md und CLAUDE.md enthalten?

Gute Anweisungen duplizieren nicht umfangreich Fakten, die aus dem Code bereits offensichtlich sind. Stattdessen priorisieren sie Informationen, die sich allein aus dem Code schwer lernen lassen oder deren falsche Ableitung teuer wäre. Codex-bezogene Materialien nennen Benennungskonventionen, Domain-Sprache, bekannte Einschränkungen und Abhängigkeiten sowie Build- und Testverfahren als Informationen, die sich für AGENTS.md eignen. cdn.openai.com↗

Root-Anweisungen können Fragen wie diese knapp beantworten:

• Welche Befehle führen nach einer ersten Änderung Formatierung, statische Analyse, Typprüfung und Tests aus?
• Wo befinden sich Quellcode, Tests, Designdokumentation und Betriebsdokumentation?
• Welche Konventionen für Dateinamen, Imports, Fehlerbehandlung und Tests sind beim Erweitern eines bestehenden Moduls einzuhalten?
• Dürfen generierte Dateien, Build-Artefakte, Lock-Dateien und Secrets geändert oder in das Repository aufgenommen werden?
• Erfordern risikoreiche Bereiche einen Plan, zusätzliche Prüfung oder bestimmte Tests?
• Welche Dokumente enthalten detaillierte Design- und Betriebsverfahren?

Dagegen lassen sich allgemeine Aussagen wie „schreibe sauberen Code“, „priorisiere Sicherheit“ oder „gib dein Bestes“ nur schwer in ausführbare Regeln überführen. Eine Aussage wie „Verwende für externe Eingaben das bestehende Validierungsmodul und füge für jede neue API-Route den entsprechenden Integrationstest hinzu“ ist nützlicher, weil sie beobachtbar und überprüfbar ist. Die Anleitung zu Claude Code betont ebenfalls, projektspezifische Regeln konkret zu formulieren sowie Anweisungen mit ihrem Wachstum regelmäßig zu überprüfen und zu ordnen. code.claude.com↗

Anweisungen sollten eine verdichtete Aufzeichnung von Entscheidungskriterien sein, nicht ein Dokument, das jedes Implementierungsdetail vorschreibt. Wissen, das umfangreich ist und sich voraussichtlich ändert – etwa die Verwendung einer bestimmten Bibliothek, API-Verträge oder die Reihenfolge bei Incident Response –, lässt sich leichter pflegen, wenn es in ein passendes Dokument unter docs/ ausgelagert wird, während Root-Anweisungen auf dessen Ort und Verwendungsbedingungen hinweisen.

Wann werden Regeln für einzelne Unterverzeichnisse benötigt?

Unterverzeichnisregeln sind keine Dateien, die mechanisch jedem Ordner hinzugefügt werden sollten. Wo gemeinsame Root-Regeln ausreichen, können separate Dateien stattdessen den Navigationsaufwand und das Konfliktpotenzial erhöhen. Sie sollten Grenzen vorbehalten bleiben, die deutlich von allgemeinen Regeln abweichen oder bei denen Fehler erhebliche Folgen haben.

Beispielsweise kann src/payments/ dokumentieren, wie Geldbeträge ausgedrückt werden sollen, wie Mocks für externe Zahlungsanbieter verwendet werden und welcher konkrete Integrationstestbefehl auszuführen ist. infra/ kann vor Änderungen einen Plan, vor deren Anwendung Prüfungen sowie Grenzen dafür verlangen, welche umgebungsspezifischen Dateien geändert werden dürfen. generated/ kann festhalten, dass direkte Änderungen verboten sind, und die Quelle sowie den Generierungsbefehl benennen. Der Zweck dieser Regeln besteht nicht darin, den Ordner besonders erscheinen zu lassen, sondern die tatsächlichen Einschränkungen dieses Bereichs präzise im Arbeitskontext bereitzustellen.

Für Codex gilt eine verschachtelte AGENTS.md unterhalb ihres Verzeichnisses, und tiefer liegende Dateien können spezifischere Regeln bereitstellen. Claude Code kann ebenfalls mehrere CLAUDE.md-Dateien als Kontext zusammenführen. Deshalb ist es sicherer, wenn verschachtelte Dateien konkrete Bedingungen ergänzen, die nur in diesem Bereich benötigt werden, anstatt mehrdeutige Aussagen zu treffen, die übergeordnete Dateien außer Kraft setzen. openai.com↗code.claude.com↗

Im Root könnte beispielsweise stehen: „Führe Tests für das geänderte Paket aus“, während im Zahlungsordner steht: „Wenn sich der Zahlungsvertag ändert, führe sowohl Unit- als auch Integrationstests aus.“ Dagegen lassen Aussagen wie „Tests müssen immer ausgeführt werden“ im Root und „Keine Tests ausführen“ in einem Unterordner nicht nur Tools, sondern auch Menschen im Unklaren darüber, welcher Regel sie folgen sollen.

Wie sollten die .claude/rules/ von Claude Code aufgeteilt werden?

In Claude Code können Sie globale Regeln, die immer benötigt werden, in CLAUDE.md ablegen und Regeln mit unterschiedlichen Themen oder pfadabhängigem Verhalten in kleine Dateien unter .claude/rules/ aufteilen. Regeldateien können rekursiv organisiert werden, und Pfadbedingungen können Regeln auf bestimmte Dateien oder Bereiche beschränken. code.claude.com↗

Das Kriterium für die Aufteilung ist nicht die Anzahl der Dateien, sondern die Kohäsion von Regeln, die sich gemeinsam ändern. Beispielsweise können Testbefehle und Grundsätze für Testdaten in testing.md stehen, Ausnahmen für Imports, Benennung und Formatierung in code-style.md und Einschränkungen zu Secrets, externen Anfragen und Berechtigungen in security.md. Jede Datei sollte ein einzelnes Thema behandeln, und ihr Titel sollte klar machen, wann sie gelesen werden muss.

Der Vorteil dieses Ansatzes liegt darin, dass unnötige Anweisungen nicht ständig vollständig gelesen werden müssen. Bleiben etwa vollständige Regeln für Datenbankmigrationen in Arbeiten vermischt, die nur Dokumentation bearbeiten, können sie die wesentlichen Anweisungen verdecken. Eine zu feine Aufteilung erschwert jedoch das Auffinden der Regeln. Ein ausgewogener Ansatz stellt die wichtigsten Regelgruppen und ihre Zwecke kurz in der Root-CLAUDE.md vor, während der tatsächliche Inhalt in themenspezifischen Dateien bleibt.

Vermeiden Sie nach der Trennung von Regeln, dieselbe Verpflichtung in mehrere Dateien zu kopieren. Kopien driften im Lauf der Zeit leicht auseinander. Gemeinsame Prinzipien an einer Stelle zu halten und in pfadspezifischen Dateien nur Ausnahmen und zusätzliche Bedingungen festzuhalten, verringert Konflikte.

Wie sollte der Code-Stil festgelegt werden?

„KI-freundlicher Code-Stil“ bedeutet nicht eine universelle Wahl wie Tabs statt Leerzeichen oder funktionale statt objektorientierter Programmierung. Das wichtigere Kriterium ist, ob sich die lokalen Konventionen des Repositorys reproduzieren lassen. Reviews und Wartung werden einfacher, wenn ein neues Modul den Dateinamensmustern, dem Export-Stil, der Importreihenfolge, den Fehlerbehandlungspfaden und der Teststruktur bestehender Module folgt.

Jede Entscheidung des Projekts, die von gängigen Konventionen der Sprache abweicht, ist besonders dokumentationswürdig. Die Claude-Code-Dokumentation nennt projektspezifischen Code-Stil wie ES-Module oder Destrukturierung benannter Imports als Beispiele. Mit anderen Worten: Statt jede Standardregel einer Sprache neu zu schreiben, ist es effizienter zu beschreiben, „was unser Projekt anders macht als der Standard“. code.claude.com↗

Die folgende Tabelle bietet einfache Kriterien für Stilvorgaben.

Formatter, Linter und Typprüfer machen Stil mechanisch testbar, anstatt ihn durch Prosa durchzusetzen. Daher sollten Anweisungen die tatsächlich auszuführenden Befehle und die erwartete Behandlung von Fehlern nennen, statt zu sagen, man solle „alles schön formatieren“. Die Best Practices für Claude Code empfehlen ebenfalls klare Projektanweisungen und überprüfbare Entwicklungsabläufe. code.claude.com↗

Mit welcher Verzeichnisstruktur können Sie beginnen?

Im Folgenden finden Sie ein Beispiel, das Sie bei gemeinsamer Betrachtung von Codex und Claude Code verwenden können. Es ist kein verpflichtender Standard, sondern ein möglicher Ausgangspunkt, der gemeinsame Anweisungen, detaillierte Dokumentation und bereichsspezifische Ausnahmen trennt.

repo/
├── AGENTS.md
├── CLAUDE.md
├── README.md
├── ARCHITECTURE.md
├── docs/
│   ├── design-docs/
│   ├── product-specs/
│   ├── runbooks/
│   └── generated/
├── src/
│   ├── feature-a/
│   └── feature-b/
├── tests/
└── .claude/
    ├── rules/
    │   ├── testing.md
    │   ├── code-style.md
    │   └── security.md
    └── settings.json

Hier kann README.md die Informationen enthalten, die Menschen für den Einstieg in das Repository benötigen; ARCHITECTURE.md kann die zentralen Grenzen und die Struktur des Systems beschreiben; und docs/ kann umfangreiches, detailliertes Wissen zu Design, Produkt und Betrieb aufnehmen. Das tatsächliche Layout von src/ und tests/ sollte sich primär nach der bestehenden Projektstruktur richten. .claude/rules/ ist ein Ort für themen- oder pfadspezifische Regeln für Claude Code. code.claude.com↗

Wenn Sie sich wegen vieler Dateien im Root sorgen, ist nicht die Anzahl der Dateinamen entscheidend, sondern die Trennung der Verantwortlichkeiten. Wenn eine Datei zugleich Projekteinstieg, Systemdesign, Betriebsreaktion, detaillierte API-Konventionen und Stilregeln übernimmt, wird es schwierig zu erkennen, welche Informationen für die aktuelle Aufgabe wesentlich sind. Ein kurzer Root-Leitfaden, der auf die erforderlichen detaillierten Dokumente verweist, ermöglicht Mitwirkenden dagegen, nur so tief wie nötig einzusteigen.

Dasselbe Prinzip gilt für Anweisungsdateien in feature-spezifischen Ordnern. Fügen Sie keine hinzu, sofern das Feature keine eigenen Regeln hat; fügen Sie eine nur bei einem klaren Grund hinzu, etwa bei der Verarbeitung sensibler Daten oder einem automatisierten Generierungsprozess. Eine häufige Vermehrung von Regeldateien kann die Struktur selbst verkomplizieren, anstatt sie zu erklären.

Wie können Sie doppelte Regeln bei der Nutzung beider Tools reduzieren?

Eine Möglichkeit besteht darin, die maßgeblichen gemeinsamen Entwicklungskonventionen in AGENTS.md zu halten, sie aus der Root-CLAUDE.md zu importieren und anschließend nur Inhalte zu ergänzen, die Claude Code benötigt. Zum Beispiel:

@AGENTS.md

## Nur Claude Code
- Lege vor Änderungen an `src/payments/` einen Plan vor.
- Befolge die pfadspezifischen Regeln in `.claude/rules/`.

Diese Konfiguration reduziert die Notwendigkeit, Testbefehle, gemeinsame Benennungsregeln und Grundsätze zu generierten Dateien in beiden Dateien wiederholt zu pflegen. Gleichzeitig bewahrt sie Claude-Code-spezifische Regeln und eine Konfiguration auf Basis von .claude/rules/. Wie bereits erwähnt, liest Claude Code AGENTS.md jedoch nicht automatisch als gemeinsame Anweisungen. Sie müssen daher tatsächlich einen Import oder eine gleichwertige Verbindung konfigurieren. code.claude.com↗

Der Speicherort der gemeinsamen Datei kann von der relativen Nutzung der Tools durch das Team und bestehenden Repository-Konventionen abhängen. Wird Codex am häufigsten eingesetzt, ist AGENTS.md eine naheliegende maßgebliche Quelle; konzentriert sich der Betrieb auf das Regelsystem von Claude Code, kann CLAUDE.md stattdessen die maßgebliche Quelle sein. Unabhängig von der Wahl ist entscheidend, für jede Regel ein maßgebliches Original festzulegen und in der anderen Datei nur Verweise oder tool-spezifische Ergänzungen zu belassen.

Es ist am besten, individuelle Präferenzen von Teamkonventionen zu trennen. Befehlsaliase in einer persönlichen Umgebung, lokale Tool-Auswahl und persönliche Arbeitsgewohnheiten können in persönliche Überschreibungsdateien gehören. Testverfahren, Sicherheitseinschränkungen und Codestruktur, die alle Personen kennen müssen, welche das Repository klonen, sollten dagegen in versionierten Projektanweisungen verbleiben. Sowohl Codex als auch Claude Code unterstützen Anweisungskonfigurationen auf Projekt- und persönlicher Ebene. openai.com↗code.claude.com↗

Warum sollten Validierungsbefehle im Mittelpunkt der Anweisungen stehen?

Die Vorschläge oder Änderungen eines Coding-Agents mögen plausibel aussehen, garantieren aber nicht automatisch Korrektheit, Kompatibilität oder Sicherheit. Codex-bezogene Anleitungen erläutern ebenfalls, dass menschliches Review und die Validierung der Ausgabe weiterhin erforderlich sind. openai.com↗

Daher erläutern gute Repository-Anweisungen nicht nur, „wie programmiert wird“, sondern auch, „wie geprüft wird“. Listen Sie nach Möglichkeit Befehle für Formatierung, Linting, Typprüfung, Unit-Tests, Integrationstests und Builds in Formen auf, die tatsächlich ausgeführt werden können. Bei großen Repositorys, in denen eine vollständige Validierung für jede Aufgabe unpraktisch ist, können Sie eine Mindestvalidierung nach Änderungsort von Bedingungen unterscheiden, die eine vollständige Validierung erfordern.

Dokumentationsaktualisierungen können beispielsweise nur eine Link-Prüfung oder einen Dokumentations-Build erfordern, während Änderungen an einem öffentlichen API-Vertrag sowohl Unit- als auch Integrationstests verlangen können. Schwer rückgängig zu machende Änderungen, etwa an Datenbankschemas oder Infrastrukturkonfigurationen, können eine zusätzliche Review-Stufe benötigen. Wichtig ist nicht, vom Tool eine magische Risikobewertung zu erwarten, sondern die dem Team bereits bekannten Validierungspfade ausdrücklich im Repository festzuhalten.

Auch generierter Code und Build-Artefakte sollten aus Validierungssicht klar unterschieden werden. Wenn Dateien nicht direkt bearbeitet werden dürfen, dokumentieren Sie ihren Quellort und das Generierungsverfahren; ist die Bearbeitung eines Artefakts zulässig, nennen Sie den Befehl, der es aktualisiert. Ebenso ist es sicherer, klar festzuhalten, dass Secrets und umgebungsspezifische persönliche Einstellungen nicht in das Repository gehören, wo Beispieldateien liegen und welche Validierungsschritte erforderlich sind.

Was sind häufige Missverständnisse und Fehlermuster?

Das erste Missverständnis lautet: „Mehr Anweisungen führen zu besserer Befolgung.“ In der Praxis können lange Dokumente die wichtigsten Regeln vergraben. Sind Anweisungen zu lang geworden, entfernen Sie doppelte Erläuterungen, bereits automatisierte Regeln und nicht mehr gültige Ausnahmen und verschieben Sie detailliertes Wissen in separate Dokumente. code.claude.com↗openai.com↗

Das zweite lautet: „Jeder Ordner braucht eine Anweisungsdatei.“ Verschachtelte Anweisungen sind nur dort nützlich, wo besondere Einschränkungen bestehen. Eine verschachtelte Datei ohne Spezifität fügt lediglich eine weitere zu lesende Datei hinzu und kann ihr Verhältnis zu übergeordneten Regeln unklar machen.

Das dritte lautet: „Die Einhaltung von Stilregeln reicht aus.“ Selbst bei konsistenter Formatierung ist eine Änderung nicht unbedingt gut, wenn Tests nicht ausgeführt wurden, Domain-Regeln verletzt wurden oder generierte Dateien direkt bearbeitet wurden. Stilautomatisierung sowie Test- und Review-Verfahren sind keine Ersatzmaßnahmen; sie sind Schutzvorkehrungen, die zusammenwirken.

Das vierte lautet: „Das Tool löst Widersprüche in der Dokumentation selbstständig.“ Wenn über- und untergeordnete Anweisungen oder gemeinsame und tool-spezifische Anweisungen kollidieren, ist das Ergebnis schwer vorhersehbar. Halten Sie dieselbe Regel an einer Stelle und machen Sie den Geltungsbereich sowie zusätzliche Bedingungen untergeordneter Regeln klar. Da die Speicherkonfiguration von Claude Code ebenfalls hierarchische Anweisungen verarbeitet, ist es wichtig, Regeln so zu gestalten, dass Konflikte vermieden werden. code.claude.com↗

Behandeln Sie eine Anweisungsdatei schließlich nicht als Qualitätsgarantie. Anweisungen liefern Kontext, der die Beurteilung von Agents und Menschen unterstützt; sie sind keine Mechanismen, die Korrektheit, Sicherheit oder bestehende Tests für generierten Code garantieren. Die Überprüfung von Änderungen und erforderliche Validierungen bleiben unverzichtbar. openai.com↗

Was sollten wir zuerst in unserem Repository umsetzen?

Sie müssen nicht die gesamte Ordnerstruktur von Anfang an neu gestalten. Realistischer ist es, mit kleinen Verbesserungen zu beginnen, die auf wiederkehrender Verwirrung im aktuellen Repository basieren. Wenn neue Mitwirkende beispielsweise den Testbefehl nicht finden, fügen Sie ihn den Root-Anweisungen hinzu. Treten im Zahlungsmodul immer wieder dieselben Fehler auf, ergänzen Sie spezifische Regeln nur für diesen Pfad. Sind Designdokumente mit Code vermischt und schwer zu navigieren, unterscheiden Sie zunächst Dokumenttypen innerhalb von docs/.

Sie können eine Bewertungsreihenfolge wie diese verwenden:

1. Identifizieren Sie die Konventionen für Dateiablage, Benennung und Tests, die im aktuellen Codebestand tatsächlich wiederkehren.
2. Ordnen Sie die Befehle und Fehlerbedingungen für Formatter, Linter, Typprüfungen und Tests.
3. Identifizieren Sie Domain-Einschränkungen, Bereiche ohne Bearbeitung und Generierungsverfahren, die allein aus dem Code schwer zu verstehen sind.
4. Schreiben Sie nur die wichtigsten Inhalte kurz in die Root-AGENTS.md oder CLAUDE.md.
5. Fügen Sie verschachtelte Anweisungen oder pfadspezifische Regeln nur in sensiblen Bereichen hinzu, die allgemeine Regeln nicht erklären können.
6. Legen Sie eine Originalquelle für gemeinsame Regeln fest und belassen Sie in Dateien für das andere Tool nur Verweise und tool-spezifische Regeln.
7. Prüfen Sie regelmäßig, ob Anweisungen bei der realen Arbeit hilfreich waren und ob sie unnötige oder widersprüchliche Aussagen enthalten.

Dabei müssen Sie „für Tools leicht verständlich“ und „für Menschen leicht wartbar“ nicht als gegensätzliche Ziele behandeln. Kurze, präzise Dokumentation, vorhersehbare Modulgrenzen und automatisch ausführbare Validierung helfen beiden. Umgekehrt führt der Versuch, eine Struktur, die selbst Menschen kaum erklären können, allein mit Anweisungsdateien auszugleichen, wahrscheinlich zu unhandlicher Dokumentation.

Fazit: Welche Konventionen sollten Sie wählen?

Der Schlüssel zu für Codex und Claude Code geeigneten Verzeichniskonventionen und Code-Stilen liegt nicht darin, eine bestimmte trendige Struktur zu übernehmen. Ein praktischer Ansatz besteht darin, die Konventionen des bestehenden Codebestands konsistent beizubehalten, im Root einen kurzen Leitfaden vorzuhalten, detailliertes Wissen in passende Dokumente zu trennen und eng abgegrenzte Regeln nur dort hinzuzufügen, wo sie benötigt werden.

Für Codex können Sie AGENTS.md verwenden; für Claude Code CLAUDE.md und bei Bedarf .claude/rules/. Wenn Sie beide Tools einsetzen, bestimmen Sie eine einzige Quelle für gemeinsame Regeln und verbinden Sie die gemeinsame Datei in Claude Code ausdrücklich, um Duplikate zu reduzieren. Kombinieren Sie Anweisungen vor allem mit Formattern, Lintern, Typprüfungen, Tests und menschlichem Review. Da sich die Interpretation produktspezifischer Anweisungen je nach Version ändern kann, empfiehlt es sich, Regeln klein und klar zu halten und gleichzeitig die offizielle Dokumentation der tatsächlich eingesetzten Tools zu prüfen. openai.com↗code.claude.com↗