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 placé à la racine de votre dépôt. Il explique à un agent de codage doté d’une IA pourquoi le code est structuré ainsi. AGENTS.md répond à une autre question : comment travailler dans ce dépôt. Il indique la commande de build, la commande de test, le lint qui doit réussir et les chemins à ne pas modifier. DESIGN.md consigne les décisions déjà établies et les problèmes provoqués par 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 l’améliore. 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 du code que le modèle a lu. 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 lire.

Si vous n’avez pas encore écrit le premier fichier, commencez par là. AGENTS.md et le fichier HUMAN.md placé à côté décrit le format et indique où chaque outil le recherche. Ce qui suit est le chapitre qui vient après.

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

Le moyen le plus rapide d’apprendre ce format consiste à lire les fichiers que des entreprises publient à leur sujet. Le dépôt official-design-md ne suit 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 août 2026, il en répertorie sept : Atlassian, Clerk, Mintlify, Nuxt, Resend, Vercel et VoltAgent. Chaque fichier se trouve à une URL publique stable. 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 qu’un produit doit avoir : couleurs, typographie, espacements et animations. Ne vous arrêtez pas à leur sujet. L’élément utile est la structure du texte, plus que le domaine traité.

Le fichier de Nuxt contient environ 2,100 mots. La plupart de ses éléments prennent la forme d’une règle accompagnée de sa justification :

Dark mode is the default theme.
Colors are semantic (`primary`, `neutral`, `error`…) rather than hardcoded hex values in components.
Don't hardcode `#00DC82` in UI code — use `text-primary` or `color="primary"`.

Le fichier de Vercel est plus long. Il contient environ 6,500 mots en août 2026 et va un peu plus loin. L’un de ses titres est Reject generated-design reflexes. Il est suivi d’une liste de ce vers quoi un générateur compétent se tourne lorsque personne ne lui a dit de s’en abstenir :

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 empêcher le modèle de les produire. Tout fichier DESIGN.md qui mérite d’être versionné constitue cette liste pour un domaine donné.

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

La communauté a été la première à le faire. awesome-design-md contient 73 fichiers rétroconçus à partir de sites web publics. Chacun suit le même format en neuf sections. Un agent peut donc recevoir l’un de ces fichiers et produire une interface dont l’apparence s’en rapproche. Ces fichiers sont utiles, mais ils restent fondés sur des suppositions. Personne dans ces entreprises ne les a relus.

Un fichier officiel 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é lui aussi. Une copie récupérée en mars continue d’enseigner l’ancienne échelle à votre agent. Rien dans votre dépôt ne vous indique alors que cette copie est obsolète.

Sept éditeurs, c’est peu, et le dépôt le précise lui-même : 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 néanmoins d’être suivie, compte tenu de l’identité de ces sept entreprises. Ce sont celles dont les développeurs copient le plus souvent le code front-end. Leurs fichiers deviennent l’exemple concret de ce qu’est un fichier DESIGN.md. Comparez avec le parcours d’AGENTS.md : agents.md recense désormais plus de 60,000 projets open source utilisant ce format, et sa gouvernance relève de l’Agentic AI Foundation, sous l’égide de la Linux Foundation. Les conventions relatives aux fichiers lisibles par les agents se fixent rapidement, et elles se fixent d’abord chez les principaux acteurs.

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 toutefois utile, car son intérêt ne tient pas aux 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. « Toutes les écritures passent par queue.enqueue(). Une écriture directe dans la base de données contourne le journal d’audit, alors que l’export de conformité lit ce journal. » Un invariant accompagné de sa raison résiste à 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 nom de l’optimisation.

Alternatives rejetées. L’option évidente et la raison de son rejet. « Nous n’utilisons pas Redis pour le cache. Le service s’exécute sur un VPS unique : une map en mémoire du processus est donc plus rapide et évite de maintenir un daemon supplémentaire. Réévaluez ce choix lorsqu’un deuxième serveur d’application sera disponible. » Sans ce paragraphe, un agent chargé 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 tout le fichier.

Limites. Les éléments où une petite modification peut avoir un impact important. Le schéma de la base de données. Le préfixe des routes publiques déjà utilisé par les scripts des clients. 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 copie 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 exemple via une instance SearXNG auto-hébergée configurée comme backend de recherche, cela constitue aussi une limite à documenter, car le fichier doit préciser quels textes récupérés sont autorisés à influencer le code et lesquels doivent uniquement vous être retournés sous forme de citation.

