Qu'est-ce que DESIGN.md pour les Agents de Codage ?

Les agents de codage sont confiants, rapides et totalement ignorants de l'architecture de votre base de code tant que vous ne leur dites pas le contraire. Donnez à Claude Code ou Codex un ticket vague et il écrira joyeusement du code qui compile, passe un test rapide et viole discrètement la frontière entre votre couche de domaine et votre couche HTTP. L'agent n'a pas lu vos documents de conception. Il a lu les fichiers qu'il pouvait voir, a fait de la reconnaissance de formes et a deviné. Un fichier DESIGN.md résout le problème de la devinette en consignant votre intention architecturale à l'endroit que l'agent consulte toujours : le dépôt lui-même.

EN BREF

DESIGN.md est un fichier de dépôt suivant une convention communautaire qui enregistre l'intention architecturale, les contraintes et les décisions de conception d'une base de code en Markdown simple afin que les agents de codage (Claude Code, Codex, Cursor) génèrent du code qui s'intègre au système au lieu de le combattre. Il répond à la question « pourquoi le code est-il structuré de cette manière », tandis que AGENTS.md répond à « comment construire et tester ».

Introduction

Voici le mode d'échec que chaque équipe adoptant des agents de codage rencontre en une semaine. Vous demandez à un agent d'ajouter un point d'API de remboursement à un service de paiement. Il renvoie un gestionnaire fonctionnel qui appelle la base de données directement depuis le contrôleur, ignore l'erreur de passerelle et invente un nouveau type de monnaie parce qu'il n'a pas remarqué que vous en aviez déjà un. Le diff est propre. Les tests passent. C'est également faux de trois manières que seul un relecteur connaissant l'architecture peut déceler. L'agent n'est pas mauvais en codage ; il est aveugle aux décisions qui résident dans votre tête, sur une page Notion, ou dans un fil Slack datant d'il y a huit mois.

DESIGN.md est la réponse sur laquelle un nombre croissant d'équipes se sont accordées. C'est un fichier Markdown unique, validé à la racine du dépôt, qui indique à tout agent les faits essentiels concernant votre système : les règles de superposition, les invariants qui ne doivent jamais être rompus, les modèles que vous avez choisis délibérément et ceux que vous avez rejetés. Ce n'est pas une spécification de fournisseur et il n'y a pas de comité qui en est propriétaire ; c'est une convention, de la même manière que ARCHITECTURE.md et CONTRIBUTING.md sont des conventions. Mais il s'associe naturellement aux fichiers d'instructions spécifiques aux outils que les agents lisent déjà, et pour le travail d'API et de backend, c'est l'un des documents les plus efficaces que vous puissiez rédiger.

Ce qu'est réellement DESIGN.md

DESIGN.md est un enregistrement en texte brut de la raison pour laquelle votre code est structuré de cette manière. Pas ce qu'il fait (ça, c'est le README), pas comment l'exécuter (ça, c'est AGENTS.md), mais le raisonnement qu'un ingénieur senior expliquerait à un nouvel employé le premier jour avant de le laisser toucher à quoi que ce soit d'important.

Pensez aux conversations qui ne figurent dans aucun fichier. « Nous n'appelons pas la passerelle de paiement depuis le thread de requête ; tout passe par la table de boîte d'envoi car la passerelle expire sous charge. » « L'argent est toujours un nombre entier d'unités mineures ; nous avons banni les flottants après l'incident d'arrondi. » « L'agrégat Account gère les mutations de solde ; rien d'autre n'écrit dans le grand livre. » Ce sont des décisions de conception. Elles sont invisibles pour un agent lisant le code source, car la source montre le résultat de la décision, pas la décision ou sa justification. Un agent peut voir que Account.debit() existe. Il ne peut pas voir que vous l'avez délibérément rendu le seul chemin d'écriture, il en ajoutera donc joyeusement un second.

La convention trouve ses racines dans des pratiques plus anciennes et bien établies. Le modèle ARCHITECTURE.md (popularisé par l'article largement cité d'Alex Kladov) soutient qu'un dépôt devrait contenir une carte de haut niveau de la base de code qui explique la structure et les invariants sans essayer de rester synchronisé ligne par ligne avec le code. Les enregistrements de décisions d'architecture (ADR) capturent les décisions individuelles et leur justification au fil du temps. DESIGN.md est ce que vous obtenez lorsque vous rédigez ce type de document pour un public qui inclut un agent de codage : concis, déclaratif, axé sur les décisions, et placé là où l'agent le chargera réellement.

