Welke mapconventies en codestijlen volgen Codex en Claude Code goed?

Codex en Claude Code hebben niet van nature een voorkeur voor een bepaalde programmeertaal, framework, inspringbreedte of mapindeling. De omgevingen die zij relatief betrouwbaar kunnen volgen, zijn omgevingen waarin bestaande repositoryconventies consistent zijn, het bereik van vereiste regels duidelijk is en wijzigingen automatisch kunnen worden gevalideerd. Het doel is daarom niet om een structuur te bedenken die een AI misschien prettig vindt, maar om projectconventies zo te maken dat mensen en nieuwe bijdragers ze kort kunnen begrijpen en verifiëren. openai.com↗code.claude.com↗

Hier verwijzen Codex en Claude Code naar coding-agenttools die bestanden in een repository kunnen lezen, instructies kunnen raadplegen, code kunnen wijzigen of commando's kunnen uitvoeren. Dergelijke tools halen veel aanwijzingen uit de code zelf, maar kunnen productdomeinterminologie, verboden wijzigingen, controles vóór implementatie of uitzonderingsregels voor specifieke mappen niet altijd nauwkeurig afleiden. Repositorystructuur, instructiebestanden en uitvoerbare validatieprocedures vullen dat gat op. cdn.openai.com↗

Waarom is consistentie belangrijker dan de “juiste mapstructuur”?

Een team kan bijvoorbeeld src/payments/ en src/users/ per functionaliteit organiseren, terwijl een ander team src/controllers/, src/services/ en src/repositories/ per laag indeelt. Er is geen grond om definitief te stellen dat een van beide aanpakken automatisch beter is voor Codex of Claude Code. Belangrijk is dat verantwoordelijkheden van hetzelfde soort vergelijkbare locaties binnen een repository hebben, dat nieuwe bestanden volgens dezelfde criteria worden geplaatst en dat tests en importstijlen bestaande patronen volgen.

Hetzelfde geldt wanneer een agent een nieuwe betaalfunctionaliteit toevoegt. Als de bestaande betaalmodule laat zien hoe requestvalidatie, foutafhandeling, gegevenstoegang en tests zijn georganiseerd, is het veiliger om dat patroon voort te zetten. Als daarentegen elke nieuwe functionaliteit nieuwe bestandsnamen en lagen introduceert, of als één map domeincode mengt met buildartefacten en tijdelijke bestanden, zullen zowel agents als mensen moeite hebben om te bepalen waar wijzigingen moeten worden aangebracht en wat die wijzigingen beïnvloeden.

Mapconventies zijn daarom niet slechts regels voor het uiterlijk. Ze vormen een navigatiesysteem dat laat zien waar code te vinden is, wat samen gewijzigd moet worden en welke validatie moet worden uitgevoerd. Hoe stabieler de namen en grenzen zijn, hoe minder vaak lange uitleg in instructiebestanden hoeft te worden herhaald.

Waar moet de basisrichtlijn van de repository staan?

In Codex dient AGENTS.md doorgaans als projectinstructiebestand. Instructies voor codestijl, structuur, naamgeving en testen in dit bestand gelden voor de map waarin het staat en de onderliggende structuur, terwijl instructies op diepere locaties als specifiekere richtlijnen kunnen fungeren als er conflicten ontstaan. Instructies voor persoonlijke omgevingen en overschrijvingen via AGENTS.override.md worden ook ondersteund. openai.com↗

In Claude Code kunnen CLAUDE.md of .claude/CLAUDE.md fungeren als het centrum voor projectgeheugen en richtlijnen. Een CLAUDE.md in een bovenliggend pad kan bij het opstarten als context worden meegegeven, terwijl bestanden in submappen zo nodig worden geladen wanneer bestanden op die paden worden behandeld. Je kunt ook CLAUDE.local.md gebruiken voor instellingen per gebruiker en bestanden op het niveau van de homedirectory. code.claude.com↗

