Installer Claude Code dans une équipe de dev sans créer de dette

Un agent de code fait gagner du temps dès le premier jour. La dette, elle, arrive plus tard : du code qui passe les tests mais que personne dans l’équipe ne sait expliquer, des conventions appliquées une fois sur deux, une documentation qui décrit un système qui n’existe plus. Aucune de ces dettes n’est propre à l’IA. L’IA les produit simplement plus vite.

Voici les garde-fous que j’applique dans mes propres repos — les mêmes que je propose d’installer dans une équipe.

Écrire ce que l’agent doit savoir

Un développeur qui arrive dans l’équipe apprend les règles implicites en quelques semaines. Un agent repart de zéro à chaque session. Tout ce qui compte doit donc être écrit, dans le repo, versionné et relu comme du code : un CLAUDE.md à la racine (stack, structure, conventions, sens des dépendances, pièges connus), et des procédures pour les gestes récurrents — ajouter une page, corriger un bug, relire une PR.

Ce document se rédige avec l’équipe, pas pour elle. C’est l’occasion de découvrir que trois personnes appliquaient trois conventions différentes : mieux vaut le trancher avant que l’agent n’en invente une quatrième.

Rendre les règles exécutables

Une règle écrite dans un fichier Markdown est un souhait. Une règle vérifiée par la CI est une règle. Chaque fois qu’une consigne peut devenir un type, une règle de lint ou un test, elle doit le devenir.

Un exemple tiré de ce site : les URL anglaises des articles sont déclarées à la main dans un module de routage, séparément du contenu, pour des raisons de performance. Le risque est évident : un article publié sans sa route, ou une route qui pointe vers un article supprimé. Plutôt qu’une consigne « pensez à mettre les deux à jour », un test compare les deux listes et casse la CI au moindre écart.

Des specs avant les prompts

Pour toute fonctionnalité qui dépasse une heure de travail, la séquence est : spécification écrite, relue par un humain, puis implémentation par l’agent, puis revue du diff contre la spécification. La spécification contient les critères d’acceptation, le plan de tests et les pièges connus du code existant. Le prompt d’implémentation en découle, il ne la remplace pas.

La revue change de nature : on ne se demande plus « est-ce que ce code me plaît ? » mais « est-ce qu’il fait ce qui était décidé, et rien d’autre ? ». Une question à laquelle on répond vite et bien.

Traiter la doc comme du code

Avec un agent, la documentation n’est plus une politesse faite aux futurs arrivants : c’est une entrée du système. Une doc fausse produit du code faux, avec assurance. Sur ce site, une documentation de sécurité périmée a orienté tout un cadrage vers une contrainte qui n’existait plus. La parade est simple et rarement appliquée : la checklist de PR demande de mettre à jour la doc que le changement touche, et le relecteur le vérifie.

Garder l’humain aux bons endroits

L’agent peut tout proposer ; il ne doit pas tout exécuter. Mise en production, migrations de données, suppression, envoi à des tiers : ces actions restent validées par une personne. C’est aussi vrai quand l’IA est dans le produit. Novera Signal, un agent en production, prépare chaque message de prospection mais n’en envoie aucun seul : c’est une décision d’architecture écrite, consignée dans un ADR, pas un réglage.

Par où commencer

1. Choisir un seul repo, représentatif, plutôt que tout déployer d’un coup.
2. Écrire son CLAUDE.md avec l’équipe, en tranchant les conventions contradictoires.
3. Brancher dans la CI tout ce qui peut l’être : types, lint, tests, build.
4. Piloter sur une fonctionnalité réelle, spécification comprise, et relire le résultat ensemble.
5. Étendre aux autres repos ce qui a marché, et seulement ça.

C’est la méthode que j’applique à mes propres produits, décrite en détail dans comment je construis un SaaS en solo avec Claude Code.