Un plugin Claude Code pour les conventions de toute l'équipe

Un assistant de code comme Claude Code se pilote au contexte : des conventions de nommage, des règles de style, des recettes pour ouvrir une Merge Request ou répondre à une review. Le réflexe naturel est d'écrire tout cela dans un CLAUDE.md à la racine du projet. Puis dans le suivant. Puis dans les vingt autres dépôts de l'équipe.

C'est là que le problème commence. Ce retour d'expérience part d'un contexte concret : un éditeur SaaS, une équipe répartie sur plusieurs dizaines de dépôts frères, et la même question posée en boucle — « c'était quoi déjà, la convention de branche ? ». La réponse n'a pas été un énième fichier de contexte, mais un plugin partagé, versionné et distribué comme une dépendance.

Le vrai problème n'est pas l'IA, c'est la dispersion

Chaque développeur refait, à sa manière, les mêmes gestes plusieurs fois par jour :

• nommer une branche aux conventions maison — et se tromper une fois sur trois ;
• rédiger un message de commit propre, avec le bon identifiant de ticket ;
• écrire une description de MR lisible pour le reviewer ;
• retrouver à quel client correspond un identifiant technique interne ;
• répondre aux retours de review et résoudre les fils un par un.

Autant de micro-frictions, refaites en double, avec des résultats inégaux d'un dev à l'autre. Le savoir-faire « comment on fait ça chez nous » reste dans la tête des anciens, et se transmet à l'oral.

Ajouter l'IA à cette situation ne la corrige pas : elle la duplique plus vite. Chaque projet finit avec sa propre copie des conventions, de ses gabarits et de ses recettes — vite divergentes. Une règle corrigée ici, oubliée là, et plus personne ne sait laquelle fait foi.

Les conventions ne devraient pas se dupliquer d'un projet à l'autre. Elles devraient vivre à un seul endroit, et tous les projets en hériter.

L'idée : traiter l'outillage IA comme un produit interne

Claude Code sait charger des plugins. Un plugin, c'est un simple dépôt Git qui regroupe, dans des dossiers auto-découverts, tout ce qui guide l'assistant :

• des commandes (slash commands) — les gestes du workflow ;
• des règles — style de code, sécurité, dimensions de review ;
• des agents — des sous-agents spécialisés, par exemple pour écrire des tests ;
• des skills — des procédures outillées, déclenchées par le contexte ;
• des hooks — des vérifications automatiques, par exemple au démarrage de session.

L'équipe l'installe une fois, depuis un marketplace interne, et le met à jour comme n'importe quelle dépendance :

/plugin marketplace add git@git.exemple.com:equipe/outillage.git
/plugin install outillage@equipe

À partir de là, les commandes /git:*, /jira:* et /gitlab:* sont immédiatement disponibles pour tout le monde, avec exactement les mêmes conventions. On ne distribue plus des bonnes pratiques dans un wiki : on distribue des gestes exécutables.

Un malentendu fréquent : « on a déjà une doc »

Beaucoup d'équipes pointent l'assistant vers leur README ou leur wiki et considèrent le sujet réglé : « c'est documenté, il n'a qu'à lire ». C'est une erreur de destinataire. La documentation écrite pour les humains et celle destinée à l'assistant ne sont pas — et ne devraient pas être — le même document.

Une doc humaine raconte. Elle explique le pourquoi, donne du contexte, laisse des zones grises que le lecteur comble avec son jugement et son expérience. « On préfère en général telle approche » suffit à un humain : il saura quand faire l'exception.

Un assistant, lui, applique — il n'interprète pas les sous-entendus. Il lui faut la règle explicite plutôt que l'implicite, l'impératif plutôt que la préférence, le format exact attendu plutôt qu'un exemple parmi d'autres. « Toujours », « jamais », « dans ce cas précis, faire ceci » : une doc pour l'assistant est opérationnelle et sans ambiguïté, là où une doc humaine peut se permettre la nuance et le non-dit.

La même règle, pour deux lecteurs différents :