Hoewel de twee bestanden vergelijkbare namen hebben, is hun gedrag voor automatische ontdekking niet hetzelfde. Ga er met name niet van uit dat Claude Code AGENTS.md automatisch als gedeelde instructies leest. Wanneer je beide tools gebruikt, importeer je het gedeelde bestand in CLAUDE.md met @AGENTS.md, of definieer je expliciet een koppeling die past bij het werkwijze van het team. code.claude.com↗

Het is het beste om het richtlijnbestand in de root meer als een startkaart te houden dan als een encyclopedie die de volledige repository uitvoerig beschrijft. Het volstaat om de commando's te tonen die een nieuwe bijdrager eerst nodig heeft, de structuur op hoofdniveau, belangrijke invarianten en de locaties van gedetailleerde documentatie. Eén lang instructiebestand verbruikt context die voor de daadwerkelijke code en taakvereisten gebruikt zou moeten worden, en kan kritieke beperkingen moeilijker zichtbaar maken. Een voorbeeld rond OpenAI Codex presenteert eveneens een combinatie van een kort, kaartachtig bestand van ongeveer 100 regels en afzonderlijke documentatie. openai.com↗

Wat moeten AGENTS.md en CLAUDE.md bevatten?

Goede instructies dupliceren niet uitgebreid feiten die al duidelijk uit de code blijken. In plaats daarvan geven ze voorrang aan informatie die moeilijk alleen uit code te leren is of kostbaar is om verkeerd af te leiden. Materiaal over Codex noemt naamgevingsconventies, domeintaal, bekende beperkingen en afhankelijkheden, en build- en testprocedures als informatie die de moeite waard is om in AGENTS.md te plaatsen. cdn.openai.com↗

Rootinstructies kunnen beknopt vragen beantwoorden zoals:

• Welke commando's voeren formatting, statische analyse, typecontrole en tests uit na een eerste wijziging?
• Waar bevinden broncode, tests, ontwerpdocumentatie en operationele documentatie zich?
• Welke conventies voor bestandsnamen, imports, foutafhandeling en testen moeten worden gevolgd bij het uitbreiden van een bestaande module?
• Mogen gegenereerde bestanden, buildartefacten, lockbestanden en secrets worden gewijzigd of in de repository worden opgenomen?
• Vereisen gebieden met een hoog risico een plan, aanvullende beoordeling of specifieke tests?
• Welke documenten bevatten gedetailleerde ontwerp- en operationele procedures?

Daarentegen zijn algemene uitspraken zoals “schrijf schone code”, “geef prioriteit aan beveiliging” of “doe je best” moeilijk om te zetten in uitvoerbare regels. Een uitspraak als “gebruik de bestaande validatiemodule voor externe invoer en voeg de bijbehorende integratietest toe voor elke nieuwe API-route” is nuttiger omdat deze kan worden waargenomen en geverifieerd. Richtlijnen voor Claude Code benadrukken eveneens dat projectspecifieke regels concreet moeten worden geschreven en dat instructies regelmatig moeten worden beoordeeld en georganiseerd naarmate ze groeien. code.claude.com↗

Instructies moeten een gecomprimeerde vastlegging van besliscriteria zijn, geen document dat elk implementatiedetail voorschrijft. Kennis die lang is en waarschijnlijk verandert — zoals het gebruik van een bepaalde library, API-contracten of de volgorde van incidentrespons — is eenvoudiger te onderhouden wanneer deze wordt verplaatst naar een passend document onder docs/, terwijl rootinstructies de locatie en gebruiksvoorwaarden aangeven.

Wanneer zijn regels voor afzonderlijke submappen nodig?

Regels voor submappen zijn geen bestanden die je mechanisch aan elke map moet toevoegen. Waar gedeelde rootregels voldoende zijn, kunnen afzonderlijke bestanden juist de navigatie-overhead en de kans op conflicten verhogen. Je kunt ze het beste reserveren voor grenzen die duidelijk afwijken van de algemene regels of waar fouten aanzienlijke gevolgen hebben.

