L'ordre de priorité, en un coup d'œil
Lisez du périmètre le plus restreint vers le plus large. Une règle dans un fichier spécifique l'emporte sur une règle générale, et une instruction saisie par l'utilisateur durant la session l'emporte sur tous les fichiers.
- Ce que l'utilisateur dit en session : gagne toujours, même si cela contredit un fichier.
- `SKILL.md` : actif uniquement lorsque cette compétence est invoquée, et limité à son périmètre.
- `CLAUDE.md` / fichier spécifique à l'outil : le comportement de cet outil dans ce repo.
- `AGENTS.md` : les règles du projet pour n'importe quel agent.
- `DESIGN.md` : le contrat visuel, référencé par les éléments ci-dessus plutôt que d'être en concurrence avec eux.
DESIGN.md se situe volontairement légèrement en dehors de la pile. Les trois autres indiquent à un agent comment *travailler* ; celui-ci lui indique à quoi le résultat doit *ressembler*. Ils entrent rarement en conflit, c'est pourquoi un projet peut l'adopter sans avoir à renégocier le reste.
AGENTS.md : le fichier projet multi-outils
C'est celui qu'il faut écrire en premier. Il est lu par un nombre croissant d'agents, n'appartient à aucun fournisseur et contient les vérités universelles, quel que soit l'exécutant : comment builder, comment tester, ce qu'il ne faut pas toucher, et quelles conventions le codebase suit réellement.
Les équivalents spécifiques aux fournisseurs se multiplient : Copilot lit .github/copilot-instructions.md (et aussi AGENTS.md dans VS Code), Gemini CLI lit une hiérarchie GEMINI.md, Cursor utilise son répertoire de règles. Le modèle suivant — un AGENTS.md canonique plus un fichier léger par outil qui l'importe ou le reformule — est la méthode pour tous les supporter sans maintenir cinq guides de règles divergents.
La discipline essentielle ici est le coût. Ce fichier est chargé à chaque requête, donc chaque ligne est payée indéfiniment. Une règle ne mérite sa place en ligne que si elle modifie le comportement par défaut, s'applique largement et qu'une erreur serait coûteuse. Les catalogues de commandes, les schémas d'API et les procédures d'installation doivent figurer dans un document vers lequel on pointe via une seule ligne.
# AGENTS.md
## Build and verify
- `pnpm dev` on :4000. Never run `pnpm build` — it corrupts the shared dev cache.
- Verify with `tsc --noEmit`, not a build.
## Conventions
- Server work goes in `src/server/` as server actions, not API routes.
- Never hardcode theme colors; use the semantic tokens in DESIGN.md.
## Before you act
- Changing the payment flow: read `docs/PRICING.md` first.CLAUDE.md : un import plus un complément
L'erreur récurrente est de maintenir CLAUDE.md et AGENTS.md comme deux copies complètes. Ils divergent silencieusement, et cette divergence apparaît lorsqu'un agent suit avec assurance une règle que vous avez supprimée il y a deux mois.
# CLAUDE.md
@AGENTS.md
## Claude Code only
- Use the local browser tool for hydration checks; the remote one stalls RSC.
- Slash commands live in `.claude/commands/`.Le piège de l'import
L'expansion @file n'est pas universelle. Claude développe les chemins relatifs au projet ; plusieurs autres outils transmettent la ligne telle quelle en texte brut, et les chemins absolus ne produisent souvent aucun effet. Vérifiez ce que votre agent charge réellement avant de vous fier à un import.
SKILL.md : une capacité, pas un guide de règles
La distinction qui rend les skills efficaces : AGENTS.md est *toujours* dans le contexte, tandis qu'un skill est chargé *lorsqu'il est pertinent*. Cette différence est une décision budgétaire. Une checklist de revue de code de 400 lignes dans AGENTS.md est payée à chaque requête, même pour corriger une faute de frappe. La même checklist en tant que skill ne coûte rien tant que la revue ne commence pas.
Le critère n'est donc pas l'importance, mais la fréquence. Les règles qui s'appliquent à presque chaque requête vont dans le fichier chargé en permanence. Les procédures qui s'appliquent à un type de tâche spécifique (déploiement, revue, génération d'une migration) vont dans une skill.
| AGENTS.md | SKILL.md | DESIGN.md | |
|---|---|---|---|
| Chargement | Chaque requête | À l'invocation | Lors de l'écriture de l'UI |
| Portée | Tout le projet | Un type de tâche | Tout l'aspect visuel |
| Cas d'usage idéal | Commandes de build, contraintes | Étapes de déploiement, checklist de revue | Tokens, échelle typographique, motifs |
| Cas d'usage inapproprié | Une procédure de 300 lignes | Une règle nécessaire à chaque requête | Tout ce qui n'est pas visuel |
| Coût d'une ligne erronée | Payé indéfiniment | Payé lors de l'invocation | Pixels erronés |
DESIGN.md : le fichier que personne n'écrit
C'est là que se trouve la lacune. AGENTS.md n'est pas l'endroit naturel pour une palette de couleurs. CLAUDE.md concerne le comportement des outils. Une skill est invoquée, elle n'est pas ambiante. Le contrat visuel se retrouve donc nulle part, et un agent sans contrat visuel revient aux valeurs par défaut, ce qui explique pourquoi les sites créés par IA convergent vers un look unique.
Un fichier DESIGN.md comble ce vide. Au minimum, il contient les design tokens sémantiques pour les modes clair et sombre, le couple et l'échelle typographique, le système d'espacement et de rayons, ainsi que les règles de base pour empêcher un agent d'inventer un nouveau pattern face à un cas inconnu.
# DESIGN.md
## Color (semantic, light + dark)
--background / --foreground / --card / --primary / --muted-foreground …
## Type
Headings: Fraunces 600, -0.02em. Body: Inter 400, 1.6.
Scale: 0.875 / 1 / 1.25 / 1.5 / 2 / 3rem.
## Motifs
Hairline rules between sections. Radius scales with element size.
## Don't
No gradient text. No shadow on flat surfaces. Never hardcode a hex.La raison pour laquelle ce fichier fonctionne là où un prompt échoue est prosaïque : il est relu au début de chaque session. Les instructions contenues dans la conversation se dégradent à mesure que le contexte s'alourdit. Un fichier, non.
Les trois autres fichiers indiquent à l'agent comment travailler. Un seul lui indique à quoi le résultat doit ressembler, et c'est généralement celui qui n'existe pas.
Avez-vous besoin des quatre ?
Non, et commencer par les quatre est une erreur. Par ordre de retour sur investissement approximatif :
- `AGENTS.md` en premier. Valeur maximale par ligne, fonctionne avec tous les outils, rapide à rédiger.
- `DESIGN.md` ensuite, si vous livrez une UI. C'est le gain de qualité le plus important pour l'effort le plus faible, car rien d'autre ne le couvre.
- `CLAUDE.md` comme un import d'une ligne, avec un complément uniquement si vous avez réellement des règles spécifiques à un outil.
- Les skills en dernier, une fois que vous remarquez qu'une même procédure longue est expliquée à répétition.
Obtenir un DESIGN.md sans l'écrire
Chaque kit Identity Forge se sérialise en un DESIGN.md complet (tokens sémantiques en clair et sombre, un vrai couple de polices, motifs et règles de base) que tout agent de code peut lire. Les kits gratuits ne nécessitent aucun compte.
Combien de projets utilisent réellement chacun de ces fichiers ?
On compare généralement ces fichiers selon leur *finalité*. Il est utile de savoir comment ils sont utilisés en pratique, car c'est dans l'écart entre la convention et la pratique que naît la plupart des confusions.
Nous avons analysé 299 fichiers DESIGN.md situés à la racine de dépôts publics sur GitHub. Le premier constat recadre toute la comparaison : seulement 24 % d'entre eux décrivent réellement le design visuel. Les 76 % restants sont des documents d'architecture logicielle : comment un système est construit, et non à quoi un produit ressemble.
DESIGN.md est une collision de noms de fichiers
Ce nom précède de plusieurs années la convention du design system. Si vous en ajoutez un à un dépôt existant, attendez-vous à ce que certains lecteurs, et certains outils, s'attendent à un document d'architecture. Il est utile d'ajouter un en-tête d'une ligne précisant la nature du vôtre.
Parmi les 72 fichiers qui décrivent réellement un système visuel, la répartition des responsabilités argumentée plus haut n'est pas respectée. 86 % n'utilisent aucun nom de rôle sémantique pour les couleurs, le fichier ne peut donc être appliqué à aucun composant qu'il n'a pas explicitement décrit, ce qui est pourtant précisément sa raison d'être. 76 % n'énoncent aucune interdiction, alors que les interdictions sont la forme d'instruction que les agents suivent le plus fidèlement. 69 % omettent le mode sombre, laissant tout un thème à inventer.
L'analyse pratique : la plupart des projets qui ajoutent un DESIGN.md rédigent un document plutôt qu'un contrat. La différence réside dans la capacité d'un agent à en extraire une valeur sans avoir à deviner.
Si je ne dois écrire qu'un seul fichier, lequel choisir ?
AGENTS.md. C'est celui qui est lu par le plus grand nombre d'outils, il n'appartient à aucun fournisseur et contient les règles qui empêchent un agent de casser votre build. Si vous livrez une interface utilisateur, DESIGN.md arrive juste après, car rien d'autre ne couvre ce domaine.
Est-ce que AGENTS.md remplace CLAUDE.md ?
En grande partie. Conservez CLAUDE.md comme étant @AGENTS.md plus des règles spécifiquement dédiées à Claude. Supprimez complètement la fin si vous n'en avez pas. Une fin vide coûte moins cher qu'un doublon.
Ces fichiers sont-ils réellement lus, ou est-ce du cargo cult ?
Ils sont lus, mais ils ne sont pas magiques. Le mode d'échec observable est la longueur : un fichier d'instructions de 600 lignes entre en conflit avec lui-même, et les règles spécifiques sont noyées sous les règles générales. Les fichiers courts sont suivis plus fidèlement que les fichiers exhaustifs.
Est-ce que DESIGN.md peut simplement être intégré à AGENTS.md ?
C'est possible, et pour un petit projet, cela convient. La séparation devient pertinente dès que le système visuel gagne en profondeur, car les tableaux de tokens sont longs et évoluent selon un cycle différent des commandes de build, et parce qu'un fichier séparé peut être consommé par des outils qui ne lisent pas du tout les instructions des agents.
Que se passe-t-il lorsque deux fichiers sont en conflit ?
Le périmètre le plus restreint devrait l'emporter, mais ne comptez pas sur le modèle pour arbitrer proprement. Il vaut mieux supprimer les conflits plutôt que de les hiérarchiser : si deux fichiers ne sont pas d'accord, l'un d'eux est obsolète.