Deux propriétés le rendent efficace. Il est dans le dépôt, donc l'agent le lit avec les mêmes outils qu'il utilise pour lire le code ; vous n'avez pas besoin d'un plugin ou d'un appel d'API. Et il concerne l'intention, il reste donc utile même si les fichiers sont déplacés. Renommez un package et vos captures d'écran README pourrissent ; la règle « la logique de domaine n'importe jamais le framework web » reste vraie.

DESIGN.md vs AGENTS.md vs CLAUDE.md vs README

Ces fichiers se chevauchent suffisamment pour prêter à confusion et diffèrent suffisamment pour que les fusionner en un seul soit une erreur. En bref : le README est destiné à l'intégration des humains, AGENTS.md est le contrat opérationnel pour les agents, CLAUDE.md est le fichier d'instructions spécifique à Claude, et DESIGN.md est la justification architecturale dont tous bénéficient.

AGENTS.md est désormais un format réel et largement adopté ; le projet agents.md le décrit comme « un format simple et ouvert pour guider les agents de codage », utilisé sur des dizaines de milliers de projets et géré par la Fondation AI Agentic de la Linux Foundation. Son rôle est opérationnel : étapes de build, commandes de test, style de code, conventions de commit, tout ce que vous diriez à un nouveau coéquipier pour qu'il ne soit pas bloqué. Selon la documentation de la mémoire de Claude Code d'Anthropic, CLAUDE.md joue le même rôle d'instruction spécifiquement pour Claude ; la documentation recommande même que si vous avez déjà un AGENTS.md, vous créiez un CLAUDE.md qui l'importe avec @AGENTS.md afin que les deux outils lisent une seule source de vérité.

Remarquez ce qui manque à ces descriptions : la justification architecturale approfondie. AGENTS.md et CLAUDE.md sont conçus pour être courts. La documentation de Claude Code recommande explicitement de maintenir CLAUDE.md en dessous de 200 lignes, car des fichiers plus longs consomment du contexte et réduisent la fiabilité avec laquelle le modèle les suit. Une véritable explication d'architecture, les limites, les invariants, les alternatives rejetées, les règles du modèle de données, ne tiendront pas là sans le gonfler. Vous le référencez donc à la place. DESIGN.md devient le document approfondi ; AGENTS.md / CLAUDE.md y renvoient avec une seule ligne.

La relation est complémentaire, et non compétitive. Une configuration propre pour un atelier Claude + Codex ressemble à ceci : README.md pour les humains ; un AGENTS.md avec les règles de build/test/style ; un CLAUDE.md qui n'est que @AGENTS.md plus deux lignes spécifiques à Claude ; et DESIGN.md contenant l'architecture, lié depuis AGENTS.md afin que chaque agent le charge à la demande. Aucune duplication, chaque fichier a un seul rôle. Si vous souhaitez une exploration plus approfondie de la structuration du contexte de Claude à travers ces fichiers, les flux de travail de Claude Code détaillent le modèle de mémoire en pratique.

Que mettre dans DESIGN.md (avec un modèle)

DESIGN.md doit répondre aux questions qu'un agent ne peut pas inférer du code : la forme du système, les règles qui n'apparaissent dans aucun fichier unique, et les décisions que vous avez prises délibérément. Gardez-le déclaratif. Chaque section doit se lire comme une règle qu'un relecteur ferait respecter, pas comme un essai.

Couvrez ces points :

• Forme du système : les couches ou modules et le sens des flux de dépendances. Une phrase par limite.
• Invariants : ce qui doit toujours être vrai. Énoncez-les comme des absolus. « Les soldes ne deviennent jamais négatifs en dehors d'un découvert autorisé. » « Chaque appel externe est idempotent par clé de requête. »
• Décisions clés et leur justification : les choix qui semblent arbitraires jusqu'à ce que vous sachiez pourquoi. Incluez le pourquoi ; la justification est ce qui empêche un agent de le « réparer ».
• Alternatives rejetées : ce que vous avez délibérément omis de faire, afin qu'un agent ne le propose pas comme une nouvelle idée. Cette seule section prévient une grande catégorie de mauvaises suggestions.
• Règles de données et de domaine : représentation de la monnaie, gestion du temps/fuseau horaire, identifiants, suppression logique, multi-location.
• Source de vérité du contrat d'API : où se trouve la spécification OpenAPI et la règle selon laquelle elle fait autorité sur les types écrits à la main.
• Où va le nouveau code : une courte carte « si vous ajoutez X, cela appartient à Y » pour que les agents cessent de disperser la logique.
• Hors périmètre / Ne pas toucher : fichiers générés, modules hérités en cours de migration, tout ce qu'un agent devrait ignorer.

