Chapitre 3.3 — Des conventions qui tiennent

⏱️ TL;DR — Une convention n’est pas fiable parce qu’elle est écrite : elle est fiable quand elle est soutenue par plusieurs couches. Énonce-la (CLAUDE.md), montre-la (fichier-modèle), impose-la mécaniquement (lint/hook) quand c’est possible, et rattrape le reste en revue. Compter sur le seul CLAUDE.md marche pour les règles de jugement, mais échoue pour les règles mécaniques : le texte peut être oublié, un hook non. La cohérence, c’est de la redondance intelligente.

🎯 Objectifs

• Comprendre pourquoi une convention écrite ne suffit pas.
• Connaître les quatre couches d’application d’une convention.
• Choisir les bonnes couches selon la nature de la règle.
• Diagnostiquer une convention « qui ne tient pas ».

Pourquoi l’écrit seul ne suffit pas

Le CLAUDE.md est du texte dans le contexte. L’agent le pondère fort, mais ce n’est pas une garantie mécanique : sur une longue session, avec un contexte chargé, une règle peut passer à la trappe. Pour une règle de jugement (« préfère la composition à l’héritage »), c’est acceptable — de toute façon, aucune machine ne peut la vérifier. Mais pour une règle mécanique (« pas de any », « imports triés », « pas de couleur en dur »), s’en remettre à l’attention du modèle est un pari perdant à long terme. Ces règles-là méritent une garantie.

⚠️ Piège — Le réflexe « je vais l’écrire encore plus fort dans le CLAUDE.md » (en MAJUSCULES, avec trois points d’exclamation). Ça ne transforme pas une règle mécanique en garantie. Une règle mécanique se garantit par un hook/lint, pas par de l’emphase.

Les quatre couches

Pense à chaque convention comme soutenue par jusqu’à quatre couches, de la plus « molle » à la plus « dure » :

L’idée n’est pas d’empiler les quatre partout — c’est de choisir les couches adaptées à la règle :

• « Pas de any » → énoncer + imposer (TS strict + lint). La couche dure suffit presque seule.
• « Structure feature-folder » → énoncer + montrer (un dossier exemplaire à imiter). Difficile à linter, facile à montrer.
• « Nommage clair des variables » → énoncer + rattraper (revue). Pas automatisable, on l’attrape en relecture.
• « Server actions pour les mutations » → énoncer + montrer + imposer partiellement (un lint custom ou une convention de dossier).

💡 Réflexe d’architecte — Devant une convention, demande : « Quelle est la couche la plus dure qui peut la porter ? » Si une règle peut être imposée par les types ou le lint, mets-y l’énergie là — c’est la seule couche qui ne dépend pas de l’attention (ni de l’agent, ni de la tienne). Le CLAUDE.md devient alors un rappel, pas l’unique rempart.

La redondance est une force, pas un gaspillage

En code applicatif, la duplication est souvent un défaut. Pour faire tenir une convention, la redondance est voulue : énoncée et montrée et imposée, une règle survit à l’oubli de n’importe quelle couche. Le fichier-modèle rappelle ce que le texte décrit ; le lint rattrape ce que l’agent oublie ; la revue attrape ce que le lint ne voit pas. Chaque couche couvre les angles morts des autres.

Diagnostiquer une convention qui ne tient pas

Quand une règle est régulièrement violée, ne t’énerve pas sur l’agent : diagnostique la couche manquante.

🧭 Sur TaskFlow — « UI depuis src/components/ui/ uniquement » est difficile à linter finement. On la fait tenir par montrer (le Button modèle + un index.ts d’export) et imposer partiellement (une règle ESLint interdisant d’importer un composant d’UI hors de ce dossier). En Partie 7, on ajoutera le hook qui refuse un any glissé. Chaque convention reçoit les couches qu’elle mérite.

✏️ Exercices

Exercice 1 — Attribue les couches. Prends 5 de tes conventions. Pour chacune, note les couches adaptées (énoncer / montrer / imposer / rattraper) et la plus dure applicable.

Exercice 2 — Répare une règle molle. Choisis une convention souvent violée chez toi. Identifie la couche manquante et ajoute-la (un fichier-modèle, une règle de lint, ou une étape de revue).

🧠 Quiz de révision

Chapitre suivant : Mémoire : hiérarchie & persistance — gérer la mémoire dans le temps, entre projets et entre sessions.