Quelles conventions de répertoires et quels styles de code Codex et Claude Code suivent-ils bien ?

Codex et Claude Code ne préfèrent pas intrinsèquement un langage de programmation, un framework, une largeur d’indentation ou une organisation de dossiers particulière. Les environnements qu’ils peuvent suivre de façon relativement fiable sont ceux où les conventions existantes du dépôt sont cohérentes, la portée des règles requises est claire et les modifications peuvent être validées automatiquement. L’objectif n’est donc pas d’inventer une structure susceptible de plaire à une IA, mais de rendre les conventions du projet compréhensibles, courtes et vérifiables pour les personnes et les nouveaux contributeurs. openai.com↗code.claude.com↗

Ici, Codex et Claude Code désignent des outils d’agents de programmation capables de lire des fichiers dans un dépôt, de consulter des instructions, de modifier du code ou d’exécuter des commandes. Ces outils tirent de nombreux indices du code lui-même, mais ils ne peuvent pas toujours déduire correctement la terminologie métier du produit, les modifications interdites, les contrôles avant déploiement ou les règles d’exception propres à certains dossiers. La structure du dépôt, les fichiers d’instructions et les procédures de validation exécutables comblent cette lacune. cdn.openai.com↗

Pourquoi la cohérence est-elle plus importante que la « bonne structure de dossiers » ?

Par exemple, une équipe peut organiser src/payments/ et src/users/ par fonctionnalité, tandis qu’une autre peut organiser src/controllers/, src/services/ et src/repositories/ par couche. Rien ne permet d’affirmer de manière concluante que l’une ou l’autre approche est automatiquement meilleure pour Codex ou Claude Code. Ce qui importe est que les responsabilités de même nature soient situées de façon similaire dans un dépôt, que les nouveaux fichiers soient placés selon les mêmes critères et que les tests ainsi que les styles d’import suivent les modèles existants.

Il en va de même lorsqu’un agent ajoute une nouvelle fonctionnalité de paiement. Si le module de paiement existant montre comment sont organisés la validation des requêtes, la gestion des erreurs, l’accès aux données et les tests, poursuivre ce modèle est plus sûr. À l’inverse, si chaque nouvelle fonctionnalité introduit de nouveaux noms de fichiers et de nouvelles couches, ou si un même dossier mélange code métier, artefacts de build et fichiers temporaires, les agents comme les personnes auront du mal à déterminer où effectuer les modifications et ce qu’elles affectent.

Les conventions de répertoires ne sont donc pas de simples règles d’apparence. Elles constituent un système de navigation indiquant où trouver le code, ce qui doit être modifié ensemble et quelle validation exécuter. Plus les noms et les limites sont stables, moins il est nécessaire de répéter de longues explications dans les fichiers d’instructions.

Où placer les orientations de base du dépôt ?

Dans Codex, AGENTS.md sert généralement de fichier d’instructions du projet. Les instructions de style de code, de structure, de nommage et de tests contenues dans ce fichier s’appliquent au répertoire qui le contient et à son sous-arbre, tandis que les instructions situées plus profondément peuvent servir de consignes plus spécifiques en cas de conflit. Les instructions pour l’environnement personnel et les remplacements par AGENTS.override.md sont également pris en charge. openai.com↗

Dans Claude Code, CLAUDE.md ou .claude/CLAUDE.md peut servir de centre pour la mémoire et les orientations du projet. Un CLAUDE.md placé dans un chemin parent peut être fourni comme contexte au démarrage, tandis que les fichiers de sous-répertoires sont chargés selon les besoins lors du traitement de fichiers à ces emplacements. Vous pouvez aussi utiliser CLAUDE.local.md pour des paramètres par utilisateur et des fichiers au niveau du répertoire personnel. code.claude.com↗

Bien que les deux fichiers portent des noms semblables, leur comportement de découverte automatique n’est pas le même. En particulier, ne supposez pas que Claude Code lit automatiquement AGENTS.md comme instructions partagées. Lorsque vous utilisez les deux outils, importez le fichier partagé dans CLAUDE.md avec @AGENTS.md, ou définissez explicitement une connexion adaptée au modèle de fonctionnement de l’équipe. code.claude.com↗

Il est préférable de rapprocher le fichier d’orientation racine d’une carte d’entrée plutôt que d’une encyclopédie décrivant longuement l’intégralité du dépôt. Il suffit d’y montrer les premières commandes dont un nouveau contributeur a besoin, la structure de premier niveau, les invariants clés et l’emplacement de la documentation détaillée. Un fichier d’instructions unique et long consomme du contexte qui devrait servir au code réel et aux exigences de la tâche, et peut rendre les contraintes critiques plus difficiles à remarquer. Un exemple lié à OpenAI Codex présente également une combinaison d’un court fichier d’environ 100 lignes, semblable à une carte, et d’une documentation séparée. openai.com↗