Voici un modèle complet, écrit pour un service d'API de paiement réaliste. Copiez-le, supprimez ce qui ne s'applique pas, complétez le reste.

# DESIGN.md: Service d'API de paiements

Ce fichier enregistre l'intention architecturale et les décisions qui la sous-tendent.
Lisez-le avant de générer ou de modifier du code. Si un changement entre en conflit
avec une règle ici, arrêtez-vous et signalez-le au lieu de le contourner.

## Forme du système

Architecturé en couches, les dépendances ne pointent que vers l'intérieur :

  http (gestionnaires, DTO)  ->  app (cas d'utilisation)  ->  domain (entités,
  invariants)  <-  infra (base de données, clients de passerelle)

- `domain/` n'a aucune importation de `http/`, `app/`, ou de tout framework.
- `infra/` implémente les interfaces déclarées dans `domain/` ou `app/`.
- `http/` ne touche jamais directement la base de données ou la passerelle de paiement.
  Il appelle un cas d'utilisation dans `app/`.

## Invariants (doivent toujours être respectés)

- Une écriture de grand livre est immuable une fois enregistrée. Les corrections sont de nouvelles
  écritures compensatoires, jamais des mises à jour ou des suppressions.
- Le solde du compte est dérivé des écritures de grand livre, et non stocké comme un champ
  mutable que le code peut définir directement.
- L'argent est un nombre entier d'unités mineures (cents) plus un code de devise
  ISO-4217. Jamais un flottant. Ne jamais mélanger les devises dans une même opération.
- Chaque appel à une passerelle de paiement externe est idempotent, identifié par
  `idempotency_key`. Les réessais ne doivent pas entraîner de double facturation.
- Les soldes ne deviennent jamais négatifs, sauf si une `OverdraftPolicy` explicite
  l'autorise pour ce compte.

## Décisions clés et leur justification

- **Modèle Outbox pour les appels de passerelle.** Les gestionnaires écrivent une ligne d'intention
  dans la même transaction de base de données que le changement métier, puis un processus
  travailleur appelle la passerelle. Justification : la passerelle expire sous charge ;
  le faire en ligne rendait la latence de requête et la gestion des erreurs non maîtrisées.
  N'appelez pas la passerelle depuis un gestionnaire de requêtes.
- **Chemin d'écriture unique par agrégat.** Seul `Account.post_entry()` écrit dans le grand livre.
  Justification : un second chemin d'écriture a causé la dérive de solde de Mars 2025.
  Ajoutez de nouveaux comportements comme des méthodes sur l'agrégat, et non de nouvelles requêtes.
- **Event sourcing uniquement pour le grand livre.** Le reste du système est CRUD.
  Justification : nous avons besoin d'une piste d'audit parfaite pour l'argent et
  rien d'autre, et l'event sourcing complet était trop coûteux ailleurs.

## Alternatives rejetées (ne pas réintroduire)

- Chargement paresseux d'ORM à travers les agrégats ; a causé des N+1 et des limites de transaction
  floues. Les dépôts renvoient des agrégats entièrement chargés.
- Stocker le solde comme une colonne mise à jour sur place ; voir l'incident de dérive de solde.
  Le solde est toujours dérivé.
- Une bibliothèque générique `Money` tirée du registre ; nous avons notre
  propre `domain/money.py` ; utilisez-la.
- Webhooks synchrones vers les marchands depuis le thread de requête ; ils
  bloquent et échouent silencieusement. Utilisez la file d'attente de notifications.

## Règles de données et de domaine

- Tous les horodatages sont en UTC, stockés comme `timestamptz`, formatés RFC 3339
  à la limite. Aucune date/heure naïve ne traverse une limite de fonction.
