Comment partager vos rules entre tous vos projets (sans les copier-coller) ?

Dans les deux premiers articles, on a vu ce qu'était une rule et comment créer les vôtres. À la fin du deuxième, il restait deux questions : comment choisir entre les bonnes pratiques que vous voulez mettre en place et l'existant qui ne les respecte pas ? Et une fois le choix fait, comment savoir si une règle est respectée dans votre code ?

Dans cet article, on va voir comment on a répondu à ces deux questions avec un plugin, et comment vous pouvez construire le vôtre.

Article 3/3 de la série Wana-Rules

Temps de lecture : ~7 min

Sommaire

• Pourquoi une library commune ?
• La library : des rules versionnées
• Adopter à la carte : /wana-rules:sync
• Mesurer l'écart : /wana-rules:audit
• Faire vivre les règles

Pourquoi une library commune ?

À la fin du deuxième article, on avait une belle library de règles, triées, reviewées dans un seul repo. Mais un fournisseur de solutions comme WanadevDigital, ce n'est pas un seul repo. Voilà ce qu'on constatait :

• Certains projets existants n'avaient pas ou peu de règles, et on retrouvait les mêmes retours en MR d'un projet à l'autre.
• Extraire et trier des règles, c'est long (vous avez lu l'article 2). Personne ne veut le refaire pour chaque projet.
• Et surtout, copier-coller des fichiers de règles entre projets, ça ne se maintient pas. Pas de versioning, chaque copie diverge, on ne sait plus qui a la dernière version, et une amélioration faite sur un projet reste sur ce projet.

Il fallait un seul endroit où vivent les règles, et un moyen simple pour chaque projet de s'y brancher. C'est ce qu'on a construit avec un plugin Claude Code qu'on a appelé wana-rules.

La library : des rules versionnées

On a d'abord déplacé toute la library dans un repo dédié : 115 sub-rules aujourd'hui, organisées comme dans le premier article (shared, frontend, backend). Ce repo est versionné comme un vrai projet, avec semver et changelog. Une amélioration de règle passe par une MR, et une fois mergée, elle profite à tous les projets.

On a ajouté des métadonnées à chaque rule, et les deux skills du plugin reposent dessus :

Ce qui nous sert dans ces métadonnées :

• force : le niveau de recommandation, highly-recommended ou recommended. Toutes les règles n'ont pas le même niveau d'importance, et c'est sur ce niveau que le sync filtre quand on lui demande de n'appliquer que les essentielles (on y revient dans la section suivante).
• last-update : la date de dernière modification. Elle sert au moment de resynchroniser, on y revient à la fin.
• sub-rules : un fichier de rule contient en réalité plusieurs conventions, les sub-rules. Notre typescript.md en contient cinq (préfixes de types, notation des tableaux, ordre des membres de classe...). Chaque sub-rule a son propre force, sa propre date, et surtout elle est adoptable indépendamment des autres. Dans la suite de l'article, rule désigne le fichier et sub-rule la convention unitaire qu'il contient.

Pour le refaire chez vous : un repo git structuré comme un marketplace de plugins Claude Code. Le plugin embarque les rules et deux skills : un pour adopter, un pour auditer. L'arborescence minimale tient en quelques fichiers :

mon-marketplace/
├── .claude-plugin/marketplace.json
└── mes-rules/
    ├── .claude-plugin/plugin.json
    ├── commands/
    │   ├── sync.md
    │   └── audit.md
    └── rules/
        ├── shared/
        ├── frontend/
        └── backend/

Le marketplace.json liste les plugins du repo, le plugin.json donne le nom et la version du plugin, chaque fichier de commands/ est un skill, et rules/ contient vos fichiers de rules avec leurs métadonnées.
Côté projet, deux commandes dans Claude suffisent pour se brancher dessus, une simple URL git fait office de marketplace :

/plugin marketplace add <url-git-de-votre-repo>
/plugin install mes-rules@mon-marketplace

Une fois en place on peut utiliser les deux skills qu'on va voir maintenant.

Adopter à la carte :

/wana-rules:sync

Un développeur qui veut brancher son projet sur la library lance /wana-rules:sync. Le skill parcourt la library et propose chaque rule, avec quatre choix : tout appliquer, choisir sub-rule par sub-rule, tout ignorer, ou décider plus tard.

Et c'est le point qui compte pour nous : tous les projets n'adoptent pas de la même manière. Chaque dév garde la main sur ce qu'il accepte ou refuse pour son projet.

