DESIGN.md : le fichier après AGENTS.md

Ce qu’est DESIGN.md et ce que AGENTS.md ne couvre pas

DESIGN.md est un fichier Markdown à la racine de votre dépôt. Il explique à un agent de codage IA pourquoi le code est structuré de cette façon. AGENTS.md répond à une autre question : comment travailler dans ce dépôt. Il indique notamment la commande de build, la commande de test, le lint qui doit réussir et les chemins auxquels il ne faut pas toucher. DESIGN.md consigne les décisions déjà établies et les conséquences de leur annulation.

Un agent de codage, c’est-à-dire un outil comme Claude Code ou Cursor qui lit et modifie votre dépôt de manière autonome, est par défaut sûr de lui. Il trouve un modèle qu’il ne reconnaît pas et le remplace par ce qu’il considère comme une amélioration. Un cache écrit manuellement devient Redis (un magasin de données en mémoire), parce que c’est à cela que ressemble un cache dans la plupart des codes que le modèle a lus. AGENTS.md ne l’en empêche pas, car make test fonctionne dans les deux cas. La règle enfreinte n’avait jamais été écrite à un endroit que l’agent pouvait consulter.

Si vous n’avez pas encore créé le premier fichier, commencez par là. AGENTS.md et le fichier HUMAN.md qui se trouve à côté explique le format et l’emplacement que chaque outil utilise pour le trouver. Ce qui suit est le chapitre qui vient ensuite.

Ce que contient réellement un DESIGN.md publié

Le moyen le plus rapide de comprendre le format consiste à lire les fichiers que des entreprises publient à leur sujet. Le dépôt official-design-md ne recense que ces fichiers. Sa règle d’inclusion tient en une ligne, et cette ligne constitue tout l’intérêt de la collection :

Every entry here is a DESIGN.md published by the company or project itself — not extracted, not reverse-engineered, not community-made.

En octobre 2026, il en recense onze : Ant Design, Atlassian, Clerk, Juspay, Microsoft FAST, Mintlify, Nuxt, Oxide Computer, Resend, Vercel et VoltAgent. Chaque fichier se trouve à une URL publique, généralement sur le domaine de l’éditeur, et pour les autres dans un dépôt GitHub public. Vous pouvez donc en lire un immédiatement dans un terminal.

curl -s https://nuxt.com/design.md | head -n 60
curl -s https://vercel.com/design.md | wc -w

Ces deux fichiers sont des documents de design system. Ils décrivent l’apparence d’un produit : couleurs, typographie, espacements et animations. Ne vous arrêtez pas au sujet traité, car l’élément utile réside dans la structure du texte plutôt que dans son thème.

Le fichier Nuxt fait environ 2 000 mots au 27 octobre 2026, et la plupart de son contenu prend la forme d’une règle accompagnée de sa justification. Il commence par indiquer que le mode sombre est le thème par défaut. Il présente le vert de la marque #00DC82 avec une note précisant que les couleurs de la marque sont « Pour les logos, les images destinées aux réseaux sociaux et l’impression. Ne les utilisez pas comme valeurs brutes dans le code de l’interface. » Vers la fin, une section intitulée Reject these contient :

Raw hex values or palette classes (`text-gray-500`) in components instead of semantic tokens.

Le fichier Vercel est plus long, avec environ 6 000 mots en octobre 2026, et va un peu plus loin. L’un de ses titres est Reject generated-design reflexes. Il contient une liste des éléments vers lesquels un générateur compétent se tourne lorsqu’aucune consigne ne lui interdit de les utiliser :

Hard reject decorative gradients, gradient text, glows, blobs, stripes, textures, grid backgrounds, glass effects, paper simulations, colored side rails, ornamental shadows, and fake depth.

Cette phrase définit le type de fichier. Il s’agit d’une liste écrite des valeurs par défaut qu’un modèle sûr de lui produit, publiée pour qu’il cesse de les produire. Tout DESIGN.md qui mérite d’être versionné constitue cette liste pour un domaine donné.

Pourquoi les entreprises publient-elles leur propre DESIGN.md ?

La communauté a pris les devants. awesome-design-md contient 84 fichiers extraits de sites web publics, selon le décompte indiqué dans son README au 27 octobre 2026. Chaque fichier suit le même format en neuf sections. Un agent peut donc s’appuyer sur l’un d’eux pour produire quelque chose qui s’en rapproche. Ces fichiers sont utiles, mais restent des suppositions. Personne dans les entreprises concernées ne les a vérifiés.