• Écrite pour un humain — « On essaie de garder des commits atomiques et bien nommés. » Le lecteur comble le reste avec son jugement.
• Écrite pour l'assistant — « Un commit = une ligne au format type(scope): sujet, l'identifiant du ticket déduit du nom de branche, aucun trailer. » Rien à deviner, rien à interpréter.

Le problème est aussi quantitatif. Déverser quarante pages de wiki narratif dans le contexte de l'assistant noie l'instruction utile sous le récit : cela dilue les consignes, coûte des tokens et augmente les chances qu'il rate la règle au moment où elle compte. Une doc pour l'assistant est découpée et ciblée — la bonne règle remonte pour la bonne tâche, pas un pavé à trier à chaque fois.

Ce n'est pas dupliquer l'information, c'est la reformuler pour un autre lecteur. Le README reste écrit pour les humains ; les règles du plugin sont écrites pour l'assistant. Les deux décrivent la même réalité, mais chacun sert son public — et c'est précisément ce qu'un plugin permet de matérialiser : un artefact dédié, impératif, structuré par tâche, au lieu d'espérer qu'un agent devine vos conventions entre les lignes d'une doc pensée pour des humains.

Ce qu'on y met concrètement

Les gestes git, sans réfléchir aux conventions

Les commandes du quotidien encapsulent la convention plutôt que de la rappeler. Créer une branche part d'un develop à jour et applique le bon format sans jamais perdre le travail en cours. Composer un commit produit un Conventional Commit d'une seule ligne, avec l'identifiant du ticket déduit du nom de branche. Nettoyer les branches locales déjà mergées ne touche jamais aux branches de référence. La convention n'est plus une chose qu'on connaît : c'est une chose qui s'exécute.

Du ticket à la MR, sans quitter le terminal

Les recettes Jira et GitLab branchent l'assistant sur les outils réels, via le protocole MCP pour le ticketing et la CLI officielle pour le dépôt. S'attribuer un ticket et le passer « En cours », ouvrir la MR en la liant au ticket et en posant les bons reviewers, récupérer les fils de review non résolus pour les traiter un par un : chaque étape devient une commande, avec la même sortie pour tout le monde. Les descriptions de MR, les titres, les messages : uniformes sur tous les repos, parce que le gabarit est dans le plugin, pas dans la mémoire de chacun.

Les règles transverses, partagées une fois pour toutes

Au-delà des commandes, le plugin embarque les règles que l'assistant applique en continu — style PHP, checklist de sécurité, dimensions d'une revue de code, gabarit de description de MR. Elles vivent dans des fichiers Markdown, réutilisées comme des partials par les commandes qui en ont besoin :

git-branching.md            # nommage des branches
git-commit.md               # format des commits
mr-description.md           # gabarit de description de MR
php-style.md                # conventions de style
security.md                 # checklist sécurité
code-review-dimensions.md   # ce qu'une review doit couvrir

Corriger une règle de sécurité, c'est désormais une modification à un seul endroit, répercutée partout à la prochaine mise à jour. Fini les rules/ et CLAUDE.md recopiés et désynchronisés de dépôt en dépôt.

Câbler l'environnement, pas juste documenter

Un plugin peut aussi vérifier ses propres prérequis. Plutôt qu'un échec cryptique au milieu du travail, une commande s'arrête avec un message clair : telle CLI n'est pas authentifiée, tel connecteur MCP est absent, tel jeton d'API n'est pas défini — et la marche exacte à suivre pour le corriger. Un nouvel arrivant câble ses accès en quelques minutes, guidé pas à pas, sans aller fouiller la doc ni demander à un ancien.

Un garde-fou non négociable : le plugin ne contient aucun secret. Il vérifie qu'un jeton est présent et pointe vers la variable d'environnement qui le porte, mais ne le stocke jamais. Un plugin est un dépôt partagé et historisé : y écrire un token reviendrait à le diffuser à toute l'équipe et à le graver dans l'historique Git. On distribue des vérifications et des pointeurs, pas des identifiants.