Zo kan src/payments/ documenteren hoe geldberekeningen moeten worden uitgedrukt, hoe mocks voor externe betalingsproviders moeten worden gebruikt en welk specifiek integratietestcommando moet worden uitgevoerd. infra/ kan vóór wijzigingen een plan vereisen, controles voordat ze worden toegepast, en beperkingen opleggen aan welke omgevingsspecifieke bestanden mogen worden gewijzigd. generated/ kan aangeven dat directe bewerkingen verboden zijn en de bron en het generatiecommando benoemen. Het doel van deze regels is niet om de map bijzonder te laten lijken, maar om de werkelijke beperkingen van dat gebied nauwkeurig in de werkcontext aan te bieden.

Voor Codex geldt een genest AGENTS.md onder de eigen map, en diepere bestanden kunnen specifiekere regels bieden. Claude Code kan eveneens meerdere CLAUDE.md-bestanden als context opstapelen, dus het is veiliger als geneste bestanden concrete voorwaarden toevoegen die alleen in dat gebied nodig zijn, in plaats van dubbelzinnige verklaringen af te leggen die bovenliggende bestanden tenietdoen. openai.com↗code.claude.com↗

De root kan bijvoorbeeld zeggen: “Voer tests uit voor het pakket dat je hebt gewijzigd”, terwijl de betalingsmap zegt: “Als het betalingscontract wijzigt, voer dan zowel unit- als integratietests uit.” Daarentegen zorgt “Tests moeten altijd worden uitgevoerd” in de root en “Voer geen tests uit” in een submap ervoor dat niet alleen tools, maar ook mensen niet weten welke regel ze moeten volgen.

Hoe moet je Claude Code's .claude/rules/ opsplitsen?

In Claude Code kun je globale regels die altijd nodig zijn in CLAUDE.md plaatsen en regels met verschillende onderwerpen of padafhankelijk gedrag opsplitsen in kleine bestanden onder .claude/rules/. Regelbestanden kunnen recursief worden georganiseerd en padvoorwaarden kunnen regels uitsluitend toepassen op bepaalde bestanden of gebieden. code.claude.com↗

Het criterium voor opsplitsen is niet het aantal bestanden, maar de samenhang van regels die samen veranderen. Commando's voor tests en principes voor testdata kunnen bijvoorbeeld in testing.md staan; uitzonderingen voor imports, naamgeving en formatting in code-style.md; en beperkingen rond secrets, externe requests en rechten in security.md. Elk bestand moet één onderwerp behandelen en de titel moet duidelijk maken wanneer het moet worden gelezen.

Het voordeel van deze aanpak is dat onnodige instructies niet voortdurend volledig hoeven te worden gelezen. Als bijvoorbeeld de volledige regels voor databasemigraties gemengd blijven met werk dat alleen documentatie wijzigt, kunnen ze de belangrijkste instructies verbergen. Maar regels te fijn opsplitsen maakt hun locaties moeilijk vindbaar. Een evenwichtige aanpak is om de belangrijkste regelgroepen en hun doel kort in de root-CLAUDE.md te introduceren en de daadwerkelijke inhoud in onderwerpsspecifieke bestanden te bewaren.

Vermijd na het scheiden van regels om dezelfde verplichting in meerdere bestanden te kopiëren. Kopieën lopen in de loop van de tijd gemakkelijk uiteen. Door gedeelde principes op één plek te houden en alleen uitzonderingen en aanvullende voorwaarden in padspecifieke bestanden vast te leggen, verminder je conflicten.

Hoe moet codestijl worden gespecificeerd?

“AI-vriendelijke codestijl” betekent niet één universele keuze, zoals tabs versus spaties of functioneel versus objectgeoriënteerd programmeren. Het belangrijkere criterium is of de lokale conventies van de repository kunnen worden gereproduceerd. Reviews en onderhoud worden eenvoudiger wanneer een nieuwe module de patronen van bestaande modules volgt voor bestandsnamen, exportstijl, importvolgorde, foutafhandelingspaden en teststructuur.