Un fichier publié par l’entreprise elle-même est différent, car il constitue la source et non une interprétation du résultat. Lorsque Vercel modifie son échelle typographique, vercel.com/design.md est modifié en conséquence. Une copie extraite en mars continue d’enseigner l’ancienne échelle à votre agent, et rien dans votre dépôt ne vous indique que cette copie est devenue obsolète.

Onze éditeurs représentent encore un petit nombre, et le dépôt le précise : le standard est récent et son adoption officielle progresse. Les deux collections sont maintenues par VoltAgent, un framework open source pour agents qui publie également son propre fichier. Il faut donc considérer cette liste comme un suivi, et non comme un recensement neutre. Elle mérite toutefois d’être surveillée, compte tenu des entreprises qui y figurent. Plusieurs font partie de celles dont le code front-end est le plus souvent repris par d’autres développeurs. Les entrées les plus récentes, Ant Design, Microsoft FAST, Juspay et Oxide Computer, sont des design systems sur lesquels d’autres équipes s’appuient. Leurs fichiers deviennent l’exemple concret de ce qu’est un DESIGN.md. Comparez le parcours d’AGENTS.md : agents.md est désormais utilisé par plus de 60 000 projets open source, et sa gouvernance relève de l’Agentic AI Foundation, sous l’égide de la Linux Foundation. DESIGN.md a commencé à suivre la même voie. Le 21 avril 2026, Google a publié en open source une spécification préliminaire du format, sous la forme de google-labs-code/design.md, avec un schéma de tokens et une CLI sous licence Apache-2.0. En octobre 2026, le format est en version alpha et reste en développement actif. Il est maintenu par Google Labs plutôt que par une fondation neutre, et décrit une identité visuelle. Il ne dit donc rien des invariants nécessaires à un fichier backend. Les conventions relatives aux fichiers lisibles par les agents se stabilisent rapidement, et elles se définissent au plus haut niveau.

Que mettre dans un DESIGN.md quand le projet n’a pas d’interface utilisateur

La plupart des logiciels exécutés sur un VPS n’ont pas de langage visuel à définir. Le fichier reste utile, car son objectif n’a rien à voir avec les couleurs. Il sert à consigner les contraintes qu’un éditeur sûr de lui pourrait sinon enfreindre sans s’en rendre compte.

Invariants. Une phrase par invariant, indiquant ce qui doit rester vrai après toute modification. « Chaque écriture passe par queue.enqueue(). Une écriture directe dans la base de données contourne le journal d’audit, qui est utilisé par l’export de conformité. » Un invariant accompagné de sa raison reste valable face à une tâche que vous n’aviez pas prévue. Un invariant présenté seul ressemble à une préférence, et les préférences finissent par être supprimées au cours de l’optimisation.

Alternatives rejetées. L’option évidente et la raison pour laquelle elle a été écartée. « Nous n’utilisons pas Redis pour le cache. Le service s’exécute sur un seul VPS, donc une map en mémoire du processus est plus rapide et cela fait un daemon de moins à maintenir. Réévaluez ce choix lorsqu’un deuxième serveur d’application sera présent. » Sans ce paragraphe, un agent auquel vous demandez d’accélérer le cache ajoute Redis, et il a raison de le faire : vous ne lui avez jamais indiqué cette contrainte. C’est la section qui justifie à elle seule l’ensemble du fichier.

Limites. Les endroits où une petite modification peut avoir un impact important. Le schéma de la base de données. Le préfixe des routes publiques que les clients utilisent déjà dans leurs scripts. Le fichier de configuration lu par un déploiement avant le démarrage de l’application. L’entrée cron qui suppose qu’une seule instance s’exécute. Nommez-les et indiquez le coût d’une modification pour chacun. Si l’agent peut également accéder au Web ouvert, par une instance SearXNG auto-hébergée configurée comme backend de recherche, cette possibilité constitue aussi une limite qu’il est utile de documenter. Le fichier doit préciser quels textes récupérés peuvent influencer le code et lesquels doivent uniquement vous être retransmis sous forme de citation.

Vocabulaire. Si le code utilise tenant et que l’équipe utilise customer, consignez la correspondance. Un agent qui se trompe produit du code qui se lit correctement mais représente le mauvais concept. C’est le type d’erreur le plus difficile à repérer lors de la revue.

Un DESIGN.md que vous pouvez créer aujourd’hui

