Le développement assisté par IA déraille lorsque le contrat comportemental entre l'humain et le LLM reste vague. Les équipes qui formalisent ces contrats dans leur chaîne d'outils obtiennent des gains cumulatifs. Celles qui font l'impasse multiplient les rapports de bugs sur des sorties hallucinées.
La preuve : forrestchang/andrej-karpathy-skills sur GitHub. Un seul fichier CLAUDE.md condensant les observations d'Andrej Karpathy sur les pièges du codage par LLM en règles actionnables pour Claude Code. 22 700 étoiles. 1 800 forks. Pour un fichier.
Ce score confirme que 22 000 développeurs partagent la même douleur : les assistants de codage IA sont puissants mais imprévisibles, et un contrat comportemental bien rédigé y remédie (les étoiles mesurent la visibilité, pas des résultats vérifiés).
Les quatre principes derrière 22 000 étoiles
Le dépôt formalise quatre principes, chacun ciblant un mode de défaillance précis dans le codage assisté par LLM :
- Réfléchir avant de coder. Formuler les hypothèses, présenter les compromis, demander plutôt que supposer. Cible le mode de défaillance où le LLM commence à implémenter avant de comprendre le problème.
- La simplicité d'abord. Code minimal viable, sans fonctionnalités spéculatives ni abstractions. Cible le mode de défaillance où le LLM sur-ingénierise des solutions inutilement complexes.
- Exécution orientée objectif. Définir les critères de succès, non les instructions pas à pas. Laisser le LLM itérer jusqu'à ce que les critères soient atteints. Cible le mode de défaillance où des instructions impératives produisent un code rigide et trop littéral.
- Communication explicite. Aucune hypothèse silencieuse. Chaque décision documentée. Cible le mode de défaillance où le LLM fait des choix qui semblent raisonnables mais violent des contraintes non exprimées.
Aucun de ces principes n'est surprenant en soi. Ce qui l'est, c'est qu'en les consignant dans un seul fichier, on passe de « l'IA m'a fait perdre mon après-midi » à « l'IA a livré la fonctionnalité pendant que je relisais ».
CLAUDE.md n'est pas un guide de style
La plupart des équipes traitent leur CLAUDE.md (ou fichier de prompt système équivalent) comme un guide de style de code : préférences de formatage, conventions de nommage, peut-être quelques notes propres au projet. C'est passer entièrement à côté du sujet.
Un CLAUDE.md est un contrat comportemental. Il définit comment l'agent IA raisonne sur les problèmes, quand il demande des éclaircissements plutôt que de formuler des hypothèses, comment il délimite le travail, et ce qu'il vérifie avant de déclarer une tâche terminée. Les guides de style indiquent à l'IA à quoi doit ressembler le code. Les contrats comportementaux lui indiquent comment penser.
Le propre workflow de codage assisté par IA de Karpathy le confirme. Sa boucle (injection de contexte, description du changement, choix d'une approche, relecture, test, commit, répétition) traite l'IA comme ce qu'il appelle un « stagiaire prodige surdoué » : savoir encyclopédique, jugement nul. Le contrat comportemental fournit le jugement que le modèle ne possède pas.
Cette reformulation a une conséquence concrète. Lorsque l'agent IA produit un résultat médiocre, la question passe de « le modèle est-il suffisamment bon ? » à « le contrat est-il suffisamment précis ? ». La première mène à attendre GPT-5. La seconde mène à une pull request livrable aujourd'hui.
Passer des contrats comportementaux à l'échelle des systèmes multi-agents
Les principes de Karpathy ont été conçus pour un développeur solo travaillant avec un seul assistant IA. Le même schéma s'étend toutefois à l'orchestration multi-agents, où des agents spécialisés coordonnent des tâches complexes.
J'utilise oh-my-claudecode (OMC), une couche d'orchestration multi-agents open source pour Claude Code, pour coordonner 19 sous-agents spécialisés : architecte, exécuteur, relecteur, auditeur sécurité, ingénieur de test, et d'autres encore. Chaque agent dispose de son propre contrat comportemental définissant ses schémas de raisonnement, ses périmètres d'action et ses exigences de vérification.
| Dimension | Contrat mono-agent | Contrat multi-agents |
|---|---|---|
| Périmètre | Un développeur, un assistant | 19 agents spécialisés aux rôles distincts |
| Vérification | L'humain relit la sortie de l'IA | L'agent relecteur contrôle l'exécuteur ; l'humain relit le résultat final |
| Contexte | L'intégralité du code en une seule fenêtre | Chaque agent reçoit uniquement le contexte pertinent pour sa tâche |
| Mode de défaillance | L'IA complique un seul fichier à l'excès | Les agents dupliquent le travail ou se contredisent |
| Priorité du contrat | Comment raisonner sur ce code | Qui est propriétaire de quelles décisions et comment fonctionnent les transferts |
La preuve de concept : une intégration produit complète générée à partir d'une spécification via le pipeline d'agents OMC. La leçon essentielle portait sur le contrôle qualité, pas sur le nombre de lignes. Les contrats comportementaux définis dans le prompt système de chaque agent constituaient la principale contribution humaine rédigée au-delà de la spécification elle-même.
Claude était déjà suffisamment performant. Les contrats étaient suffisamment précis pour que les 19 agents coordonnent leur travail sans écraser celui des autres.
Là où se trouve le véritable avantage concurrentiel
Si l'infrastructure IA se banalise, et c'est bien le cas avec des runtimes d'agents managés désormais disponibles à 0,08 $ de l'heure de session, la question devient : où réside l'avantage concurrentiel durable ?
Une grille d'analyse en cinq couches permet d'y répondre :
| Couche | Fonction | Défendabilité |
|---|---|---|
| Infrastructure | Hébergement des modèles, sandboxing, persistance | Faible. Banalisée. Nombreux fournisseurs. |
| Orchestration | Coordination multi-agents, contrats comportementaux | Moyenne. Nécessite un savoir-faire accumulé. |
| Règles de conception | Ingénierie produit orientée agents | Moyenne à élevée. Nécessite une expertise métier. |
| Thèse produit | Ce qu'il faut construire et pour qui | Élevée. Nécessite une connaissance du marché. |
| Modèle économique | Comment le travail génère des revenus | Maximale. Nécessite des relations clients. |
Les contrats comportementaux se situent à la couche orchestration. C'est précisément là que la plupart des équipes échouent actuellement. Maîtriser l'orchestration, c'est ce qui sépare « nous avons expérimenté le codage IA » de « le codage IA est notre mode de livraison ».
Les règles d'ingénierie produit orientée agents de PostHog confirment cela côté produit. Leur cinquième règle (« traiter les agents comme de vrais utilisateurs ») est fondamentalement le même constat : l'IA a besoin de contraintes explicites, testées et vérifiées, pas d'approximations.
Trois schémas à adopter
Si vous ne retenez qu'une chose du dépôt karpathy-skills, adoptez ces trois schémas pour votre équipe :
- Rédigez des critères de succès, pas des instructions. Le principe d'exécution orientée objectif de Karpathy fonctionne parce que les LLM itèrent mieux vers une cible mesurable qu'en suivant des étapes procédurales. Définissez à quoi ressemble « terminé ». Laissez l'agent trouver comment y parvenir.
- Séparez la rédaction de la relecture. Dans les systèmes multi-agents, l'agent qui écrit le code ne doit jamais être celui qui l'approuve. Dans les workflows mono-agent, le même principe s'applique : relisez les sorties de l'IA avec la même rigueur que vous appliqueriez à la pull request d'un développeur junior.
- Versionnez vos contrats comme du code. Votre CLAUDE.md, vos prompts système et vos définitions d'agents sont des artefacts de production. Ils appartiennent au contrôle de version, méritent une revue de code et doivent évoluer à partir des défaillances observées. Le dépôt karpathy-skills lui-même en est la preuve : c'est un contrat comportemental versionné et relu par une communauté.
Les 22 000 étoiles suggèrent que l'écart entre des outils IA qui produisent du bruit et ceux qui livrent des fonctionnalités exploitables tient souvent à un fichier de contrats bien rédigé. webvise s'appuie sur cette conviction au quotidien. Pour explorer ce que les contrats comportementaux et l'orchestration multi-agents pourraient apporter à votre workflow de développement, prenez contact.
Les pratiques de webvise sont alignées sur les normes ISO 27001 et ISO 42001.