Que doivent contenir AGENTS.md et CLAUDE.md ?

De bonnes instructions ne dupliquent pas abondamment les faits déjà évidents dans le code. Elles privilégient plutôt les informations difficiles à apprendre à partir du seul code ou coûteuses à déduire de manière erronée. Les documents relatifs à Codex identifient les conventions de nommage, le langage métier, les contraintes et dépendances connues, ainsi que les procédures de build et de test comme des informations pertinentes à placer dans AGENTS.md. cdn.openai.com↗

Les instructions racines peuvent répondre de manière concise à des questions telles que :

• Quelles commandes exécutent le formatage, l’analyse statique, la vérification de types et les tests après une première modification ?
• Où se trouvent le code source, les tests, la documentation de conception et la documentation opérationnelle ?
• Quelles conventions de nommage de fichiers, d’imports, de gestion d’erreurs et de tests faut-il suivre lors de l’extension d’un module existant ?
• Les fichiers générés, les artefacts de build, les fichiers de verrouillage et les secrets peuvent-ils être modifiés ou inclus dans le dépôt ?
• Les zones à haut risque exigent-elles un plan, une revue supplémentaire ou des tests particuliers ?
• Quels documents contiennent les procédures détaillées de conception et d’exploitation ?

À l’inverse, des affirmations générales telles que « écrivez du code propre », « privilégiez la sécurité » ou « faites de votre mieux » sont difficiles à convertir en règles exécutables. Une instruction comme « utilisez le module de validation existant pour les entrées externes et ajoutez le test d’intégration correspondant pour chaque nouvelle route API » est plus utile, car elle peut être observée et vérifiée. Les orientations de Claude Code insistent elles aussi sur la formulation concrète de règles propres au projet et sur la revue et l’organisation régulières des instructions au fur et à mesure qu’elles s’étoffent. code.claude.com↗

Les instructions doivent être un enregistrement condensé des critères de décision, non un document dictant chaque détail d’implémentation. Les connaissances longues et susceptibles d’évoluer — comme l’utilisation d’une bibliothèque particulière, les contrats API ou l’ordre de réponse aux incidents — sont plus faciles à maintenir lorsqu’elles sont placées dans un document approprié sous docs/, tandis que les instructions racines indiquent leur emplacement et leurs conditions d’utilisation.

Quand des règles pour des sous-répertoires individuels sont-elles nécessaires ?

Les règles de sous-répertoires ne sont pas des fichiers à ajouter mécaniquement dans chaque dossier. Là où les règles racines partagées suffisent, des fichiers distincts peuvent au contraire accroître la surcharge de navigation et le risque de conflits. Il est préférable de les réserver aux limites qui s’écartent clairement des règles générales ou où les erreurs ont des conséquences importantes.

Par exemple, src/payments/ peut documenter la manière d’exprimer les calculs monétaires, d’utiliser les mocks des fournisseurs de paiement externes et la commande de test d’intégration spécifique à lancer. infra/ peut exiger un plan avant les modifications, des contrôles avant leur application et des limites sur les fichiers propres à un environnement pouvant être modifiés. generated/ peut indiquer que les modifications directes sont interdites et identifier la source ainsi que la commande de génération. Le but de ces règles n’est pas de donner un caractère spécial au dossier, mais de fournir précisément dans le contexte de travail les contraintes réelles de cette zone.

Pour Codex, un AGENTS.md imbriqué s’applique sous son répertoire, et les fichiers plus profonds peuvent fournir des règles plus spécifiques. Claude Code peut lui aussi accumuler plusieurs fichiers CLAUDE.md comme contexte ; il est donc plus sûr que les fichiers imbriqués ajoutent des conditions concrètes nécessaires uniquement dans cette zone plutôt que de formuler des déclarations ambiguës qui annulent les fichiers parents. openai.com↗code.claude.com↗

Par exemple, la racine peut indiquer : « Exécutez les tests du package modifié », tandis que le dossier des paiements indique : « Si le contrat de paiement change, exécutez les tests unitaires et d’intégration. » En revanche, écrire « Les tests doivent toujours être exécutés » à la racine et « N’exécutez pas les tests » dans un sous-dossier laisse les outils comme les personnes dans l’incertitude quant à la règle à suivre.

