Comment créer vos premières rules pour Claude Code ? (sans les écrire de tête)

Dans le précédent article, on a vu ce qu'étaient les rules, où les positionner et surtout à quoi elles servent. Si vous ne l'avez pas lu, je vous invite à le faire avant de lire celui-ci.

Restait une question : ces règles, d'où sortent-elles ? Le réflexe serait de les écrire de tête. Mauvaise idée : de tête, vous obtiendrez des règles génériques que Claude connaît déjà, et vous passerez à côté de celles qui font vraiment votre façon de travailler. Vos règles existent déjà : dans votre code, vos reviews, vos réunions.

Dans cet article, on va voir comment on les a extraites chez Wanadev, et comment vous pouvez le faire à votre tour.

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

Temps de lecture : ~8 min

Cet article est le 2ème d'une série de 3 articles sur les rules pour Claude Code et leur application chez WanadevDigital, avant de lire cet article, consultez d'abord le 1er de cette série.

Sommaire

• Extraire les règles
• Trier les règles
• Faire reviewer les règles
• Améliorer la qualité des règles
• La méthode en résumé

Extraire les règles

La première étape n'est pas de rédiger, c'est de collecter. Reste à savoir où chercher.

Au sein de l'agence, on a plusieurs types de projets : des courts, des longs, des anciens, des nouveaux. Et en termes de technos, c'est très variable aussi, entre le back (Symfony et Nest), le front (Vue), la 2D (Fabric.js ou Paper.js) et la 3D (Babylon.js ou Three.js). Nos règles devaient couvrir tout ça.
On est partis de quatre sources, que vous avez probablement aussi chez vous.

1. Les règles déjà écrites chez vous

Cherchez d'abord ce qui existe déjà : un guide de conventions, un README, des notes d'équipe. Chez nous, Louis, Lead frontend, avait déjà rédigé un premier jet de règles pour son équipe. Des conventions déjà écrites, déjà discutées : c'est le point de départ idéal.

2. Vos projets réels

Identifiez les projets qui vont servir de référence.
Si dans votre entreprise vous n'en avez qu'un, c'est facile !
De notre côté, nous avons choisi les technos qu'on porte actuellement et les projets qu'on estime les plus avancés en termes de bonnes pratiques (souvent les derniers). Demandez ensuite à Claude d'en extraire des règles réutilisables, des bonnes pratiques.

Il faut éviter de tomber dans le piège d'extraire des règles trop particulières au projet. Claude extrait ce qu'il voit, pas ce qui a été décidé. On a eu le cas d'une convention sur le nommage d'un dossier de textures dans nos assets 3D : la règle extraite ne venait d'aucune décision, juste d'une habitude sur un projet. On a vérifié avec la personne concernée avant de la garder et de l'étendre aux autres projets.

3. Vos réunions techniques et votre base de connaissances

Vos comptes rendus de réunions techniques sont une mine : ce sont des décisions actées, qui ne sortent pas de nulle part. Chez Wanadev, les équipes techniques se réunissent chacune de leur côté et toutes ensemble (deux réunions par mois). Au cours de ces échanges, on partage des bonnes pratiques, on discute, puis on vote les règles qu'on adopte ou non. Les comptes rendus des dernières années ont été passés à l'extraction, et ça a été extrêmement précieux pour nous.

Dans la même veine, on maintient une base de connaissances sur Notion, avec de nombreux articles de bonnes pratiques, notamment rédigés par les équipes de modélisation et d'UX/UI. Elle aussi est passée à l'extraction.

4. Les grands principes connus

DRY, SOLID, Clean Architecture. Claude les connaît déjà, mais les écrire explicitement dans nos rules lui dit qu'on y tient, et surtout comment on les applique.

À ce stade, vous avez extrait un GROS ensemble de règles. Mais ce gros ensemble n'est pas directement utilisable : les règles ne sont pas encore bien définies, pas encore rangées, et parfois même en contradiction entre elles (tel projet ne fait pas comme tel autre projet). Il va falloir trier.

Trier les règles

C'est la partie la plus longue, mais c'est elle qui fait passer d'un gros tas de règles plus ou moins importantes aux règles que vous allez vouloir promouvoir. Le tri se fait en deux passes : une passe automatique, avec Claude, puis une revue manuelle, par vous.

La passe automatique d'abord. On utilise Claude pour détecter les règles en contradiction. On peut aussi donner un indice de confiance selon leur provenance. Par exemple, pour nous, les choix faits au cours des réunions avec toute l'équipe technique avaient un fort indice de confiance. À l'inverse, les règles extraites d'un seul projet avaient un indice plus faible.

Détecter les contradictions, c'est le travail de Claude. Les trancher, non : je ne l'ai surtout pas laissé faire. La consigne : à chaque opposition, me poser la question au lieu de choisir. Quand je pouvais trancher seul, je tranchais. Quand la décision appartenait à l'équipe, la question partait dans un fichier OPEN_QUESTIONS.md versionné avec les rules. Les questions ont été tranchées au fil des réunions, et avant de merger, le fichier a été supprimé : les questions restantes sont devenues des tickets. Une contradiction entre deux règles, c'est une décision d'équipe qui n'a pas encore été prise. L'IA peut la détecter, pas la prendre.

Jusque-là, Claude se débrouille bien avec une intervention minimale de notre côté. La deuxième passe, elle, doit être manuelle.

La revue manuelle se fait règle par règle, avec des critères simples et quatre issues possibles : on garde, on jette, on adapte, on ne sait pas. J'avais un peu peur que cette étape soit longue et pénible. En fait, elle est très instructive : vous vous remémorez vos propres règles, et vous mettez en évidence les sujets jamais tranchés chez vous (de quoi alimenter vos prochaines réunions techniques).