Elke keuze van het project die afwijkt van de gangbare conventies voor de taal is bijzonder de moeite waard om te documenteren. Claude Code-documentatie noemt projectspecifieke codestijl, zoals ES-modules of destructuring met named imports, als voorbeelden. Met andere woorden: in plaats van elke standaardregel van een taal opnieuw te schrijven, is het efficiënter om te beschrijven “wat ons project anders doet dan de standaard”. code.claude.com↗

De volgende tabel biedt eenvoudige criteria voor het bepalen van stijlrichtlijnen.

Formatters, linters en typecheckers maken stijl mechanisch testbaar in plaats van deze via proza af te dwingen. Daarom is het beter dat instructies de werkelijke uit te voeren commando's en de verwachte afhandeling van fouten specificeren dan dat ze zeggen “formatteer alles netjes”. Claude Code-best practices bevelen ook duidelijke projectinstructies en verifieerbare ontwikkelworkflows aan. code.claude.com↗

Met welke mapstructuur kun je beginnen?

Hieronder staat een voorbeeld dat je kunt gebruiken wanneer je Codex en Claude Code samen overweegt. Het is geen verplichte standaard, maar een mogelijk uitgangspunt dat gedeelde instructies, gedetailleerde documentatie en gebiedsspecifieke uitzonderingen scheidt.

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 kan README.md de informatie bevatten die mensen nodig hebben om met de repository te beginnen, kan ARCHITECTURE.md de belangrijkste grenzen en structuur van het systeem beschrijven en kan docs/ uitgebreide, gedetailleerde ontwerp-, product- en operationele kennis bevatten. De daadwerkelijke indeling van src/ en tests/ moet vooral de bestaande structuur van het project volgen. .claude/rules/ is een locatie voor onderwerpsspecifieke of padspecifieke regels voor Claude Code. code.claude.com↗

Als je je zorgen maakt over veel bestanden in de root, is het belangrijkste punt niet het aantal bestandsnamen, maar de scheiding van verantwoordelijkheden. Als één bestand tegelijkertijd projectintroductie, systeemontwerp, operationele respons, gedetailleerde API-conventies en stijlregels behandelt, wordt het moeilijk te weten welke informatie essentieel is voor de huidige taak. Een korte rootgids die naar de vereiste gedetailleerde documenten wijst, laat bijdragers daarentegen slechts zo diep verkennen als nodig is.

Hetzelfde principe geldt voor het plaatsen van instructiebestanden in functionaliteitsspecifieke mappen. Voeg er geen toe tenzij de functionaliteit eigen regels heeft; voeg er alleen een toe wanneer daar een duidelijke reden voor is, zoals het omgaan met gevoelige gegevens of een geautomatiseerd generatieproces. Een sterke toename van regelbestanden kan de structuur zelf ingewikkelder maken in plaats van die uit te leggen.

Hoe kun je dubbele regels verminderen wanneer je beide tools gebruikt?

Een optie is om de canonieke gedeelde ontwikkelconventies in AGENTS.md te bewaren, dit vanuit de root-CLAUDE.md te importeren en vervolgens alleen inhoud toe te voegen die Claude Code nodig heeft. Bijvoorbeeld:

@AGENTS.md

## Claude Code only
- Present a plan before changing `src/payments/`.
- Follow the path-specific rules in `.claude/rules/`.

Deze opzet vermindert de noodzaak om testcommando's, algemene naamgevingsregels en principes voor gegenereerde bestanden herhaaldelijk in beide bestanden te onderhouden. Tegelijkertijd behoudt deze Claude Code-specifieke regels en een configuratie op basis van .claude/rules/. Zoals hierboven vermeld, leest Claude Code AGENTS.md echter niet automatisch als gedeelde instructies, dus je moet daadwerkelijk een import of gelijkwaardige koppeling configureren. code.claude.com↗

Waar het gedeelde bestand moet staan, kan afhangen van het relatieve gebruik van de tools door het team en van bestaande repositoryconventies. Als Codex het vaakst wordt gebruikt, is AGENTS.md een eenvoudige canonieke bron; als de werkwijze draait om het regelsysteem van Claude Code, kan CLAUDE.md in plaats daarvan de canonieke bron zijn. Ongeacht de keuze is het belangrijk om voor elke regel één gezaghebbende oorspronkelijke bron aan te wijzen en in het andere bestand alleen verwijzingen of toolspecifieke toevoegingen te laten staan.

