CLAUDE.md vs AGENTS.md vs SKILL.md vs DESIGN.md

Lisez du périmètre le plus étroit 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.

1. Ce que l'utilisateur dit durant la session — l'emporte toujours, même en cas de contradiction avec un fichier.
2. `SKILL.md` — actif uniquement lorsque cette compétence est invoquée, et limité à son périmètre.
3. `CLAUDE.md` / fichier spécifique à l'outil — le comportement de cet outil dans ce repo.
4. `AGENTS.md` — les règles du projet pour n'importe quel agent.
5. `DESIGN.md` — le contrat visuel, référencé par les éléments ci-dessus plutôt que d'être en concurrence avec eux.

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'auteur du travail : comment builder, comment tester, quoi ne pas toucher, et quelles conventions le codebase suit réellement.

La discipline cruciale ici est le coût. Il est chargé à chaque requête, donc chaque ligne est payée en permanence. Une règle ne mérite sa place en ligne que si elle modifie le comportement par défaut, s'applique largement et s'avère coûteuse en cas d'erreur. 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 un lien d'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.

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/`.

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. Cette 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 toutes les requêtes 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 de migration — vont dans un skill.

Voici la lacune. AGENTS.md n'a pas de place naturelle pour une palette de couleurs. CLAUDE.md concerne le comportement des outils. Une skill est invoquée, elle n'est pas ambiante. Ainsi, le contrat visuel finit par n'être nulle part — et un agent sans contrat visuel se rabat sur les valeurs par défaut, ce qui est la raison pour laquelle les sites générés par l'IA convergent vers un look unique.

Un DESIGN.md comble cette lacune. Au minimum, il contient les design tokens de couleur sémantiques pour les modes clair et sombre, l'appairage et l'échelle typographiques, le système d'espacement et de radius, ainsi que les « à faire » et « à ne pas faire » qui empêchent un agent d'inventer un nouveau pattern lorsqu'il est confronté à 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 peu glorieuse : il est relu au début de chaque session. Les instructions contenues dans une conversation se dégradent à mesure que le contexte s'élargit. Un fichier, non.

Non, et commencer par les quatre est une erreur. Voici l'ordre approximatif de rentabilité :

1. `AGENTS.md` en premier. Valeur la plus élevée par ligne, fonctionne sur tous les outils, facile à écrire.
2. `DESIGN.md` ensuite, si vous livrez de l'UI. C'est le plus grand écart de qualité pour le moins d'effort possible, car rien d'autre ne le couvre.
3. `CLAUDE.md` comme un import d'une ligne, avec une extension uniquement si vous avez réellement des règles spécifiques à un outil.
4. Les skills en dernier, une fois que vous remarquez la même procédure longue expliquée de manière répétée.

Ces fichiers sont généralement comparés 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 l'apparence d'un produit.

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 de couleur sémantique, le fichier ne peut donc être appliqué à aucun composant qu'il n'a pas explicitement décrit — ce qui est 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 concrète : 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.