Des règles aux résultats : ce que 22 000 étoiles pour un seul CLAUDE.md révèlent sur le développement assisté par IA

Le goulot d'étranglement dans le codage assisté par IA n'est pas la capacité du modèle. C'est la qualité du contrat comportemental entre l'humain et le LLM. Les équipes qui encodent ces contrats dans leur chaîne d'outils obtiennent des rendements cumulatifs. Celles qui ne le font pas continuent de soumettre les mêmes rapports de bugs sur « l'IA qui a encore halluciné ».

La preuve : forrestchang/andrej-karpathy-skills sur GitHub. Un seul fichier CLAUDE.md distillant 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 seul fichier.

Ce nombre d'étoiles ne reflète pas l'enthousiasme pour la notoriété personnelle de Karpathy. Ce sont 22 000 développeurs confirmant qu'ils partagent la même douleur : les assistants de codage par IA sont puissants mais imprévisibles, et un contrat comportemental bien rédigé y remédie.

Les quatre principes derrière 22 000 étoiles

Le dépôt encode quatre principes, chacun ciblant un mode d'échec spécifique dans le codage assisté par LLM :

• Réfléchir avant de coder. Exposer les hypothèses, présenter les compromis, demander plutôt que supposer. Cible le mode d'échec où les LLM plongent dans l'implémentation avant de comprendre le problème.

• La simplicité d'abord. Code minimal viable, sans fonctionnalités spéculatives ni abstractions. Cible le mode d'échec où les LLM sur-ingénient des solutions avec une complexité inutile.

• Exécution orientée objectifs. Spécifier des critères de succès, non des instructions étape par étape. Laisser le LLM itérer jusqu'à ce que les critères soient atteints. Cible le mode d'échec où des instructions impératives produisent un code fragile et trop littéral.

• Communication explicite. Aucune hypothèse silencieuse. Chaque décision documentée. Cible le mode d'échec où les LLM font des choix qui paraissent raisonnables mais violent des contraintes non formulées.

Aucun de ces principes n'est surprenant en soi. Ce qui est surprenant, c'est que les encoder dans un seul fichier fait la différence entre « l'IA m'a fait perdre mon après-midi » et « 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 spécifiques au projet. Cela passe complètement à 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 précisions plutôt que de faire des hypothèses, comment il délimite son travail, et ce qu'il vérifie avant de se déclarer terminé. 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 (remplissage 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 junior encyclopédique et surdoué » : une connaissance encyclopédique, aucun jugement. Le contrat comportemental fournit le jugement que le modèle n'a pas.

Ce changement de perspective a une conséquence concrète. Lorsque votre agent IA produit un résultat médiocre, la question n'est plus « le modèle est-il suffisamment bon ? » mais « le contrat est-il suffisamment précis ? ». Une question mène à attendre GPT-5. L'autre mène à une pull request que vous pouvez livrer aujourd'hui.

Faire passer les 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. Mais le même schéma passe à l'échelle de l'orchestration multi-agents, où des agents spécialisés se coordonnent sur des tâches complexes.

Nous utilisons 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, réviseur, auditeur de sécurité, ingénieur de test, et bien d'autres. Chaque agent dispose de son propre contrat comportemental définissant ses schémas de raisonnement, ses limites de périmètre et ses exigences de vérification.

La preuve de concept : une intégration produit complète (environ 25 000 lignes de code réparties sur 252 fichiers) générée entièrement à partir d'une spécification produit via le pipeline d'agents d'OMC. Aucune écriture manuelle de code. Les contrats comportementaux définis dans le prompt système de chaque agent constituaient la seule contribution humaine rédigée au-delà de la spécification elle-même.

Ce résultat ne tient pas au fait que le modèle soit suffisamment intelligent. Claude l'était déjà. Il tient au fait que les contrats soient suffisamment précis pour que 19 agents puissent se coordonner sans se gêner mutuellement.

Où se trouve vraiment l'avantage concurrentiel

Si l'infrastructure IA se banalise (et c'est le cas, avec des runtimes d'agents gérés désormais disponibles à 0,08 $ de l'heure de session), la question devient : où réside l'avantage concurrentiel durable ?

Nous pensons cela en termes d'une pile à cinq couches :

Les contrats comportementaux se situent à la couche orchestration. Ce n'est pas la couche avec l'avantage le plus élevé, mais c'est la couche où la plupart des équipes échouent actuellement. Maîtriser l'orchestration, c'est ce qui distingue « nous avons expérimenté le codage par IA » de « le codage par IA est notre façon de livrer ».

Les règles d'ingénierie produit orientée agents de PostHog le confirment côté produit. Leur cinquième règle (« traiter les agents comme de vrais utilisateurs ») est essentiellement le même constat : l'IA a besoin de contraintes explicites, testées et vérifiées, non de vagues intuitions.

Trois patterns à adopter

Si vous ne retenez qu'une chose du dépôt karpathy-skills, adoptez ces trois patterns pour votre propre équipe :

• Rédigez des critères de succès, non des instructions. Le principe d'exécution orientée objectifs de Karpathy fonctionne parce que les LLM sont plus efficaces pour itérer vers une cible mesurable que pour suivre des étapes procédurales. Définissez à quoi ressemble « terminé ». Laissez l'agent déterminer 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 à vous : relisez la sortie 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 en fonction des échecs observés. Le dépôt karpathy-skills lui-même en est la preuve : c'est un contrat comportemental versionné et revu par la communauté.

Les 22 000 étoiles ne vont pas aux conseils de codage de Karpathy. Elles vont à l'idée que la différence entre « une IA qui vous fait perdre votre temps » et « une IA qui livre vos fonctionnalités » tient à un fichier bien rédigé. Chez webvise, nous construisons sur cette idée chaque jour. Si vous souhaitez explorer ce que les contrats comportementaux et l'orchestration multi-agents pourraient apporter à votre workflow de développement, contactez-nous.