- Les identifiants sont des ULID générés dans la couche application, jamais d'auto-incrément DB.
- La suppression logique n'est pas utilisée. Les enregistrements sont soit actifs, soit déplacés vers
  une table d'archives par un cas d'utilisation explicite.
- Multi-locataire : chaque requête est scopeée par `tenant_id`. Une méthode de dépôt
  sans portée de locataire est un bug.

## Source de vérité du contrat d'API

- La spécification OpenAPI 3.1 dans `api/openapi.yaml` fait autorité.
  Les types de requête/réponse en sont générés ; ne modifiez pas manuellement les
  types générés dans `http/generated/`.
- Nouveaux points de terminaison ou modifiés : mettez à jour `api/openapi.yaml` en premier, puis
  régénérez, puis implémentez. La spécification est conçue et revue dans
  Apidog avant les changements de code.
- Les réponses d'erreur suivent le RFC 9457 (problem+json). Utilisez l'aide partagée
  `problem()` ; n'inventez pas de formes d'erreur ad hoc.

## Où va le nouveau code

- Nouveau point de terminaison : route dans `http/routes/`, DTO dans `http/dto/`,
  cas d'utilisation dans `app/usecases/`, logique de domaine dans `domain/`.
- Nouvelle intégration externe : client dans `infra/clients/`, interface
  dans `app/ports/`.
- Préoccupation transversale (authentification, journalisation, idempotence) : middleware dans
  `http/middleware/`, jamais en ligne dans les gestionnaires.

## Hors périmètre / Ne pas toucher

- `http/generated/` : régénéré à partir d'OpenAPI, les modifications sont perdues.
- `legacy/billing_v1/` : gelé, en cours de migration. Ne pas étendre.
- `migrations/` : ne jamais modifier une migration appliquée ; ajoutez-en une nouvelle.

## En cas de doute

Si un changement demandé exige de rompre une règle ci-dessus, la bonne approche
est de le signaler et de proposer la plus petite alternative de conception cohérente,
plutôt que de contourner silencieusement la règle.

Cette dernière section est plus importante qu'il n'y paraît. Dire à un agent quoi faire lorsque la requête est en conflit avec la conception transforme le fichier d'une documentation passive en un garde-fou actif. Sans cela, un agent qui rencontre une contrainte a tendance à la contourner et à livrer la solution de contournement.

Comment les agents de codage consomment réellement DESIGN.md

Les agents n'ont pas d'analyseur DESIGN.md spécial. Ils le consomment de la même manière qu'ils consomment n'importe quel fichier : en le lisant avec leurs outils de fichier et en traitant le contenu comme du contexte. Ainsi, les mécanismes de chargement sont importants, et ils diffèrent légèrement selon l'outil.