Het is het beste om individuele voorkeuren te scheiden van teamconventies. Commandaliasen in een persoonlijke omgeving, lokale toolkeuzes en persoonlijke werkgewoonten kunnen thuishoren in persoonlijke overridebestanden. Testprocedures, beveiligingsbeperkingen en codestructuur die iedereen die de repository kloont moet kennen, moeten daarentegen in versiebeheerbare projectinstructies blijven. Zowel Codex als Claude Code ondersteunen instructieconfiguraties op project- en persoonlijk niveau. openai.com↗code.claude.com↗

Waarom moeten validatiecommando's centraal staan in instructies?

De voorstellen of wijzigingen van een coding agent kunnen aannemelijk lijken, maar garanderen niet automatisch correctheid, compatibiliteit of beveiliging. Richtlijnen rond Codex leggen ook uit dat menselijke beoordeling en validatie van output nog steeds nodig zijn. openai.com↗

Daarom leggen goede repositoryinstructies niet alleen uit “hoe te coderen”, maar ook “hoe te controleren”. Vermeld waar mogelijk commando's voor formatting, linting, typecontrole, unittests, integratietests en builds in vormen die daadwerkelijk kunnen worden uitgevoerd. Voor grote repositories waarin volledige validatie voor elke taak onpraktisch is, kun je minimale validatie per wijzigingslocatie onderscheiden van voorwaarden die volledige validatie vereisen.

Documentatie-updates kunnen bijvoorbeeld alleen linkcontrole of een documentatiebuild vereisen, terwijl wijzigingen aan een openbaar API-contract zowel unit- als integratietests kunnen vereisen. Wijzigingen die moeilijk terug te draaien zijn, zoals databaseschema's of infrastructuurconfiguratie, kunnen een extra beoordelingsfase vereisen. Het belangrijkste is niet te verwachten dat de tool risico op magische wijze beoordeelt, maar expliciet de validatiepaden vast te leggen die het team al kent in de repository.

Gegenereerde code en buildartefacten moeten ook vanuit validatieperspectief duidelijk worden onderscheiden. Als bestanden niet rechtstreeks mogen worden bewerkt, documenteer dan hun bronlocatie en generatieprocedure; als het bewerken van een artefact is toegestaan, vermeld dan welk commando het bijwerkt. Het is ook veiliger om duidelijk het principe te maken dat secrets en omgevingsspecifieke persoonlijke instellingen niet in de repository thuishoren, alsmede de locatie van voorbeeldbestanden en de vereiste validatiestappen.

Wat zijn veelvoorkomende misvattingen en faalpatronen?

De eerste misvatting is dat “meer instructies tot betere naleving leiden”. In de praktijk kunnen lange documenten de belangrijkste regels begraven. Als instructies te lang zijn geworden, verwijder dan dubbele uitleg, regels die al geautomatiseerd zijn en uitzonderingen die niet langer geldig zijn, en verplaats gedetailleerde kennis naar afzonderlijke documenten. code.claude.com↗openai.com↗

De tweede is dat “elke map een instructiebestand nodig heeft”. Geneste instructies zijn alleen nuttig waar bijzondere beperkingen gelden. Een genest bestand zonder specificiteit voegt slechts nog een te lezen bestand toe en kan de relatie met bovenliggende regels onduidelijk maken.

De derde is dat “het volgen van stijlregels voldoende is”. Ook als formatting consistent is, is een wijziging niet noodzakelijk goed wanneer tests niet zijn uitgevoerd, domeinregels zijn geschonden of gegenereerde bestanden rechtstreeks zijn bewerkt. Stijlautomatisering en test- en reviewprocedures zijn geen vervangers; het zijn waarborgen die samen werken.

