# Les conventions de code à l'ère de l'IA Prenez deux développeurs de la même équipe, donnez-leur la même fonctionnalité à implémenter. IA ou pas IA, vous aurez deux versions différentes. En freelance, aucun problème : vous êtes seul maître à bord, vous avez votre manière d’écrire le code. Mais en agence, tout change : pour gagner en efficience, je suis de ceux qui pensent qu’il faut standardiser les manières de développer. Maintenant, mettez une IA dans tout ça : vous récupérez deux implémentations, fonctionnelles… et qui ne se ressemblent pas du tout. Ça n’est pas un bug, ça n’est pas la faute de l’IA, ou en tout cas c’est autant votre faute que celle de l’IA : c’est juste l'absence de conventions partagées, rendue visible à une vitesse qu'on n'avait jamais connue avant. Chez BSA Web, nous avions fait ce constant bien avant l’IA : tous les vendredis matins, lors de nos sessions R&D, une partie du boulot consistait à écrire de la documentation. Nous sommes même allés plus loin : pour notre framework interne, Forge, interdiction de merger quoi que ce soit si aucune documentation lisible par un humain n’était fournie (donc les PHP DocBlock ne comptent pas, les README.md non plus). À l'ère de l'IA, les conventions ne peuvent plus vivre dans la tête des devs, de notre directeur technique, ni dans une page de wiki (Outline dans notre cas) que personne ne relit. Elles doivent être chargées dans le contexte de l'IA, vérifiées et vérifiables par la machine. > Les conventions de code implicites, orales ne survivaient pas aux humains, même dans les petites équipes. Elles ne survivront pas non plus à l'IA. > > Benjamin - Développeur Avant, les conventions d'une équipe se transmettaient au cours d’un projet, lors de discussions : quand nous étions deux développeurs, sans appel à des freelances, cela fonctionnait plutôt bien. On apprenait ensemble, en se faisant des commentaires lors de reviews, en passant du temps sur le projet, on s’appelait pour se demander quelle était la meilleure manière de faire, quelle architecture choisir… Et on partageait le même bureau : partager nos expérimentations était forcément très facile. Mais plus l’équipe grandit, et plus ces standards disparaissent. Plus l’équipe grandit, et plus - malgré toute la bonne volonté du monde - il devient compliqué de transmettre l’intégralité des informations et décisions prises dans le cadre technique à tous les développeurs. Avec les IA agentiques, le volume de code produit peut vite exploser (damn), et les standards peuvent ne plus suivre. Une IA reproduit ce qu'elle voit : si votre projet est incohérent, elle amplifie l'incohérence. Si vos conventions ne sont écrites nulle part, elle ne peut tout simplement pas les appliquer : c’est pareil pour un humain. Et le vrai sujet quand on travaille à plusieurs a changé de nature. La question n'est plus « est-ce que mon collègue code comme moi », mais « est-ce que son agent code comme le mien ». Deux devs avec deux configurations Cursor ou Claude différentes, c'est deux styles de code, deux façons de structurer un plugin, deux niveaux d'exigence sur les tests. Multipliez par le nombre de projets, et la dette diverge plus vite qu'avant. ## Notre parti-pris : des plugins Claude Code versionnés et partagés Plutôt que de laisser chaque dev bricoler son `AGENTS.md` personnel, on a construit un marketplace de plugins Claude Code interne, hébergé sur notre GitLab. Pour situer : Claude Code permet de packager des instructions, des skills (des instructions détaillées que l'IA charge à la demande) et des agents spécialisés sous forme de plugins installables. Chaque dev de l'équipe ajoute le marketplace une fois, puis installe les plugins correspondant à son profil : ``` /plugin install bsaweb-core@bsaweb-marketplace /plugin install bsaweb-dev@bsaweb-marketplace /plugin install bsaweb-wordpress@bsaweb-marketplace /plugin install bsaweb-version-control@bsaweb-marketplace ``` La chance que l’on avait, c’est que toute notre documentation était déjà écrite, dans [Outline](https://github.com/outline/outline) (une alternative à Notion). Nous n’avons pas eu à produire une quantité de how-to, de justifications de pourquoi on travaille comme ça au moment de l’arrivée de l’IA et il faut avouer que ça a grandement contribué à notre prise en main rapide de l’outil. ![Capture d'écran du logiciel Outline](https://www.bsa-web.fr/app/uploads/2026/06/bsaweb-site-conventions-code-ia-1024x683-1.jpg)### Notre découpage : un plugin = un domaine de responsabilité On a découpé par domaine, pas par projet. Ça donne aujourd'hui neuf plugins : - **bsaweb-core** : les méta-outils transversaux : checklists qualité, ton de voix de l'agence, outils de rétrospective sur nos propres skills ou notre configuration Claude, - **bsaweb-dev** : le tronc commun web, indépendant du CMS : SCSS, accessibilité, React, agents back et front génériques. - **bsaweb-wordpress** : tout le spécifique WordPress : Gutenberg, FSE, theme.json, Interactivity API, comment on déclare un hook, un CPT, une taxo... et notre framework interne Forge. - **bsaweb-woocommerce** : le spécifique e-commerce, encore une coquille qu'on peuple progressivement : par exemple, comment on créé une nouvelle passerelle de paiement ? - **bsaweb-version-control** (tout le monde) : le workflow Git : commits conventionnels, création de MR, orchestration des reviews, split de MR si ces dernières sont trop conséquentes... - **bsaweb-maintenance**, **bsaweb-project-manager**, **bsaweb-devops**, **bsaweb-media-production** : respectivement le support client, le cadrage projet (PRD, estimation), l'infra, et la production de contenu. Ce découpage n'est pas cosmétique. Un dev WordPress active quatre plugins, quelqu'un qui fait du support en active deux autres, personne ne charge dans son contexte des conventions qui ne le concernent pas (on préserve nos tokens héhé). Quand WooCommerce mérite ses propres règles, elles ont déjà leur place. Si demain, on se met à une autre stack, il faudra que l’on créé un autre plugin. D’où l’idée d’avoir un tronc commun pour le développement (bsaweb-dev) et pour la vie de l’agence (bsaweb-core). Dernièrement, je réfléchis par exemple à un plugin `bsaweb-gravity-forms` : ce dernier pourrait nous servir à documenter comment envoyer des données à une API tierce, comment on enregistre un nouveau type de champ, de nouveaux réglages... ## Après quelques mois d'utilisation, ça donne quoi ? La convention n'est plus un document, c'est du contexte versionné, lisible par l’IA et par les humains. Un premier exemple : chez nous, on ne code jamais de fil d'Ariane custom, on délègue toujours à SEOPress ou Yoast, c’est leur métier, et on se rajouterait de la dette technique en le faisant. Avant, cette règle vivait dans nos têtes. Aujourd'hui, c'est un skill `add-breadcrumbs` dans `bsaweb-wordpress` : quand n'importe quel dev demande à l’IA d'ajouter un breadcrumb, l'IA charge la règle et l'applique. La convention s'exécute toute seule. Claude sait comment altérer les breadcrumbs de ces plugins si besoin. Ici, on parle volontairement d’un exemple très atomique : on considère que chaque tâche que l’on réalise, même la plus petite, peut aujourd’hui être documentée sans effort. Autre exemple, l’autre jour, je travaillais sur un bloc “Diagramme de Gantt”. J’ai donc exploré plusieurs options : est-ce qu’on utilise une librairie ? Est-ce qu’on affiche le diagramme simplement via un CSS Grid ? A la fin de la discussion avec l’IA, une fois que la décision était prise, je demande automatiquement à cette même IA d’écrire un SKILL.md correspondant : `create-gantt-diagram`. Toutes les décisions que l’on a tranchées ici sont désormais tranchées pour tous les autres développeurs. Autre conséquence qu'on apprécie : une convention qui évolue passe par une merge request sur le dépôt du marketplace. Elle est relue, discutée, versionnée, et toute l'équipe la récupère au prochain `/plugin update --all`. On traite nos conventions et nos décisions comme du code. Le fait de versionner permet aussi de faire évoluer cela : si demain on décide que c’est mieux de passer par un bloc custom pour faire un fil d’Ariane, on créé ce bloc, on met la règle à jour et bingo : l'auto-update fait son job et tout le monde est au courant en même temps ! ## Notre prochaine étape : les linters Les plugins donnent le bon contexte à l'IA, mais un contexte n'est pas une garantie. Pour la partie vérifiable mécaniquement, on est en train de mettre en place deux linters : **PHPCS** pour le PHP et **Stylelint** pour le SCSS. Pour PHPCS, on n'utilise pas les WordPress Coding Standards tels quels : on a construit un ruleset maison. Certains standards officiels de WordPress nous semblent franchement datés, et on ne voulait pas imposer à l'équipe des règles auxquelles on ne croit pas. On y consacrera un article dédié, parce que le sujet mérite qu'on s'y attarde (et surtout, on veut justifier pourquoi on trouve ça franchement daté par moment). Le déploiement se fait en deux temps : 1. **D'abord en hooks Claude Code.** Le lint tourne au moment précis où l'IA écrit le fichier. L'agent voit l'erreur immédiatement et la corrige dans la même session, avant même le commit. C'est la boucle de feedback la plus courte possible, l’agent n’a pas à y réfléchir et c'est l'endroit le plus rentable pour un linter quand une bonne partie du code est générée. 2. **Ensuite en CI GitLab.** Le filet de sécurité bloquant sur la MR, pour tout ce qui passe entre les mailles : éditions manuelles, projets legacy, dev qui a désactivé ses hooks. Le principe derrière tout ça : ce qu'une machine peut vérifier ne doit jamais consommer du temps de review humaine. Une review qui contient « il manque un espace ici », c’est clairement du temps perdu pour tout le monde : le développeur, le reviewer, le client. On met de plus en plus en place des rules Claude également. Cela permet d’appliquer des règles sur des fichiers précis, que ce soit par extension de fichier, par domaine métier… > Quoi qu'il arrive, un LLM ne doit pas être la référence pour TOUT. Si on peut faire quelque chose de manière "scriptable", il faut le faire. C'est bien plus fiable. ## La revue de code, plus importante que jamais Il y a un paradoxe apparent : si l'IA écrit le code, on pourrait se dire qu'on a moins besoin de le relire. Notre expérience dit exactement l'inverse. Le code arrive plus vite, (souvent) en plus gros volume, et surtout il est *plausible* : l'erreur d'une IA est syntaxiquement propre, bien commentée, et passe les linters et tests sans broncher. C'est exactement ça le problème : les erreurs ne se voient pas ! Notre réponse tient en deux étapes. 1. **Premier étape : une review automatisée par agents spécialisés.** Notre plugin `bsaweb-version-control` embarque un skill `mr-review` qui orchestre plusieurs agents sur chaque merge request, selon la stack détectée : un reviewer backend qui connaît nos conventions Forge et les pratiques WordPress, un reviewer frontend qui vérifie les blocs Gutenberg et le SCSS, un reviewer sécurité qui tourne sur *chaque* MR sans exception : échappement, sanitization, nonces, capabilities, requêtes SQL, un agent performance, parfois un agent métier… Ces agents chargent les mêmes conventions que celles qui ont servi à générer le code : la boucle est cohérente de bout en bout. Pour cela, nous avons mis en place le principe **d’ADR**. Je vous renvoie à l’article de blog de Stéphane Robert. Pour faire court : chaque décision dans un projet fait l’objet d’un fichier Markdown qui consigne la décision, pourquoi elle a été prise. L’IA a accès à ces ADR, et peut donc arbitrer plus facilement. 2. **Deuxième étape : la review humaine, recentrée.** Déchargée du style par les linters et du premier passage technique par les agents, elle peut enfin se concentrer sur ce que la machine ne voit pas : le sens métier, les choix d'architecture, et la question qu’on se pose souvent mieux que l’IA : est-ce qu'on devait écrire ce code tout court ? Soyons honnêtes : la review par agent ne remplace pas l'humain. Elle change ce que l'humain regarde. Elle permet de faire une première passe, de repérer les énormités, ces lignes qui nous font dire en relisant “Mais pétard, comment j’ai pu écrire ça ?”. ## Nos axes d'amélioration On ne va pas prétendre que notre système est terminé, deux chantiers nous occupent toujours sur ces thématiques. ### Rendre toutes nos conventions machine-réviewables Il reste chez nous des conventions non-écrites. Notre objectif est simple à énoncer, mais un peu plus long à mettre en place : chaque convention doit finir soit dans un ruleset de linter, soit dans un skill chargé par l'IA, soit dans la checklist d'un agent reviewer. Une convention qui n'est encodée nulle part n'existe pas : elle ne survivra ni à un départ, ni à un agent qui ne l'a jamais vue. **C’était valable bien avant l’IA.** ### L'adoption homogène en équipe Un marketplace ne sert à rien si la moitié de l'équipe code à côté. On travaille donc l'adoption comme on travaillerait un produit interne : des versions, des changelogs, et des skills de rétrospective (`learn`, `claude-critique`) qui permettent à chacun de proposer des améliorations aux plugins à partir de ses sessions réelles. Nos plugins et nos skills doivent s’améliorer par l’usage. C’était aussi valable hors IA. La CI lint n'est pas encore branchée partout. Les hooks Claude Code tournent, le ruleset se stabilise, la généralisation en pipeline est la prochaine étape. ## Pour conclure L'IA n'a pas rendu les conventions de code obsolètes, bien au contraire, elle “redonne la part belle à la documentation” (pour citer [Jérémy Desvaux](https://jdmweb.com/blog/) 👋🏻). Une convention écrite une fois dans un plugin, un ruleset, un agent reviewer, un Notion, peu importe où elle est en réalité, est applicable par toutes les personnes de l'équipe. À l'inverse, une convention implicite est ignorée à la même échelle. C’était déjà le cas avant, sauf que désormais : - C’est bien plus rapide à faire écrire, donc vous n’avez plus d’excuses. - L’IA la lit si on lui dit de la lire, a contrario de certains humains (oups) ### Et pour aller plus loin : - Pour écrire de la documentation : Diàtaxis : - En savoir plus sur les ADR : - Créer une marketplace de plugins Claude :