Pourquoi ça change quelque chose

Une seule source de vérité

Une convention vit à un seul endroit : le plugin. Tous les repos en héritent. On peut même l'activer par défaut sur un projet, en l'ajoutant au .claude/settings.json du dépôt — il est alors proposé à toute personne qui l'ouvre :

{
  "extraKnownMarketplaces": {
    "equipe": {
      "source": { "source": "git", "url": "git@git.exemple.com:equipe/outillage.git" }
    }
  },
  "enabledPlugins": ["outillage@equipe"]
}

Un cycle de vie découplé des projets

L'outillage et les projets sont deux choses séparées. Faire évoluer une commande, une convention ou une recette ne touche pas au code, à la CI ni aux workflows des dépôts eux-mêmes : on ne commite pas dans une application de production pour ajuster une règle de nommage. Le plugin a son propre rythme, plus rapide : une idée d'amélioration → une MR sur le plugin → publiée → disponible pour tous, sans attendre une fenêtre de release ni risquer de perturber un repo en production. On itère sur comment on travaille sans payer le coût de ce sur quoi on travaille.

Le versionner comme une API

Ce découplage a une contrepartie : une convention publiée dans le plugin est un changement pour toute l'équipe — du jour au lendemain, tout le monde nomme ses branches autrement. On traite donc le plugin comme l'API qu'il est : montée de version explicite, changelog qui dit ce qui change et pourquoi, rétrocompatibilité par défaut quand c'est possible. Modifier un geste que des dizaines de personnes utilisent chaque jour se fait avec les mêmes égards qu'une release publique — pas au détour d'un commit silencieux.

Un onboarding qui capitalise le savoir-faire

Un nouvel arrivant installe le plugin et hérite immédiatement de la façon de travailler de l'équipe. Le savoir-faire est capitalisé et versionné, plus dispersé dans des notes personnelles. Et les reviews y gagnent : quand les branches, les commits et les descriptions de MR sont uniformes, le reviewer lit du code, pas de la mise en forme.

Les limites : quand ne pas le faire

Un plugin partagé n'est pas gratuit. Il a un coût de maintenance : quelqu'un doit en être responsable, arbitrer les contributions, gérer sa compatibilité dans le temps. En dessous d'une poignée de dépôts et de développeurs, un simple CLAUDE.md par projet reste le bon niveau d'investissement — ne pas sur-outiller une équipe de deux personnes.

Le second piège est l'inverse du premier : le fourre-tout. Une commande très spécifique à un seul projet n'a rien à faire dans un outil transverse. La règle reste la même que pour tout code partagé : on mutualise ce qui est réellement commun, on laisse le reste là où il est utilisé. Enfin, un outillage ne remplace pas l'adoption : si l'équipe ne se l'approprie pas, aucune commande ne fera respecter une convention à laquelle personne ne croit.

Conclusion

L'enjeu n'est pas d'ajouter de l'IA au workflow, mais d'industrialiser le workflow lui-même : en faire un artefact partagé, versionné, maintenu à un seul endroit, plutôt qu'un savoir oral recopié de projet en projet. C'est exactement la même discipline que pour une librairie de code interne : une frontière nette entre le commun et le spécifique, une rétrocompatibilité assumée, un responsable identifié.

Un assistant de code ne vaut que par le contexte qu'on lui donne. Autant faire de ce contexte un produit d'équipe, pas une note perso.

Pour démarrer sur cette approche

1. Repérer les gestes refaits en double :
   branche, commit, description de MR, réponse aux reviews. Ce sont les premiers candidats à devenir des commandes.
2. Extraire les conventions dispersées :
   rassembler les CLAUDE.md et rules/ éparpillés dans un seul plugin, et supprimer les copies.
3. Distribuer par un marketplace interne :
   une commande pour installer, une pour mettre à jour — l'adoption doit être plus simple que le copier-coller qu'elle remplace.
4. Nommer un responsable :
   l'outil est celui de l'équipe, mais sa cohérence dans le temps demande un arbitre.