# DESIGN.md

## What this service is
One paragraph. What it does, who calls it, where it runs.

## Invariants
- Every write goes through `queue.enqueue()`. Direct writes skip the audit log.
- Timestamps are stored as UTC integers. Only the display layer converts them.
- One process writes to SQLite. The database is in WAL mode, and a second writer
  gets `database is locked` under load.

## Rejected alternatives
- **Redis for caching.** Rejected: one VPS, one process, an in-process map is
  enough. Revisit at two application servers.
- **An ORM for the reporting queries.** Rejected: the reports are four hand-tuned
  SQL statements. The generated query joined the same table twice.

## Boundaries
- `schema.sql` is append-only. A column rename needs a migration and a deploy window.
- The `/v1/` routes are public. Customers script against them, so the response
  shape is frozen.

## Vocabulary
- `tenant` in code is what the docs and the billing system call a customer account.

## Keeping this file honest
Update it in the commit that changes the decision. A stale DESIGN.md is worse
than no DESIGN.md, because the agent believes it.

Remplissez aujourd’hui les deux sections que vous pouvez rédiger de mémoire : les invariants et les solutions écartées. Laissez les autres uniquement sous forme de titres. Un fichier de quatre lignes honnêtes est utile. Un fichier de quarante lignes approximatives ne l’est pas. Si le dépôt contient plusieurs packages, un seul fichier à la racine ne conviendra pas à tous. La même séparation par répertoire que celle utilisée pour les fichiers AGENTS.md imbriqués dans un monorepo s’applique ici : un fichier court à la racine pour les décisions communes à tout le dépôt, et un fichier plus petit à côté de chaque package qui possède ses propres décisions.

Certains outils chargent tous les fichiers Markdown situés à la racine du dépôt. D’autres ne chargent que celui qui leur est indiqué. Ne partez donc pas du principe qu’ils fonctionnent tous de la même manière. Ajoutez un lien vers AGENTS.md :

Read DESIGN.md before editing anything under `src/`. It lists the invariants and
the alternatives that were already rejected.

L’anti-pattern : un DESIGN.md qui répète le README

La version incorrecte la plus courante se lit bien, mais n’apporte aucune information. Elle commence par expliquer ce que fait le projet, énumère ses fonctionnalités, décrit son installation, puis se termine par la licence. Tout cela figure déjà dans le README, et rien n’explique pourquoi les choses sont conçues ainsi.

Cela vous coûte deux fois. Le premier coût est le contexte. Un fichier que l’agent lit au début de chaque tâche est pris en compte pour chaque tâche, et une section d’installation dupliquée ne fait qu’utiliser inutilement une fenêtre de contexte limitée. La gestion de cette fenêtre est une compétence à part entière, abordée dans la gestion de la fenêtre de contexte dans Claude Code. En résumé : tout ce qui est chargé automatiquement doit être le texte qui a le plus de valeur dans le dépôt.

Le second coût est plus grave. Deux copies d’une même information finissent par diverger. Le README indique que le service écoute sur 8080, tandis que DESIGN.md indique toujours 3000. L’agent ne peut pas déterminer laquelle prévaut ; il en choisit une et écrit le code en conséquence. Un fichier parfois incorrect est consulté avec la même confiance qu’un fichier toujours correct.

La vérification est rapide. Si un paragraphe pourrait figurer sans problème dans le README, supprimez-le de DESIGN.md. Le contenu restant doit être ce que vous diriez à voix haute lors d’une revue de code, la partie qui commence par « nous avons déjà essayé ».

Comment savoir si le fichier est pris en compte ?

Il n’existe pas de linter pour cela. Vous pouvez effectuer une vérification en une minute.

Donnez à l’agent une tâche qui le confronte directement à un invariant : « Ajoutez un job en arrière-plan qui marque les lignes obsolètes comme expirées. » Un fichier réellement pris en compte se manifeste dans la réponse avant même l’écriture du code : l’agent doit vous dire que le job écrit via queue.enqueue(), car une écriture directe contournerait le journal d’audit. S’il ouvre une connexion à la base de données et écrit directement, deux possibilités existent. Le fichier n’est pas lu du tout, ou l’invariant est formulé de manière suffisamment vague pour être contesté.

Surveillez également le nombre de tokens, car ce fichier est chargé à chaque tour. Si l’utilisation du contexte augmente après l’ajout de DESIGN.md et que les réponses ne s’améliorent pas, le fichier contient probablement des explications que l’agent connaissait déjà. Lire les compteurs de tokens dans Claude Code indique comment ce budget est utilisé.