Vocabulaire. Si le code utilise tenant et que l’équipe dit 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 alternatives rejetées. Laissez les autres 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 fichier racine ne pourra pas convenir à tous. La même organisation par répertoire que celle utilisée pour les fichiers AGENTS.md imbriqués dans un monorepo s’applique ici : un fichier racine court pour les décisions communes à tout le dépôt, et un fichier plus court à côté de chaque package qui possède ses propres décisions.

Certains outils chargent tous les fichiers markdown présents à la racine du dépôt. D’autres ne chargent que celui qui leur est indiqué. Ne partez donc pas du principe que tous se comportent de la même manière. Ajoutez un renvoi 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 fichier DESIGN.md qui répète le README

La mauvaise version la plus courante est facile à lire, mais n’enseigne rien. Elle commence par présenter le rôle du projet, énumère les fonctionnalités, explique comment l’installer et se termine par la licence. Tout cela figure déjà dans le README, et rien n’explique pourquoi les choix ont été faits.

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 à chaque tâche. Une section d’installation dupliquée constitue donc une surcharge inutile dans une fenêtre de contexte limitée. La gestion de cette fenêtre est une compétence à part entière, présentée dans la gestion de la fenêtre de contexte dans Claude Code. En bref : tout ce qui est chargé automatiquement doit être le texte le plus utile du dépôt.

Le second coût est plus important. Deux copies d’une même information finissent par diverger. Le README indique que le service écoute sur 8080, tandis que DESIGN.md indique encore 3000. L’agent n’a aucun moyen de déterminer quelle information est prioritaire. 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 exact.

Le test est rapide. Si un paragraphe pourrait figurer sans problème dans le README, supprimez-le de DESIGN.md. Ce qui reste doit correspondre à ce que vous diriez à voix haute lors d’une code review, à ce qui commence par « nous avons déjà essayé ».

Comment savoir si le fichier est pris en compte ?

Il n’existe pas de linter pour ce fichier. Vous pouvez toutefois effectuer un contrôle en une minute.

Donnez à l’agent une tâche qui l’oblige directement à respecter 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 révèle dans la réponse avant même l’écriture du code : l’agent doit vous indiquer 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, l’une de ces deux affirmations est vraie : le fichier n’est pas lu du tout, ou l’invariant est formulé de manière assez 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 sans améliorer les réponses, le fichier contient probablement du texte que l’agent connaissait déjà. Lire les compteurs de tokens dans Claude Code indique où 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 committer est perdu à la session suivante, et DESIGN.md est l’endroit où cette explication doit être enregistrée pour être conservée.

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 faisons autrement ». Chacun de ces commentaires correspond à un invariant qui n’a jamais été documenté. C’est aussi un cas dans lequel un agent commettra la même erreur, plus rapidement et plus souvent qu’une personne. Ajoutez des règles au fichier lorsqu’un agent vous pose problème, et non selon un calendrier. Si vous cherchez encore comment intégrer les agents à un workflow de développement normal, le guide 2026 pour apprendre à utiliser les agents IA constitue une prochaine étape pertinente.

FAQ

DESIGN.md est-il une norme officielle ?

Pas de la même manière que AGENTS.md. AGENTS.md possède un site officiel, agents.md, est utilisé par plus de 60,000 projets open source et est placé sous la responsabilité de l’Agentic AI Foundation, qui fait partie de la Linux Foundation. En août 2026, DESIGN.md n’a ni organisme responsable ni spécification publiée. Il bénéficie toutefois d’une adoption directe par des éditeurs : sept entreprises, dont Vercel, Nuxt, Atlassian et Resend, en publient un à une URL publique, et une collection communautaire en contient 73 autres, reconstitués à partir de sites publics. Considérez-le comme une convention que vous pouvez adopter dès maintenant et étendre librement, car rien ne valide les noms de sections que vous utilisez.

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

Pour un petit dépôt, oui. Un fichier que l’agent lit à coup sûr vaut mieux que deux fichiers dont l’un est 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 à 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 situés à la racine.

En quoi DESIGN.md diffère-t-il d’un architecture decision record ?

Un ADR (architecture decision record) est un historique daté d’une décision unique, et un projet sain en accumule des dizaines dans un dossier. Il s’agit d’un historique, dont le chargement est coûteux, car un 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 à quelle date. DESIGN.md indique ce qui est vrai aujourd’hui et c’est vers lui 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 que cela pose problème. Les exemples publiés sont longs parce qu’ils décrivent tout un langage visuel : le fichier de Nuxt fait environ 2,100 mots et celui de Vercel environ 6,500 en août 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 bon critère. Chaque ligne doit décrire quelque chose que l’agent ferait autrement de manière incorrecte.