Comment répartir les fichiers .claude/rules/ de Claude Code ?

Dans Claude Code, vous pouvez placer les règles globales toujours nécessaires dans CLAUDE.md, et répartir les règles ayant des sujets distincts ou un comportement dépendant du chemin dans de petits fichiers sous .claude/rules/. Les fichiers de règles peuvent être organisés récursivement, et des conditions de chemin peuvent appliquer les règles seulement à certains fichiers ou certaines zones. code.claude.com↗

Le critère de répartition n’est pas le nombre de fichiers, mais la cohésion des règles qui évoluent ensemble. Par exemple, les commandes de test et les principes liés aux données de test peuvent aller dans testing.md ; les exceptions concernant les imports, le nommage et le formatage dans code-style.md ; et les contraintes impliquant les secrets, les requêtes externes et les autorisations dans security.md. Chaque fichier doit couvrir un seul sujet, et son titre doit indiquer clairement quand il doit être lu.

L’avantage de cette approche est qu’il n’est pas nécessaire de lire en permanence et intégralement des instructions inutiles. Par exemple, si les règles complètes de migration de base de données restent mêlées à un travail ne modifiant que de la documentation, elles peuvent masquer les instructions essentielles. Toutefois, une répartition trop fine rend difficile la localisation des règles. Une approche équilibrée consiste à présenter brièvement les principaux groupes de règles et leur finalité dans le CLAUDE.md racine, tout en conservant le contenu réel dans des fichiers thématiques.

Après avoir séparé les règles, évitez de copier la même obligation dans plusieurs fichiers. Les copies divergent facilement avec le temps. Conserver les principes partagés à un seul endroit et ne consigner que les exceptions et conditions supplémentaires dans les fichiers propres à un chemin réduit les conflits.

Comment spécifier le style de code ?

Un « style de code adapté à l’IA » ne signifie pas un choix universel entre tabulations et espaces, ou entre programmation fonctionnelle et orientée objet. Le critère le plus important est la possibilité de reproduire les conventions locales du dépôt. Les revues et la maintenance deviennent plus simples lorsqu’un nouveau module respecte les modèles existants de nommage de fichiers, de style d’export, d’ordre des imports, de parcours de gestion des erreurs et de structure des tests.

Tout choix du projet qui diffère des conventions courantes du langage mérite particulièrement d’être documenté. La documentation de Claude Code cite comme exemples de style de code propre au projet les modules ES ou la déstructuration d’imports nommés. Autrement dit, plutôt que de réécrire chaque règle par défaut d’un langage, il est plus efficace de décrire « ce que notre projet fait différemment du comportement par défaut ». code.claude.com↗

Le tableau suivant fournit des critères simples pour décider des orientations de style.

Les formateurs, linters et vérificateurs de types rendent le style mécaniquement testable au lieu de l’imposer par la prose. Il est donc préférable que les instructions indiquent les commandes réelles à exécuter et le traitement attendu des échecs plutôt que de dire « formatez correctement ». Les bonnes pratiques de Claude Code recommandent également des instructions de projet claires et des workflows de développement vérifiables. code.claude.com↗

Quelle structure de répertoires pouvez-vous utiliser comme point de départ ?

L’exemple suivant peut servir lorsque vous envisagez Codex et Claude Code ensemble. Il ne s’agit pas d’une norme obligatoire, mais d’un point de départ possible séparant les instructions partagées, la documentation détaillée et les exceptions propres à une zone.

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

Ici, README.md peut contenir les informations nécessaires aux personnes qui débutent avec le dépôt, ARCHITECTURE.md peut décrire les principales limites et la structure du système, et docs/ peut contenir les connaissances détaillées et étendues de conception, produit et exploitation. L’organisation réelle de src/ et tests/ doit avant tout suivre la structure existante du projet. .claude/rules/ est un emplacement pour les règles thématiques ou propres à un chemin de Claude Code. code.claude.com↗

Si le nombre de fichiers à la racine vous préoccupe, le problème essentiel n’est pas le nombre de noms de fichiers mais la séparation des responsabilités. Si un seul fichier assume simultanément la présentation du projet, la conception du système, la réponse opérationnelle, les conventions API détaillées et les règles de style, il devient difficile de savoir quelles informations sont essentielles pour la tâche en cours. À l’inverse, un guide racine court qui renvoie vers les documents détaillés nécessaires permet aux contributeurs d’explorer seulement aussi profondément que nécessaire.

