Une IA généraliste à qui l'on demande tout, tout le temps, finit par tout faire un peu. Ce que j'ai construit autour de Claude Code ressemble plutôt à une petite équipe : des rôles précis, des savoir-faire rangés, et des garde-fous pour les erreurs qui coûtent cher. Voici ce que j'utilise réellement, sur quels projets, et ce que j'ai appris en le faisant tourner.
Trois briques : instructions, agents, skills
- Le fichier d'instructions (
CLAUDE.md) pose les règles du terrain, lues à chaque session : répondre en français, tests obligatoires sur le backend, format des messages de commit, outils du projet à utiliser. C'est la convention d'équipe. - Les agents sont des rôles : un analyste qui rédige les specs, un relecteur qui note le code. Chacun travaille dans son propre contexte, avec ses consignes, et rend un livrable.
- Les skills sont des savoir-faire empaquetés : une méthode de maintenance, un protocole d'analyse statistique, un guide de rédaction. Claude ne les charge que lorsque la tâche les demande, ce qui garde le contexte léger.
La chaîne d'une fonctionnalité
Pour une fonctionnalité de taille sérieuse, j'enchaîne six étapes, chacune confiée à un agent spécialisé :
/specétape 1@spec-analyst
Questions, risques, critères. S'arrête pour attendre ma validation.
/planétape 2@implementation-planner
Changements minimaux, fichier par fichier, avec retour arrière.
/implementétape 3@code-implementer
Tests d'abord, trois essais maximum, commit propre.
/reviewétape 4@code-reviewer
Note sur 100 : tests, complexité, clean code, archi.
/refactorétape 5@code-refactorer
Seulement si la note est sous 80.
/cleanétape 6@doc-cleaner
Supprime specs et plans temporaires, après confirmation.
La base vient d'un pack open source (Agentic Substrate), que j'ai adapté à ma façon de travailler :
- La spec remplace la recherche en tête de chaîne. Le premier agent ne part pas chercher de la documentation : il me pose des questions et rédige une spécification, puis s'arrête pour attendre ma validation.
- Le bon modèle pour chaque rôle. L'agent de recherche documentaire tourne sur un modèle plus économique ; ceux qui prennent des décisions d'architecture ou écrivent le code, sur le plus capable.
- Une revue chiffrée. Le relecteur note sur 100 : 30 points pour les tests, 25 pour la propreté du code, 20 pour la complexité, 15 pour le respect de l'architecture hexagonale, 10 pour les conventions. Sous 80, l'agent de refactoring prend le relais.
- Trois essais, pas un de plus. Pour chaque correction, l'agent de refactoring tente sa stratégie prévue, puis une approche alternative, puis le changement minimal sans risque. Si rien ne marche, il abandonne ce point et le signale : « Manual intervention required ». Une boucle sans fin coûte plus cher qu'un humain qui regarde.
Les skills que j'ai écrites
Chacune est née d'un besoin répété, ou d'une erreur que je ne voulais pas refaire.
| Skill | Projet | Ce qu'elle fait | Le détail qui compte |
|---|---|---|---|
| maintenance | tous | Réduire la dette technique en phases : réparer, mesurer, couvrir, auditer, refactorer | Commence par un passage dans un vrai navigateur : « Green is not working » |
| e2e | tous | Lancer, diagnostiquer et écrire des tests navigateur | Un tableau des causes de tests instables, et dix règles d'écriture |
| posthog-exclude-me | PostOwl | Retire mes propres sessions de toute requête d'analytics | Sur un produit jeune, mes visites écrasent celles des vrais utilisateurs |
| posthog-baselines | PostOwl | Compare chaque mesure à l'historique | Alerte si une métrique double ou se divise par deux ; une mesure stable est aussi consignée |
| blog-writer | PostOwl | Rédiger des articles SEO, du brief à l'article final | 48 règles, dont « cas réels uniquement » : jamais d'utilisateur ni de statistique inventés |
| prospection-message | Le Limier | Trouver une vraie cible dans les radars, puis écrire un premier message | « Un signal BODACC ne dit rien de la taille de l'entreprise. » |
| import-digest | Le Manoir du Butel | Intègre le digest mensuel d'événements dans l'agenda du site | Ne déploie jamais : il prépare, je publie |
Un point commun : ces skills disent autant ce qu'il ne faut pas faire que ce qu'il faut faire. La skill d'analytics, par exemple, contient une section sur ses propres limites : en dessous de 50 inscriptions par mois, un taux de conversion n'est pas statistiquement significatif, et il faut le dire.
Des garde-fous, pas seulement des aides
Certaines erreurs d'IA sont bénignes ; d'autres coûtent de l'argent. Pour celles-là, je préfère un mécanisme à une consigne.
- Sur le site du Manoir du Butel, chaque mise en production consomme des crédits d'hébergement. Un hook (un script qui s'exécute avant chaque commande de l'IA) bloque tout envoi de code sur la branche de production. Les autres branches, déployées en aperçu gratuit, passent librement.
- Sur PostOwl, la skill de déploiement classe les opérations en trois niveaux : sûres, à confirmer, interdites. Et elle rappelle qu'un tableau de bord à « 0 visiteur, 0 erreur » juste après un déploiement ne prouve pas que tout va bien.
- En maintenance, la commande qui pilote les sessions interdit explicitement de contourner les vérifications (
--no-verify) ou de sauter des tests pour obtenir un résultat vert.
Plusieurs agents en parallèle, chacun dans son worktree
Pour un gros chantier découpable, je lance plusieurs agents en même temps. Chacun travaille dans un worktree : une copie de travail séparée du dépôt Git, sur sa propre branche, pour que les agents ne se marchent pas dessus. Lors de la maintenance de PostOwl, jusqu'à dix agents ont tourné simultanément. Ça marche, mais pas tout seul :
ProblèmeDeux agents lancent les tests sur la même base
ParadeUne base de test par worktreeDB_DATABASE=testing_$(basename "$PWD")
ProblèmeUn agent réécrit le fichier au lieu de l'enrichir
Parade« Lis l'original sur main, sois additif »dans chaque brief d'agent
ProblèmeUn reboot coupe un agent en plein travail
ParadeLe worktree garde tout19 fichiers récupérés tels quels
Problème40 worktrees oubliés après la session
ParadeNettoyage en fin de chantiergit worktree remove, git branch -D
Le problème le plus sournois est le deuxième : un agent isolé dans sa copie a tendance à réécrire un fichier existant au lieu de l'enrichir, effaçant au passage le travail fusionné entre-temps. La parade tient en une phrase, ajoutée à chaque brief : lis la version actuelle sur la branche principale, et sois additif.
Sur Le Limier, la planification du MVP suivait la même logique : une première phase séquentielle (le schéma de données, dont tout dépend), puis cinq chantiers en parallèle, chacun en worktree, avec une validation de ma part avant chaque fusion.
Ce que j'en retiens
- Un agent vaut ce que vaut son brief. Périmètre, fichiers autorisés, critère de fin : plus c'est explicite, moins il improvise.
- Le contexte vieillit. Un fichier d'agent écrit il y a un an décrivait un domaine de 59 fichiers ; il en compte 229 aujourd'hui. Je relis et je mets à jour ces fichiers comme du code.
- Ce qui compte se vérifie par la machine. Une consigne est une intention ; un hook, un test ou une analyse statique est une garantie. Sur Le Limier, un test d'architecture bloque désormais toute dépendance interdite, ce que des mois de consignes aux agents n'avaient pas obtenu.
- La relecture reste humaine. Les agents produisent ; je décide de ce qui part en production.
C'est cette organisation qui me permet de livrer seul des projets comme Le Limier ou PostOwl, sans sacrifier les tests. Si vous voulez savoir ce qu'elle donnerait sur votre projet, parlons-en.