• Un nouveau projet prend tout (mode --accept-all). Il n'a pas d'historique, aucun code existant à contredire : autant partir 100 % conforme dès le premier commit.
• Un projet existant choisit. Il a déjà ses conventions, du code legacy, des choix qui datent d'avant les règles. Lui imposer les 115 sub-rules d'un coup, c'est le meilleur moyen d'obtenir un code incohérent entre l'ancien et le nouveau. Il commence par les essentielles (mode --highly-recommended-only, qui ne garde que les highly-recommended), ou il fait son marché à la carte, sub-rule par sub-rule.

Le quatrième choix, décider plus tard, a plus servi que prévu. Une rule laissée de côté n'est pas notée dans le journal, le sync la reproposera au prochain passage. Chez nous, les intégrateurs ont fait le sync sur les rules qui les concernaient et ont laissé celles de la 2D et de la 3D pour plus tard. Les développeurs 2D-3D ont fait l'inverse. Chacun décide sur ce qu'il connaît.

Concrètement, le sync écrit deux choses dans le projet. D'abord un journal des décisions, référencé depuis le CLAUDE.md, avec la liste de ce qui est adopté, ignoré ou désactivé, et les dates.
Ensuite les règles adoptées, copiées dans .claude/rules/, où Claude les charge comme n'importe quelle rule, avec les globs du premier article. Comme le journal est versionné avec le projet, un nouveau dév voit tout de suite quelles règles s'appliquent ici et lesquelles ont été écartées.

On peut donc répondre à la première question de l'article. Entre vos bonnes pratiques et l'existant qui ne les respecte pas, la décision se prend règle par règle, projet par projet, et elle est notée dans le journal.

Mesurer l'écart :

/wana-rules:audit

Reste la deuxième question : comment savoir si une règle est respectée ? C'est le rôle de /wana-rules:audit, qui scanne le code du projet au regard des règles adoptées (et seulement celles-là).

Trois modes : complet, sélectif (on choisit les rules à scanner), ou échantillon (environ 10 fois plus rapide, pour se faire une idée). Le résultat est un rapport horodaté dans .audit/ qui donne, pour chaque règle, le nombre de violations et un niveau de confiance.

C'est là que le format DO/DON'T du deuxième article paie. Une règle en DO/DON'T se vérifie avec une confiance élevée. Une règle rédigée en prose part en confiance moyenne, avec de possibles faux positifs. Et certaines ne sont tout simplement pas auditables dans le code (le nommage des branches git par exemple) : le rapport le dit plutôt que d'inventer un résultat.

Chaque règle non respectée est accompagnée d'un prompt à copier-coller, prêt à envoyer à Claude : corriger les violations listées, ou désactiver la règle si elle ne colle finalement pas au projet.

On aurait pu mettre cet audit en CI. On ne l'a pas fait. Le but, c'est de mesurer l'écart et de le réduire à son rythme. Un audit qui bloque les MR, on n'en veut pas pour l'instant.

Faire vivre les règles

Une library de règles n'est jamais finie. La nôtre a un manque connu côté back, des règles qui vont se préciser, d'autres qui vont apparaître avec les technos. Ce qui compte, c'est comment elle évolue.

L'évolution passe par des MR. N'importe qui dans l'équipe peut proposer une règle ou une amélioration, et les référents techniques valident. Une fois la MR mergée, la version de la library est incrémentée et on note le changement dans le changelog.

Chaque projet resynchronise à son rythme. On relance /wana-rules:sync de temps en temps, et c'est là que le last-update des métadonnées sert. Le sync est incrémental : il ne repose des questions que sur les règles nouvelles ou modifiées depuis le dernier passage. Resynchroniser un projet à jour ne prend que quelques minutes. Chez nous, le rythme visé est un re-sync tous les 2 à 3 mois.

Un dév rencontre un cas dans son projet, il en fait une MR sur la library, et trois mois plus tard tous les projets de la boîte peuvent hériter de la règle.

La fin de la série

En trois articles, on a vu que les rules sortent votre code IA de la moyenne d'internet et lui apprennent vos conventions. Qu'elles ne s'écrivent pas de tête mais s'extraient de ce que votre équipe sait déjà, puis se trient et se font reviewer. Et qu'elles se distribuent dans tous vos projets avec une library versionnée, une adoption à la carte et un audit pour mesurer l'écart.

Le tout avec des briques standard de Claude Code : des rules, des skills, un plugin. De notre côté, la library va continuer à bouger, en particulier côté back. Si vous montez la vôtre, on sera curieux de voir ce que ça donne.