Le même principe s’applique au placement de fichiers d’instructions dans des dossiers propres à une fonctionnalité. N’en ajoutez pas à moins que la fonctionnalité ait des règles dédiées ; ajoutez-en un seulement lorsqu’il existe une raison claire, telle que le traitement de données sensibles ou un processus de génération automatisé. La prolifération fréquente de fichiers de règles peut compliquer la structure elle-même au lieu de l’expliquer.

Comment réduire les règles dupliquées lors de l’utilisation des deux outils ?

Une option consiste à conserver les conventions de développement partagées faisant autorité dans AGENTS.md, à l’importer depuis le CLAUDE.md racine, puis à n’ajouter que le contenu requis par Claude Code. Par exemple :

@AGENTS.md

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

Cette configuration réduit le besoin de maintenir à répétition les commandes de test, les règles de nommage communes et les principes relatifs aux fichiers générés dans les deux fichiers. Elle conserve en même temps les règles propres à Claude Code et une configuration fondée sur .claude/rules/. Toutefois, comme indiqué plus haut, Claude Code ne lit pas automatiquement AGENTS.md comme instructions partagées ; vous devez donc réellement configurer un import ou une connexion équivalente. code.claude.com↗

L’emplacement du fichier partagé peut dépendre de l’utilisation relative des outils par l’équipe et des conventions existantes du dépôt. Si Codex est utilisé le plus souvent, AGENTS.md constitue une source canonique facile ; si les opérations sont centrées sur le système de règles de Claude Code, CLAUDE.md peut être la source canonique à la place. Quel que soit le choix, l’essentiel est de désigner une source originale faisant autorité pour chaque règle, et de ne laisser que des références ou des ajouts propres à l’outil dans l’autre fichier.

Il est préférable de séparer les préférences individuelles des conventions de l’équipe. Les alias de commandes dans un environnement personnel, les choix d’outils locaux et les habitudes de travail personnelles peuvent appartenir aux fichiers de remplacement personnels. En revanche, les procédures de test, les contraintes de sécurité et la structure de code que toute personne clonant le dépôt doit connaître doivent rester dans des instructions de projet versionnées. Codex et Claude Code prennent tous deux en charge des configurations d’instructions au niveau du projet et au niveau personnel. openai.com↗code.claude.com↗

Pourquoi les commandes de validation doivent-elles être centrales dans les instructions ?

Les propositions ou modifications d’un agent de programmation peuvent sembler plausibles, mais elles ne garantissent pas automatiquement l’exactitude, la compatibilité ou la sécurité. Les orientations relatives à Codex expliquent également qu’une revue humaine et une validation du résultat restent nécessaires. openai.com↗

C’est pourquoi de bonnes instructions de dépôt expliquent non seulement « comment coder », mais aussi « comment vérifier ». Lorsque c’est possible, listez les commandes de formatage, linting, vérification de types, tests unitaires, tests d’intégration et build sous des formes réellement exécutables. Pour les grands dépôts où exiger une validation complète pour chaque tâche n’est pas réaliste, vous pouvez distinguer la validation minimale selon l’emplacement de la modification des conditions exigeant une validation complète.

Par exemple, les mises à jour de documentation peuvent n’exiger qu’une vérification des liens ou une génération de documentation, tandis que les modifications d’un contrat d’API public peuvent exiger à la fois des tests unitaires et d’intégration. Les changements difficiles à annuler, tels que les schémas de base de données ou la configuration d’infrastructure, peuvent nécessiter une étape de revue supplémentaire. L’important n’est pas d’attendre de l’outil qu’il évalue le risque de manière magique, mais de consigner explicitement dans le dépôt les parcours de validation déjà connus de l’équipe.

Le code généré et les artefacts de build doivent également être clairement distingués du point de vue de la validation. Si des fichiers ne doivent pas être modifiés directement, documentez leur emplacement source et leur procédure de génération ; si la modification d’un artefact est autorisée, indiquez la commande qui le met à jour. Il est aussi plus sûr d’expliciter le principe selon lequel les secrets et paramètres personnels propres à un environnement n’ont pas leur place dans le dépôt, l’emplacement des fichiers d’exemple et les étapes de validation requises.

Quelles sont les idées reçues et les schémas d’échec courants ?

La première idée reçue est que « davantage d’instructions entraîne un meilleur respect ». En pratique, de longs documents peuvent enfouir les règles les plus importantes. Si les instructions sont devenues trop longues, supprimez les explications dupliquées, les règles déjà automatisées et les exceptions qui ne sont plus valides, puis déplacez les connaissances détaillées dans des documents distincts. code.claude.com↗openai.com↗