De vierde is dat “de tool tegenstrijdigheden in documentatie zelf zal oplossen”. Wanneer instructies van ouder- en kindniveau, of gedeelde en toolspecifieke instructies, conflicteren, wordt het resultaat moeilijk voorspelbaar. Bewaar dezelfde regel op één plek en maak het bereik en de aanvullende voorwaarden van kindregels duidelijk. Omdat de geheugenconfiguratie van Claude Code eveneens hiërarchische instructies verwerkt, is het belangrijk regels zo te ontwerpen dat conflicten worden vermeden. code.claude.com↗

Behandel een instructiebestand ten slotte niet als kwaliteitsgarantie. Instructies leveren context die het oordeel van agents en mensen ondersteunt; ze zijn geen mechanismen die de correctheid, beveiliging of geslaagde tests van gegenereerde code garanderen. Het beoordelen van wijzigingen en uitvoeren van noodzakelijke validatie blijft essentieel. openai.com↗

Wat moeten we als eerste toepassen in onze repository?

Je hoeft niet vanaf het begin de volledige mapstructuur opnieuw te ontwerpen. Het is realistischer om te beginnen met kleine verbeteringen op basis van terugkerende verwarring in de huidige repository. Als nieuwe bijdragers bijvoorbeeld het testcommando niet kunnen vinden, voeg dit dan toe aan rootinstructies. Als in de betalingsmodule steeds dezelfde fouten optreden, voeg dan alleen voor dat pad specifieke regels toe. Als ontwerpdocumenten met code zijn vermengd en moeilijk te navigeren zijn, onderscheid dan eerst documenttypen binnen docs/.

Je kunt een beoordelingsvolgorde als deze gebruiken:

1. Identificeer de conventies voor bestandsplaatsing, naamgeving en testen die daadwerkelijk terugkomen in de huidige codebase.
2. Organiseer de commando's en foutvoorwaarden voor formatters, linters, typecontroles en tests.
3. Identificeer domeinbeperkingen, gebieden die niet mogen worden bewerkt en generatieprocedures die moeilijk alleen uit code te begrijpen zijn.
4. Schrijf alleen de belangrijkste inhoud beknopt in de root-AGENTS.md of CLAUDE.md.
5. Voeg geneste instructies of padspecifieke regels alleen toe aan gevoelige gebieden die algemene regels niet kunnen verklaren.
6. Wijs één oorspronkelijke bron aan voor gedeelde regels en laat in bestanden voor de andere tool alleen verwijzingen en toolspecifieke regels staan.
7. Beoordeel regelmatig of instructies in het echte werk behulpzaam waren en of ze onnodige of tegenstrijdige uitspraken bevatten.

In dit proces hoef je “gemakkelijk te begrijpen voor tools” en “gemakkelijk te onderhouden voor mensen” niet als tegengestelde doelen te behandelen. Korte, nauwkeurige documentatie, voorspelbare modulegrenzen en automatisch uitvoerbare validatie helpen beide. Andersom zal het proberen te compenseren voor een structuur die zelfs voor mensen moeilijk uit te leggen is met alleen instructiebestanden, de documentatie waarschijnlijk onhandelbaar maken.

Conclusie: welke conventies moet je kiezen?

De sleutel tot mapconventies en codestijlen die geschikt zijn voor Codex en Claude Code is niet het overnemen van een bepaalde modieuze structuur. Een praktische aanpak is om de conventies van de bestaande codebase consequent te onderhouden, een korte gids in de root te houden, gedetailleerde kennis in passende documenten te scheiden en alleen waar nodig nauw afgebakende regels toe te voegen.

Voor Codex kun je AGENTS.md gebruiken; voor Claude Code CLAUDE.md en, waar nodig, .claude/rules/. Als je beide tools gebruikt, wijs dan één bron aan voor gedeelde regels en koppel het gedeelde bestand expliciet in Claude Code om duplicatie te verminderen. Combineer instructies vooral met formatters, linters, typecontroles, tests en menselijke beoordeling. Omdat de interpretatie van productspecifieke instructies per versie kan veranderen, is het raadzaam regels klein en duidelijk te houden en tegelijk de officiële documentatie te controleren voor de tools die je daadwerkelijk gebruikt. openai.com↗code.claude.com↗