Le « on adapte » mérite un mot. Beaucoup de règles disaient presque la même chose. Soit c'est un vrai doublon et on fusionne. Soit la nuance est justifiée et on précise : une règle sur la gestion des entités n'a pas la même forme en 2D et en 3D, et forcer une fusion aurait donné une règle molle qui ne dit plus rien.

Reste à ranger les règles. Comme expliqué dans le premier article, on a choisi de les regrouper d'abord par domaine (front, back, shared), puis par techno/sujet/savoir-faire (i18n, 3d-assets, architecture, comments, etc.).

Faire relire les règles

Vos règles vont s'appliquer à tous vos futurs projets et contraindre toute l'équipe : elles méritent le même niveau de review que du code de prod. Une fois le tri fini, je n'ai donc pas mergé tout seul dans mon coin : j'ai ouvert une merge request et demandé une review à tous les leads dev. Je vous donne les chiffres, parce qu'ils disent quelque chose du sérieux de l'exercice : un mois de travail, 25 commits, 129 threads de discussion sur la MR.

Cette review a produit quatre choses.

Des règles supprimées

Le débat le plus intéressant : « cette règle n'est-elle pas déjà dans ESLint ? » On a fini par poser la question à Claude lui-même, et sa réponse a fixé notre doctrine. Il ne lit pas les configs ESLint avant de générer du code. Une règle purement de formatage (quotes, points-virgules) sort des rules : ESLint la corrige après coup, gratuitement et sans token. Une règle structurelle (imports absolus, nommage, architecture) reste : Claude doit la connaître au moment où il écrit, pas après. Le chemin inverse existe aussi : une de nos rules s'est révélée implémentable en ESLint, elle est devenue un ticket sur notre config de lint partagée.

Des règles défendues

Un lead ne partageait pas notre convention de nommage des booléens en is*. La réponse n'a pas été « c'est mon avis contre le tien » : cette convention a été votée en réunion et documentée. Réponse de Louis sur le thread : « L'idée est que les décisions soient prises et contraignantes. Ça évite des discussions interminables lors des reviews. » C'est exactement ce qu'une rule apporte : elle n'est pas l'avis du dernier qui a parlé, elle porte une décision d'équipe.

Des règles ajustées

Notre règle de nommage des branches Git reprenait telle quelle une décision de réunion. La review a montré qu'elle n'était plus adaptée aux nouveaux projets : sans le numéro d'issue en préfixe, la MR ne s'attache pas au ticket dans GitLab. La règle a été resserrée. Une décision d'équipe peut être remise en question quand le contexte a changé, et la review des rules est le bon endroit pour ça.

Des règles nées pendant la review

Léo, lead 2D 3D, a proposé une règle qu'on utilisait mais qu'on n'avait écrite nulle part : ne jamais rendre réactives des classes contenant des objets d'un moteur (Three.js, Paper.js), sous peine de faire s'effondrer les performances. Elle est entrée dans la library avec la recommandation shallowRef. La review ne fait pas que filtrer : elle fait émerger les règles que tout le monde applique mais que personne n'a jamais écrites.

Et pour tout ce qui n'était pas tranché à la fin ? Six tickets de follow-up. On n'a pas bloqué la MR sur des débats de fond : une library de rules se merge imparfaite et s'améliore ensuite.

Améliorer la qualité des règles

Tout ce processus nous a appris ce qui fait une bonne règle. Quatre critères, à appliquer à chacune des vôtres.

Des règles courtes et atomiques

Une règle trop générale, Claude ne peut rien en faire. « Écrire du code maintenable » ne lui apprend rien. « Toute constante a un nom explicite et une unité » lui dit exactement quoi faire.

Des DO/DON'T partout où c'est possible

Claude arrive mieux à les gérer, et en plus vos règles deviennent auditables plus facilement : il saura dire quand une règle n'est pas respectée. On verra dans le troisième article que ça a son importance.

Attention aux règles fausses

Il vaut mieux ne pas avoir de règle qu'une règle fausse. Claude va traiter une règle fausse comme vraie, alors que sans la règle il aurait vérifié lui-même le code du projet.

Des règles qui évoluent

Enfin, et c'est vraiment le plus important, il faut que les règles vivent. Ça implique :

• Permettre à toute personne de proposer des règles via des MR.
• Laisser les référents techniques maîtres de leurs règles : ils ont sûrement des règles implicites, des retours qu'ils font souvent en review.

La méthode en résumé

Si vous voulez le faire à votre tour :

1. Collectez large : les règles déjà écrites chez vous, vos projets de référence analysés par Claude, vos comptes rendus de réunions techniques, les grands principes auxquels vous tenez.
2. Traquez les contradictions et faites-les trancher par l'équipe, jamais par l'IA.
3. Passez tout en revue manuellement : on garde, on jette, on adapte, on ne sait pas.
4. Faites-les reviewer par les gens qui vont vivre avec, au même niveau d'exigence que du code de prod.
5. Formatez en DO/DON'T et gardez les règles atomiques.

Vous avez maintenant de quoi créer, trier et faire reviewer vos propres règles. Le plus gros du travail est là.

La suite

Il reste quelques soucis. Le premier : comment choisir entre les bonnes pratiques que vous voulez mettre en place et l'existant qui ne les respecte pas forcément ? Le deuxième : comment savoir si une règle est respectée dans votre code ? Et derrière ces deux questions, il y a la gestion au quotidien d'une library de règles partagée entre plusieurs projets et plusieurs technos. C'est à tout ça que je répondrai dans le troisième et dernier article sur les rules.