La deuxième est que « chaque dossier a besoin d’un fichier d’instructions ». Les instructions imbriquées ne sont utiles que là où existent des contraintes particulières. Un fichier imbriqué dépourvu de spécificité ajoute simplement un autre fichier à lire et peut rendre incertaine sa relation avec les règles parentes.

La troisième est que « respecter les règles de style suffit ». Même si le formatage est cohérent, une modification n’est pas nécessairement bonne si les tests n’ont pas été exécutés, si les règles métier ont été violées ou si des fichiers générés ont été modifiés directement. L’automatisation du style ainsi que les procédures de test et de revue ne se substituent pas les unes aux autres ; ce sont des garde-fous qui fonctionnent ensemble.

La quatrième est que « l’outil résoudra seul les contradictions dans la documentation ». Lorsque les instructions parentes et enfants, ou les instructions partagées et propres à l’outil, entrent en conflit, le résultat devient difficile à prévoir. Conservez une même règle à un seul endroit et rendez claires la portée et les conditions supplémentaires des règles enfants. Puisque la configuration de mémoire de Claude Code gère également les instructions hiérarchiques, il est important de concevoir les règles de façon à éviter les conflits. code.claude.com↗

Enfin, évitez de considérer un fichier d’instructions comme une garantie de qualité. Les instructions fournissent un contexte qui soutient le jugement des agents et des personnes ; elles ne sont pas des mécanismes garantissant l’exactitude, la sécurité ou la réussite des tests du code généré. La revue des modifications et l’exécution des validations nécessaires restent essentielles. openai.com↗

Que devons-nous appliquer d’abord dans notre dépôt ?

Vous n’avez pas besoin de repenser toute la structure des dossiers dès le départ. Il est plus réaliste de commencer par de petites améliorations fondées sur les sources de confusion récurrentes dans le dépôt actuel. Par exemple, si les nouveaux contributeurs ne trouvent pas la commande de test, ajoutez-la aux instructions racines. Si les mêmes erreurs surviennent de manière répétée dans le module de paiement, ajoutez des règles précises uniquement pour ce chemin. Si les documents de conception sont mélangés au code et difficiles à parcourir, commencez par distinguer les types de documents dans docs/.

Vous pouvez suivre une séquence d’évaluation comme celle-ci :

1. Identifiez les conventions de placement des fichiers, de nommage et de tests qui reviennent réellement dans la base de code actuelle.
2. Organisez les commandes et conditions d’échec des formateurs, linters, vérifications de types et tests.
3. Identifiez les contraintes métier, les zones à ne pas modifier et les procédures de génération difficiles à comprendre à partir du seul code.
4. Rédigez de façon concise uniquement le contenu le plus important dans le AGENTS.md ou CLAUDE.md racine.
5. N’ajoutez des instructions imbriquées ou des règles propres à un chemin que dans les zones sensibles que les règles générales ne peuvent pas expliquer.
6. Désignez une source originale pour les règles partagées, et ne laissez que les références et règles propres à l’outil dans les fichiers de l’autre outil.
7. Vérifiez régulièrement si les instructions ont été utiles dans le travail réel et si elles contiennent des affirmations inutiles ou contradictoires.

Dans ce processus, vous n’avez pas à traiter « facile à comprendre pour les outils » et « facile à maintenir pour les personnes » comme des objectifs opposés. Une documentation courte et exacte, des limites de modules prévisibles et une validation automatiquement exécutable aident les deux. À l’inverse, tenter de compenser par les seuls fichiers d’instructions une structure difficile à expliquer même pour les personnes risque de rendre la documentation encombrante.

Conclusion : quelles conventions choisir ?

La clé de conventions de répertoires et de styles de code adaptés à Codex et Claude Code ne consiste pas à adopter une structure tendance particulière. Une approche pratique consiste à maintenir avec cohérence les conventions de la base de code existante, à conserver un guide court à la racine, à séparer les connaissances détaillées dans des documents appropriés et à ajouter des règles à portée limitée seulement là où elles sont nécessaires.

Pour Codex, vous pouvez utiliser AGENTS.md ; pour Claude Code, CLAUDE.md et, si nécessaire, .claude/rules/. Si vous utilisez les deux outils, désignez une source unique pour les règles partagées et connectez explicitement le fichier partagé dans Claude Code afin de réduire les duplications. Surtout, associez les instructions aux formateurs, linters, vérifications de types, tests et à la revue humaine. Comme l’interprétation des instructions propres à un produit peut évoluer selon les versions, il est conseillé de conserver des règles courtes et claires tout en consultant la documentation officielle des outils que vous utilisez réellement. openai.com↗code.claude.com↗