Le modèle fiable consiste à référencer DESIGN.md depuis le fichier d'instructions que chaque agent charge déjà au démarrage. Pour Claude Code, c'est CLAUDE.md ; la documentation sur la mémoire décrit une syntaxe d'importation @path où @DESIGN.md étend le fichier dans le contexte au début de la session. Pour l'écosystème AGENTS.md, vous ajoutez une ligne dans AGENTS.md qui y renvoie (« Règles d'architecture et de conception : voir DESIGN.md ; lisez-le avant les changements structurels »). Les agents qui parcourent l'arborescence des répertoires détecteront le AGENTS.md le plus proche, verront le pointeur et chargeront DESIGN.md lorsque le travail touche à l'architecture. Dans les deux cas, vous ne dupliquez pas le contenu ; vous maintenez le fichier opérationnel court et laissez le fichier détaillé être approfondi.

Trois notes pratiques sur le comportement de ces outils :

Premièrement, l'agent traite le fichier comme du contexte, et non comme des règles imposées. La documentation de Claude Code est catégorique : le contenu de CLAUDE.md est une orientation que le modèle essaie de suivre, et non une contrainte stricte. Il en va de même pour tout ce que vous y référencez. C'est pourquoi le modèle formule tout en absolus testables et ajoute une instruction explicite « en cas de doute » ; une prose vague est ignorée sous pression, les règles précises sont suivies plus souvent.

Deuxièmement, la longueur et la structure influencent l'adhérence. Les titres et les puces l'emportent sur les paragraphes car le modèle analyse la structure de la même manière qu'un lecteur. Un mur de philosophie architecturale de 3 pages sera survolé ; dix invariants clairs sous un titre explicite seront utilisés. Écrivez pour la récupération d'informations, pas pour la prose.

Troisièmement, le fichier modifie l'économie de la révision, pas seulement la génération. Même lorsqu'un agent l'ignore en partie, un relecteur peut signaler la règle violée et l'agent la corrige en un seul tour (« cela rompt la règle du chemin d'écriture unique dans DESIGN.md »). Cette boucle de rétroaction, qui ancre la correction dans la décision écrite, est l'endroit où se trouve une grande partie de la valeur réelle. Les équipes construisant leurs propres outils d'agents s'appuient exactement sur cela ; voir construire votre propre Claude Code pour savoir comment cette boucle est intégrée dans les flux autonomes.

Anti-modèles et comment éviter qu'il ne pourrisse

Le moyen le plus rapide de rendre DESIGN.md inutile est de l'écrire comme une page wiki. Un fichier de conception pourri est pire que pas de fichier du tout, car les agents et les humains lui font confiance et sont induits en erreur. Évitez cela.

• Redire le code. « La classe UserService gère les utilisateurs » ne dit rien à un agent qu'il ne puisse lire depuis user_service.py. Si une phrase est vraie en lisant le fichier, supprimez-la. Ne gardez que ce que le code ne peut pas vous dire : justification, invariants, chemins rejetés.
• Dérive tutorielle. Les tutoriels étape par étape sur « comment ajouter une fonctionnalité » appartiennent à CONTRIBUTING.md ou à une compétence, pas ici. Dès que DESIGN.md contient des commandes shell et des extraits à copier-coller, c'est le mauvais document et il deviendra obsolète à la vitesse de l'outillage.
• Aspiration comme fait. Écrire « le système utilise CQRS » alors que la moitié ne le fait pas, entraîne les agents à produire du code correspondant à une fiction. Documentez ce qui est vrai maintenant et où vous vous dirigez délibérément, et signalez la différence. « Cible : toutes les écritures passent par des cas d'utilisation. Actuel : legacy/ contourne cela ; ne l'étendez pas. »
• Pas de propriétaire, pas de déclencheur de révision. Un fichier de conception dont personne n'est responsable dérive en un trimestre. Liez-le à un déclencheur : révisez DESIGN.md dans toute PR qui ajoute un module, modifie une limite de couche ou introduit une nouvelle dépendance externe. Mettez cette règle dans le modèle de PR. Certaines équipes ajoutent un élément de liste de contrôle : « ce changement modifie-t-il une décision dans DESIGN.md ? Si oui, mettez-le à jour dans la même PR. »
• Théâtre de synchronisation. N'essayez pas de le maintenir synchronisé ligne par ligne avec le code ; c'est une bataille perdue et c'est la raison pour laquelle les documents d'architecture sont abandonnés. Gardez-le au niveau des décisions qui changent quelques fois par an, pas des signatures de fonctions qui changent chaque semaine. La directive ARCHITECTURE.md de matklad est le bon instinct ici : ne notez que ce qui est peu susceptible de changer souvent.
• Contredire les autres fichiers d'instructions. Si AGENTS.md dit une chose sur la gestion des erreurs et DESIGN.md en dit une autre, les agents en choisissent une arbitrairement. Gardez les règles opérationnelles dans AGENTS.md / CLAUDE.md et les règles architecturales dans DESIGN.md, et ne les laissez pas se chevaucher. Lorsqu'ils doivent se référencer mutuellement, l'un pointe vers l'autre ; ils n'affirment pas tous les deux le même fait.

Un DESIGN.md sain est court, dense, déclaratif, possède un propriétaire et est révisé sur déclencheur. Si le vôtre est long, narratif et n'a pas été touché depuis un an, les agents lisent de la fiction.

DESIGN.md pour les bases de code d'API et de backend

C'est là que le fichier prouve sa valeur. Les services API et backend ont exactement le genre de contraintes invisibles et coûteuses pour lesquelles les agents sont les moins performants : les limites de contrat, la sémantique transactionnelle, l'idempotence, l'intégrité des données, l'architecture en couches. Rien de tout cela n'est évident à partir d'un seul fichier, et se tromper envoie des bugs qui atteignent la production et le portefeuille.

Mettez ces éléments spécifiques aux API dans DESIGN.md et la qualité de la sortie de l'agent sur les tickets backend fera un bond :

• Le contrat est la source de vérité, et indiquez où il se trouve. Déclarez clairement que la spécification OpenAPI fait autorité et que les types générés ne doivent pas être édités manuellement. Les agents adorent « aider » à modifier un type généré pour faire passer un build ; une ligne dans DESIGN.md l'arrête. Pointez vers le chemin du fichier de spécification. Si vous concevez le contrat en premier dans Apidog et exportez le document OpenAPI dans le dépôt, votre DESIGN.md peut nommer ce fichier comme l'élément auquel chaque point de terminaison doit se conformer, et l'agent a une cible non ambiguë. L'argument de la conception du contrat avant le code est abordé dans concevoir des API pour les agents d'IA ; un contrat axé sur la conception est précisément ce qui rend les gestionnaires générés par l'agent sûrs à accepter.
• Limites de transaction et de cohérence. Où commence et se termine une transaction ? Qu'est-il autorisé à l'intérieur ? « Les appels externes ne se produisent jamais au sein d'une transaction de base de données ; utilisez la boîte d'envoi. » Les agents se contentent par défaut de l'appel en ligne naïf à chaque fois, à moins que le fichier ne l'interdise.
• Idempotence et tentatives. Énoncez la stratégie d'idempotence comme un invariant. Les points de terminaison de paiement, de commande et de provisionnement sont les endroits où une clé d'idempotence manquante entraîne une double facturation. L'agent ne l'inférera pas en lisant un gestionnaire.
• Modèle d'erreur. Une phrase : « toutes les erreurs sont de type problem+json via l'aide problem() ; n'inventez jamais de formes d'erreur. » Sans cela, vous obtenez une enveloppe d'erreur différente par point de terminaison, ce qui casse chaque client.
• Portée d'authentification et de multi-location. « Chaque requête est scopeée par locataire ; une méthode de dépôt non scopeée est un bug. » C'est un invariant de sécurité, et il est invisible dans toute requête individuelle, c'est donc exactement le genre de règle qui doit être documentée.
• Règles de versioning et de changements cassants. Ce qui est considéré comme cassant, comment vous versionnez, ce qui est autorisé dans une version mineure. Les agents renommeront volontiers un champ de réponse ; le fichier leur indique qu'il s'agit d'un changement cassant avec un processus.

Pour le travail backend, les avantages sont concrets : moins de violations de couches, pas d'appels de passerelle en ligne inattendus, des formes d'erreur et de pagination cohérentes, et des gestionnaires conformes au contrat car l'agent a été dirigé vers la spécification OpenAPI au lieu de deviner le schéma. L'agent cesse d'inventer et commence à se conformer. Si vous souhaitez que l'agent exerce également l'API qu'il vient d'écrire, la combinaison contrat-plus-design est ce qui permet aux outils et aux agents de tester une interface connue ; Téléchargez Apidog vous offre l'espace de travail de conception préalable, l'exportation OpenAPI vers laquelle votre DESIGN.md pointe, ainsi qu'un serveur MCP et un débogueur d'agent IA pour vérifier que les points de terminaison générés correspondent réellement au contrat.

Conclusion

• DESIGN.md enregistre pourquoi votre code est structuré de cette manière : les invariants, les décisions et les alternatives rejetées qu'un agent ne peut pas déduire du code source.
• Il complète plutôt qu'il ne remplace AGENTS.md et CLAUDE.md : ces derniers restent courts et opérationnels ; DESIGN.md contient l'architecture approfondie et est référencé à partir d'eux.
• Rédigez-le de manière déclarative, comme des absolus testables, plus une règle « en cas de doute, signalez plutôt que de contourner », afin qu'il agisse comme un garde-fou, et non comme de la prose passive.
• Il est le plus rentable sur les bases de code d'API et de backend, où les limites de contrat, les transactions, l'idempotence et la portée de multi-location sont invisibles et coûteuses à mal gérer.
• Empêchez-le de pourrir avec un propriétaire et un déclencheur de révision lié à votre modèle de PR ; ne le synchronisez jamais ligne par ligne avec le code.
• Le plus grand avantage pour le backend est de désigner la spécification OpenAPI comme faisant autorité afin que les agents se conforment au contrat au lieu d'inventer des schémas.
• Concevez ce contrat en premier. Téléchargez Apidog pour concevoir des API en mode conception préalable, exportez la spécification OpenAPI vers laquelle votre DESIGN.md pointe, et testez que les points de terminaison générés par l'agent y correspondent réellement.

FAQ

DESIGN.md est-il une norme officielle comme AGENTS.md ?

Non. AGENTS.md est un format défini et largement adopté, désormais géré par l'Agentic AI Foundation de la Linux Foundation. DESIGN.md est une convention communautaire sans propriétaire unique ni spécification, dans la même famille que ARCHITECTURE.md et les ADR. Traitez-le comme un modèle utile que vous adaptez, et non comme une norme à laquelle vous vous conformez.

Ai-je besoin de DESIGN.md si j'ai déjà AGENTS.md ou CLAUDE.md ?

Si votre architecture a des contraintes non évidentes, oui. AGENTS.md et CLAUDE.md sont destinés à rester courts et opérationnels ; la documentation de Claude Code recommande de maintenir CLAUDE.md en dessous d'environ 200 lignes. Une justification architecturale approfondie n'y tiendrait pas sans le gonfler et nuire à l'adhérence, vous la placez donc dans DESIGN.md et la référencez. Pour le fichier opérationnel lui-même, consultez comment écrire des fichiers AGENTS.md.

En quoi DESIGN.md est-il différent de ARCHITECTURE.md ?

Principalement par l'intention et le public. ARCHITECTURE.md est la convention plus ancienne destinée aux contributeurs humains pour cartographier la base de code. DESIGN.md est la même idée écrite pour un public qui inclut un agent de codage : plus déclaratif, axé sur les décisions et les invariants, et explicitement référencé depuis les fichiers d'instructions de l'agent afin qu'il soit chargé dans le contexte. De nombreuses équipes utilisent un seul fichier et un seul nom ; les principes sont les mêmes.

Quelle doit être la longueur de DESIGN.md ?

Assez long pour couvrir les décisions que les agents continuent de mal comprendre, assez court pour que chaque ligne justifie sa présence. Une densité de décisions l'emporte sur l'exhaustivité. S'il ressemble à un tutoriel ou reformule le code, supprimez-le. Deux à quatre pages ciblées d'invariants et de justifications sont préférables à une narration de quinze pages qu'aucun agent ne lira attentivement.

Comment faire en sorte que l'agent le lise réellement ?

Référencez-le depuis le fichier que l'agent charge déjà au démarrage. Pour Claude Code, importez-le depuis CLAUDE.md avec @DESIGN.md. Pour l'écosystème AGENTS.md, ajoutez une ligne de pointeur dans AGENTS.md indiquant aux agents de lire DESIGN.md avant les changements structurels. Ne collez pas l'intégralité du contenu dans le fichier court ; référencez-le pour que le fichier opérationnel reste concis.

L'agent suivra-t-il toujours DESIGN.md ?

Non, et vous devriez concevoir en tenant compte de cela. Les fichiers d'instructions d'agent sont un contexte que le modèle essaie de suivre, pas une configuration imposée. Rédigez des règles comme des absolus clairs, ajoutez une instruction explicite « signalez les conflits, ne les contournez pas », et appuyez-vous sur la boucle de révision ; signaler une règle violée dans DESIGN.md permet une correction rapide et juste même si la première passe l'a manquée.

DESIGN.md aide-t-il spécifiquement avec les problèmes de contrat d'API ?

Beaucoup. Son utilisation la plus précieuse en backend est de déclarer que la spécification OpenAPI fait autorité et de nommer le fichier, afin que les agents se conforment au contrat au lieu d'inventer des schémas ou de modifier manuellement les types générés. Concevoir ce contrat en premier lieu dans un outil comme Apidog donne à l'agent une cible non ambiguë vers laquelle votre DESIGN.md peut pointer directement.

Où DESIGN.md doit-il résider dans le dépôt ?

À la racine du dépôt, à côté de README.md et AGENTS.md, afin que les agents et les humains le trouvent sans recherche. Dans un monorepo, un DESIGN.md à la racine pour les règles à l'échelle du système, plus un par package pour l'architecture locale, fonctionne bien, reflétant la façon dont les agents lisent le AGENTS.md le plus proche dans l'arborescence des répertoires.