C’est particulièrement important lorsque l’agent s’exécute sur un serveur plutôt que sur votre ordinateur portable. Un agent qui travaille dans une session persistante, comme dans un workspace Claude Code sur un VPS avec tmux, ne conserve aucun souvenir de la conversation de la veille. Le dépôt constitue sa mémoire. Tout ce que vous avez expliqué dans le chat sans le valider dans le dépôt disparaît à la session suivante. DESIGN.md permet de conserver ces explications.

Commencez par les décisions qui font débat

La première version prend vingt minutes. Ouvrez les dernières pull requests dans lesquelles un reviewer a écrit : « non, ici, nous procédons autrement ». Chacun de ces commentaires décrit un invariant qui n’a jamais été documenté. C’est aussi un cas dans lequel un agent commettra la même erreur, plus vite et plus souvent qu’une personne. Ajoutez une règle au fichier lorsqu’un échec vous l’a révélée, et non selon un calendrier. Si vous cherchez encore comment intégrer les agents dans un workflow de développement normal, le guide 2026 pour apprendre à utiliser les agents IA constitue une bonne prochaine étape.

FAQ

DESIGN.md est-il une norme officielle ?

Pas de la même manière que AGENTS.md. AGENTS.md a son propre site à l’adresse agents.md, est utilisé par plus de 60,000 projets open source et bénéficie de la gouvernance de l’Agentic AI Foundation, qui fait partie de la Linux Foundation. DESIGN.md dispose d’une spécification publiée, mais d’aucun organisme neutre chargé de sa gouvernance. Google a publié une ébauche de spécification en open source le April 21, 2026, dans le dépôt google-labs-code/design.md, sous licence Apache-2.0. En October 2026, le format en est à la version alpha et son développement se poursuit activement. Il décrit une identité visuelle : couleurs, typographie, mise en page et composants. DESIGN.md bénéficie également d’adoptions officielles : onze entreprises et projets, dont Vercel, Nuxt, Atlassian et Resend, en publient un. Une collection communautaire en a recensé 84 autres, extraits de sites publics, au October 27, 2026. Pour un fichier backend qui décrit les invariants et les alternatives rejetées, considérez-le comme une convention que vous pouvez adopter dès maintenant et étendre librement, car aucune spécification ne définit ces noms de section.

DESIGN.md doit-il simplement être une section de AGENTS.md ?

Pour un petit dépôt, oui. Un fichier que l’agent lit forcément vaut mieux que deux fichiers dont l’un risque d’être ignoré. Séparez-les lorsque AGENTS.md devient difficile à parcourir, ou lorsque vous constatez que les deux parties évoluent à des rythmes différents. AGENTS.md change lorsque le build change. DESIGN.md change lorsqu’une décision change, ce qui est plus rare et plus important. Après la séparation, ajoutez une ligne dans AGENTS.md pour indiquer à l’agent de lire DESIGN.md avant de modifier le code, car tous les outils ne chargent pas tous les fichiers markdown présents à la racine.

Quelle est la différence entre DESIGN.md et un architecture decision record ?

Un ADR (architecture decision record) est un compte rendu daté d’une décision. Un projet bien géré en accumule des dizaines dans un dossier. Cela constitue un historique, et l’historique coûte cher à charger : l’agent devrait tous les lire pour déterminer lesquels sont toujours valides. DESIGN.md décrit l’état actuel et est conçu pour être lu intégralement à chaque tâche. Conservez les deux si vous rédigez déjà des ADR. L’ADR indique ce qui a été décidé et quand. DESIGN.md indique ce qui est vrai aujourd’hui. C’est vers ce fichier que vous devez orienter l’agent.

Quelle doit être la longueur d’un DESIGN.md ?

Il doit être suffisamment court pour être chargé à chaque tour sans le regretter. Les exemples publiés sont longs, car ils spécifient tout un langage visuel : le fichier de Nuxt fait environ 2,000 mots et celui de Vercel environ 6,000 en October 2026. Un service backend nécessite généralement beaucoup moins de contenu. Commencez par une page et ne l’allongez que lorsqu’un agent commet une erreur qu’une seule phrase aurait permis d’éviter. La longueur n’est pas le critère. Chaque ligne doit décrire quelque chose que l’agent risquerait sinon de faire incorrectement.