DESIGN.md : documenter les choix 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 développement basé sur l’IA pourquoi le code est structuré ainsi. 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 linter qui doit réussir et les chemins à ne pas modifier. DESIGN.md consigne les décisions déjà prises et les problèmes qui apparaissent lorsque l’une d’elles est annulée.

Un agent de développement, c’est-à-dire un outil comme Claude Code ou Cursor qui lit et modifie votre dépôt de manière autonome, part du principe qu’il peut agir. Lorsqu’il trouve un pattern qu’il ne reconnaît pas, il l’améliore. Un cache écrit manuellement devient Redis (un magasin de données en mémoire), car c’est à cela que ressemble généralement un cache dans le code que le modèle a étudié. AGENTS.md n’empêche pas ce changement, car make test fonctionne dans les deux cas. La règle qui a été enfreinte n’avait jamais été écrite à un endroit que l’agent pouvait lire.

Si vous n’avez pas encore créé le premier fichier, commencez par là. AGENTS.md et le fichier HUMAN.md placé à côté expliquent le format et indiquent où chaque outil le recherche. La suite constitue le chapitre suivant.

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

Le moyen le plus rapide d’apprendre le format consiste à lire les fichiers que les 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, que vous pouvez consulter 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 que doit avoir un produit : couleurs, typographie, espacements et animations. Ne vous arrêtez pas au sujet traité. L’élément utile est la structure du texte, plutôt que le domaine concerné.

Le fichier de Nuxt compte environ 2,100 mots, et la plupart de son contenu prend 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 : environ 6,500 mots en août 2026. Il va aussi 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 lorsqu’on ne lui a pas indiqué de faire autrement :

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 l’empêcher 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 73 fichiers rétroconçus à partir de sites web publics. Chacun respecte le même format en neuf sections. Un agent peut ainsi recevoir l’un de ces fichiers et produire une interface qui s’en approche. Ces fichiers sont utiles, mais restent des suppositions. Personne dans les entreprises concernées ne les a relus.

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 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. Le dépôt le reconnaît lui-même : le standard est récent et son adoption officielle progresse. Les deux collections sont gérées par VoltAgent, un framework open source pour agents qui publie également son propre fichier. Considérez donc cette liste comme un suivi, et non comme un recensement neutre. Elle mérite néanmoins d’être suivie, en raison de l’identité de ces sept entreprises. Ce sont celles dont le code front-end est le plus souvent repris par d’autres développeurs. Leurs fichiers deviennent l’exemple concret de ce qu’est un 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 stabilisent rapidement, et elles se définissent d’abord au sommet.

Que mettre dans un DESIGN.md lorsque 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 le mécanisme n’a rien à voir avec les couleurs. Il sert à consigner les contraintes qu’un éditeur expérimenté risquerait sinon d’enfreindre sans s’en apercevoir.

Invariants. Une phrase par invariant, pour indiquer 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 c’est ce journal que lit l’export de conformité. » Un invariant accompagné de sa justification reste valable face à une tâche que vous n’aviez pas anticipée. Un invariant isolé ressemble à une préférence, et les préférences finissent par être supprimées lors de l’optimisation.

Alternatives rejetées. Présentez l’option évidente et expliquez pourquoi elle a été écartée. « Nous n’utilisons pas Redis pour la mise en cache. Le service s’exécute sur un seul VPS, donc une map en mémoire du processus est plus rapide et cela é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. Indiquez 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 utilisé par les scripts des clients. Le fichier de configuration lu par le 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 de chacun.

Vocabulaire. Si le code utilise tenant et que l’équipe parle de customer, consignez la correspondance. Lorsqu’un agent se trompe dans cette correspondance, il produit du code qui semble correct à la lecture, mais modélise le mauvais concept. C’est le type d’erreur le plus difficile à repérer lors de la revue.

Un fichier DESIGN.md que vous pouvez copier dès 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 dès 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 contenant quatre lignes exactes est utile. Un fichier contenant quarante lignes basées sur des suppositions ne l’est pas.

Certains outils chargent tous les fichiers Markdown à la racine du dépôt, tandis que d’autres chargent uniquement celui qui leur est indiqué. Ne partez donc pas du principe inverse. 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 DESIGN.md qui répète le README

La mauvaise version la plus courante se lit bien, mais n’apporte rien. Elle commence par expliquer ce que fait le projet, énumère les fonctionnalités, décrit l’installation, puis 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 concerne le contexte. Un fichier que l’agent lit au début de chaque tâche est pris en compte à chaque tâche, et une section d’installation dupliquée ne fait qu’occuper inutilement une fenêtre de contexte limitée. La gestion de cette fenêtre est une compétence à part entière, abordée dans gérer la fenêtre de contexte dans Claude Code. En bref : 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 encore 3000. L’agent n’a aucun moyen de déterminer laquelle est prioritaire. Il en choisit une et écrit du code en conséquence. Un fichier parfois incorrect est consulté avec la même confiance qu’un fichier toujours correct.

Le test est rapide. Si un paragraphe pourrait figurer sans problème dans le README, supprimez-le de DESIGN.md. Ce qui reste doit être ce que vous diriez à voix haute lors d’une code review, 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 pris en compte se manifeste dans la réponse avant même l’écriture du moindre code : l’agent doit vous indiquer que le job écrit via queue.enqueue(), car une écriture directe contournerait l’audit log. 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 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é.

Cela compte surtout lorsque l’agent s’exécute sur un serveur plutôt que sur votre laptop. Un agent qui travaille dans une session longue durée, comme dans la configuration présentée dans un workspace Claude Code sur un VPS avec tmux, ne garde 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ù consigner ces explications pour qu’elles persistent.

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 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 rapidement et plus souvent qu’une personne. Ajoutez des règles au fichier lorsqu’un agent vous met en échec, et non selon un calendrier. Si vous cherchez encore à déterminer comment intégrer les agents dans un workflow de développement classique, le guide 2026 pour apprendre à utiliser les agents IA constitue une prochaine étape raisonnable.

FAQ

DESIGN.md est-il un standard officiel ?

Pas au même titre que AGENTS.md. AGENTS.md dispose d’un site de référence, 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. En août 2026, DESIGN.md n’a ni organisme de gouvernance ni spécification publiée. Il bénéficie en revanche d’une adoption par les éditeurs : sept entreprises, dont Vercel, Nuxt, Atlassian et Resend, en publient un à une URL publique, et une collection communautaire en recense 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 vos sections.

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

Pour un petit dépôt, oui. Un fichier que l’agent lit systématiquement 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 à la racine.

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

Un ADR (architecture decision record) est un document daté qui consigne une décision, et un projet bien géré en accumule des dizaines dans un dossier. Cela constitue un historique, et l’historique est coûteux à charger, car un agent devrait tous les lire pour déterminer lesquels sont encore valides. DESIGN.md décrit l’état actuel et doit être lu intégralement pour 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 : en août 2026, le fichier de Nuxt fait environ 2,100 mots et celui de Vercel environ 6,500. Un service backend en nécessite généralement beaucoup moins. 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 un point que l’agent se tromperait sinon à interpréter.