FND-005 : Culture de contribution : collaboration humaine, partenariat avec l’IA et croissance de l’équipe

À partir de v0.7.0 · Type : Culture · Rév. 2

Référence canonique · Ratifiée par l’équipe · Rév. 2 Discussion RFC originale : #5615

Une note à l’équipe avant que vous lisiez ceci.

Ceci est le cinquième document du cadre de maturité de ZeroClaw. Les quatre autres traitent de l’architecture, de la documentation, de la gouvernance et de l’infrastructure d’ingénierie, les couches structurelles qui font fonctionner un projet. Celui-ci aborde quelque chose que ces quatre documents tiennent pour acquis mais n’enseignent jamais explicitement : comment travailler ensemble.

Les outils et les processus décrits dans les autres RFC ne fonctionnent que dans la mesure où l’équipe qui les utilise est compétente. Un pipeline CI parfait n’aide pas une équipe incapable de fournir des retours honnêtes. Une architecture propre ne survit pas dans une équipe incapable de désaccorder de manière productive. Un modèle de gouvernance ne permet pas de développer un sens des responsabilités chez des personnes qui n’ont jamais appris ce que signifie l’appropriation.

Ce document porte sur la construction de cette équipe : pas seulement des individus techniquement compétents, mais des personnes qui savent donner et recevoir du feedback, demander de l’aide, utiliser des outils puissants de manière responsable et grandir ensemble au fil du temps. Ce sont des compétences qui s’apprennent. Personne n’arrive avec ces compétences pleinement développées. Ce document les nomme assez clairement pour que vous puissiez commencer à les pratiquer délibérément, ici, dans le contexte d’un travail réel qui compte.

Rien dans ce document ne constitue une critique de qui vous êtes ou de votre point de départ. C’est une carte pour nous montrer où nous cherchons à aller ensemble.

La suite du cadre de maturité

Ce RFC est le cinquième d’un ensemble de cinq documents qui forment ensemble le cadre de maturité de ZeroClaw. Ils sont conçus pour être lus dans leur ensemble, bien que chacun puisse être lu indépendamment.

Les quatre premiers RFC répondent à des questions structurelles. Celui-ci répond à une question humaine : étant donné la structure, comment les personnes qui y travaillent se comportent-elles les unes envers les autres et envers leurs outils ? Cette question ne dispose ni de compilateur, ni de linter, ni de contrôle CI. Elle repose uniquement sur les habitudes que nous construisons, les exemples que nous donnons et l’intentionnalité que nous y apportons.

Table des matières

1. Pourquoi ce document existe
2. Le travail avant le travail
3. Travailler avec des personnes
   • Donner un retour
   • Recevoir des commentaires
   • Demander de l’aide
   • Désaccord constructif
   • Propriété
   • Accompagner une personne en difficulté
4. Travailler avec l’IA
   • Le modèle mental de délégation
   • Le fonctionnement de l’IA se situe au niveau de l’implémentation
   • L’amplification n’est pas de la magie
   • La discipline de revue
   • Ce que cela signifie pour votre carrière
5. La taxonomie des retours
6. Une note à destination des relecteurs et mentors

Historique des révisions

1. Pourquoi ce document existe

La plupart des guides de contribution vous expliquent comment ouvrir une PR. Ils vous indiquent quels labels utiliser, comment exécuter la suite de tests et ce qui doit figurer dans le message de commit. Ces éléments sont importants, et nous disposons de documents qui les couvrent.

Ce document aborde un sujet différent : les compétences qui déterminent si un groupe de personnes talentueuses devient une équipe fonctionnelle ou une collection d’individus qui partagent simplement un dépôt.

Ce sont des compétences qui s’apprennent. Ce ne sont pas des traits de personnalité que l’on possède ou non. Ce ne sont pas des choses qui viennent automatiquement avec les compétences techniques. Elles se pratiquent, lentement, avec des retours, au fil du temps, de la même manière que toute autre compétence s’acquiert. La plupart des formations en génie logiciel se concentrent presque entièrement sur la couche technique et laissent la couche humaine au hasard. Le résultat est que beaucoup de personnes techniquement compétentes se retrouvent dans des équipes qui ne fonctionnent pas bien ensemble, sans comprendre clairement ce qui manque ni comment y remédier.

L’objectif de ce document est de nommer ces compétences de manière suffisamment claire pour que vous puissiez commencer à les pratiquer délibérément, ici, dans le contexte de travaux réels qui ont de l’importance.

2. Le travail avant le travail

Avant d’écrire une ligne de code, d’ouvrir une PR ou de demander à une IA de générer quoi que ce soit, il y a un ensemble de questions auxquelles vous devriez être capable de répondre. Ce projet utilise une hiérarchie de décision pour les décrire :

Vision
  └── Architecture
        └── Design
              └── Implementation
                    └── Testing
                          └── Documentation
                                └── Release

La hiérarchie est décrite en détail dans la RFC sur l’architecture (#5574). Ce qui compte ici, c’est le principe sous-jacent : chaque décision que vous prenez doit pouvoir être tracée jusqu’au sommet.

En pratique, cela signifie vous poser la question suivante avant de commencer à construire :

• Quel problème suis-je en train de résoudre ? Pas « quel ticket suis-je en train de fermer » : quel problème réel cela résout-il pour quelqu’un ?
• Cela s’intègre-t-il à l’architecture ? Si vous ne pouvez pas décrire où cela appartient dans la structure du système, vous ne comprenez pas encore suffisamment bien le système pour le modifier.
• À quoi ressemble le travail terminé ? Avant de commencer à écrire le code, rédigez les critères d’acceptation. « Ça marche » n’est pas un critère d’acceptation. « Un utilisateur peut installer un plugin sans chaîne d’outils Rust et celui-ci s’exécute correctement » en est un.
• Qui doit être informé de cela ? Les modifications qui touchent au travail d’autres personnes, ou qui impliquent des décisions que toute l’équipe devrait prendre, nécessitent une visibilité avant l’implémentation, pas après.

Il ne s’agit pas de bureaucratie. C’est la différence entre construire quelque chose et construire la bonne chose. Cela s’applique également directement à la manière dont vous travaillez avec des outils d’IA, que nous abordons dans la Section 4.

La version honnête de ce qui se passe quand vous sautez cette étape : vous construisez quelque chose qui fonctionne, vous ouvrez une PR, puis vous apprenez lors de la revue que cela résout le mauvais problème, ou que cela résout le bon problème d’une manière qui entre en conflit avec une décision déjà prise ailleurs. Cela fait perdre votre temps, le temps du relecteur, et retarde les personnes qui dépendent de ce travail. Le travail préalable n’est pas du superflu. C’est ainsi que vous protégez votre propre effort.

3. Travailler avec des personnes

Donner un retour

Les retours sont l’un des leviers les plus puissants que vous puissiez utiliser pour aider un autre ingénieur. Un commentaire de revue bien rédigé peut enseigner quelque chose qui prendrait des années à apprendre seul. Un commentaire mal rédigé peut décourager quelqu’un de contribuer à nouveau.

Soyez précis. Des commentaires vagues créent de l’anxiété sans offrir de direction.

❌ « C’est difficile à lire. »

✅ “Cette fonction gère trois préoccupations distinctes : la validation des entrées, la logique métier et le formatage de la réponse. Envisagez de les séparer afin que chaque fonction ne fasse qu’une seule chose. Cela facilite le test de chaque partie et permet de comprendre en un coup d’œil ce que fait chacune d’elles.”

La deuxième version est plus longue, mais elle enseigne quelque chose. Le lecteur sait maintenant quel est le problème, pourquoi il est important et quoi faire à ce sujet.

Expliquez le principe, pas seulement le verdict. Si vous demandez à quelqu’un de modifier quelque chose, expliquez-lui pourquoi. « Changez X en Y » produit une correction. « Changez X en Y parce que Z » produit une compréhension qui s’applique aux dix situations suivantes où le même principe est en jeu.

Séparez le travail de la personne. « Cette approche a un problème » et « vous avez fait une erreur » ne sont pas la même chose. La première concerne le code. La seconde concerne la personne. Gardez vos commentaires centrés sur le travail.

Nommez ce qui est bien. Il ne s’agit pas d’être gentil. Il s’agit d’être utile. Quand vous dites à quelqu’un ce qu’il a bien fait et expliquez pourquoi c’est bien, vous lui apprenez quels schémas reproduire. Les éloges génériques (« excellent travail ! ») n’enseignent rien. Les éloges spécifiques (« extraire ceci dans sa propre crate était la bonne décision, car cela signifie que nous pouvons désormais tester cette logique de manière isolée sans avoir à mettre en place toute la boucle de l’agent ») enseignent le principe et renforcent la décision.

Utilisez la taxonomie de feedback. La taxonomie de la Section 5 attribue à chaque commentaire un poids clair. Les relecteurs qui mélangent les problèmes bloquants avec des suggestions mineures sans les distinguer obligent l’auteur à deviner ce qui doit réellement être modifié. Ne forcez pas les gens à deviner.

Recevoir des commentaires

C’est plus difficile que de donner des commentaires pour la plupart des gens, et il est utile d’être honnête quant aux raisons.

Lorsque vous avez passé des heures sur quelque chose, à travailler sur un problème, à prendre des décisions, à écrire le code, et que quelqu’un vous dit que cela présente des problèmes, la réaction humaine naturelle est de ressentir la critique comme étant dirigée contre vous. Ce n’est pas le cas. Elle porte sur le travail. Apprendre à séparer ces deux choses est une compétence, et cela demande de la pratique.

Quelques éléments qui peuvent aider :

Lisez le retour avant d’y répondre. Pas seulement la ligne de résumé, mais tout le commentaire, y compris l’explication. De nombreuses réponses aux retours sont rédigées en réaction au verdict avant que la personne n’ait assimilé le raisonnement. Lisez le pourquoi avant de décider ce que vous pensez du quoi.

Distinguer entre « Je ne suis pas d’accord » et « Je ne comprends pas. » Ces situations nécessitent des réponses différentes. Si vous ne comprenez pas les commentaires, posez une question pour clarifier. Si vous les comprenez et que vous n’êtes pas d’accord, exprimez-le en apportant des preuves. Les deux sont des résultats positifs. Ce qui n’est pas utile, c’est de rester silencieux lorsque vous avez des questions, ou de dire « d’accord, tant pis » lorsque vous êtes en réalité en désaccord.

Vous n’êtes pas obligé d’être d’accord avec chaque retour pour en tirer des enseignements. Parfois, les retours sont erronés. Parfois, ils reflètent un ensemble de compromis différent de ceux que vous cherchiez à optimiser. Vous avez le droit d’exprimer votre désaccord. Voir Exprimer son désaccord de manière productive ci-dessous. Mais même un retour que vous finissez par rejeter mérite d’être pleinement compris avant que vous ne décidiez de le rejeter.

Bouclez la boucle. Lorsque quelqu’un prend le temps de relire votre travail, dites-lui quand vous avez pris en compte ses retours. Vous n’avez pas besoin de le remercier avec effusion. Un simple « pris en compte dans le dernier commit » suffit. Cela lui indique que son temps a été bien employé et permet de faire avancer la PR.

Les commentaires sur votre code ne sont pas un jugement de votre valeur. Cela semble évident. Mais ce n’est pas si évident quand on est en plein dedans. Chaque ingénieur expérimenté a eu son code examiné par des personnes plus expérimentées, et ce processus est inconfortable à chaque fois. L’inconfort est la sensation d’apprentissage. Il ne disparaît pas ; vous devenez simplement meilleur pour le supporter.

Demander de l’aide

À l’école, demander de l’aide peut donner l’impression d’admettre que vous êtes en retard ou que vous ne faites pas partie du groupe. En équipe, demander de l’aide est l’une des choses les plus professionnelles que vous puissiez faire.

Le coût de rester bloqué sans poser de questions est presque toujours supérieur au coût de poser des questions. Trois heures passées à tourner en rond sur un problème qui aurait pu être résolu en cinq minutes de discussion représentent trois heures de votre temps et de celui de votre équipe, qui sont perdus. Savoir quand poser des questions est une compétence, pas une faiblesse.

Une bonne demande d’aide comporte trois parties :

1. Ce que vous essayez de faire. Pas simplement « c’est cassé » : quel est l’objectif ?
2. Ce que vous avez déjà essayé. Cela montre que vous avez interagi avec le problème et donne à la personne qui vous aide un point de départ qui n’est pas nul.
3. Là où vous êtes bloqué spécifiquement. « Je ne sais pas ce qui ne va pas » est un problème différent de « Je sais ce qui ne va pas mais je ne sais pas comment le résoudre » et de « Je l’ai corrigé mais je ne sais pas pourquoi ma correction fonctionne. »

Une demande d’aide comportant ces trois composants reçoit une réponse plus rapide et vous permet d’en apprendre davantage, car la personne qui vous aide peut se calibrer précisément sur votre situation.

Posez vos questions publiquement quand vous le pouvez. Une question posée dans un canal partagé ou sur une PR profite à toutes les personnes qui se poseront la même question plus tard. Une question posée en privé ne profite qu’à vous. Il y a des moments où le privé est approprié, comme les retours sensibles ou les circonstances personnelles, mais les questions techniques sur le code sont presque toujours mieux posées ouvertement.

Ne pas savoir quelque chose n’est pas honteux. Personne ne sait tout. Les ingénieurs qui semblent tout savoir ont posé beaucoup de questions au fil du temps, et les réponses se sont accumulées. La seule façon d’y arriver est de commencer à poser des questions.

Désaccord constructif

Les désaccords sur l’architecture sont sains. Ils signifient que les personnes se soucient de la façon dont le système est construit et prêtent attention aux décisions prises. Une équipe où personne n’exprime de désaccord n’est pas une équipe où tout le monde est d’accord. C’est une équipe où les personnes ont cessé de s’impliquer.

La différence entre un désaccord productif et un désaccord improductif réside généralement dans le cadrage.

Commencez par l’inquiétude, pas par le verdict.

❌ « Cette approche est incorrecte. »

✅ « J’ai une préoccupation concernant cette approche : plus précisément, si nous connectons la passerelle directement au runtime ici, nous enfreignons la règle de dépendance du RFC §4.2. Pouvons-nous discuter de la possibilité d’obtenir le même résultat sans ce couplage ? »

La deuxième version ouvre une conversation. La première en ferme une.

Apportez des preuves. Un désaccord architectural étayé par un fait mesuré, une section spécifique d’un RFC ou un scénario d’échec concret constitue une contribution. Un désaccord architectural fondé sur « j’ai juste l’impression que » est une opinion. Les deux méritent d’être exprimés, mais seul le premier permet d’avancer rapidement dans la discussion.

Soyez sincèrement ouvert à l’idée d’avoir tort. Si vous abordez un désaccord en ayant déjà décidé que vous avez raison, vous n’avez pas une conversation. Vous faites du lobbying. Les gens font la différence, et cela les rend moins enclins à prendre vos préoccupations au sérieux. L’objectif est le meilleur résultat pour le projet, pas d’avoir raison.

Quand l’équipe décide, avancez avec l’équipe. Vous pouvez consigner votre désaccord officiellement : dans l’issue, dans les commentaires de la RFC, dans le fil de la PR, puis vous construisez ce qui a été décidé. Ce n’est pas une capitulation. C’est ainsi que fonctionnent les équipes. Une équipe qui remet sans cesse en question des décisions déjà tranchées ne livre pas.

Certaines décisions sont réversibles et d’autres non. Sachez de quel type vous parlez. Une décision de nommage est réversible. Une décision concernant un protocole de fil qui sera dans les binaires de production pendant deux ans ne l’est pas. Pesez votre énergie en conséquence.

Propriété

La propriété est l’un de ces mots qui est souvent utilisé sans définition claire. Voici ce que cela signifie en pratique sur ce projet :

L’appropriation signifie que vous voyez le problème avant qu’on ne vous le demande. Cela signifie lire une PR qui touche votre domaine et remarquer un effet secondaire que l’auteur n’a pas vu. Cela signifie voir un problème suivant sans assigné et le prendre en charge. Cela signifie ne pas attendre qu’on vous le dise.

L’appropriation signifie que votre parole a de la valeur. Si vous créez un ticket de suivi avec votre nom dessus, ce ticket est votre engagement. Pas « quelqu’un devrait faire ça » : vous le ferez. Si les circonstances changent et que vous ne le pouvez pas, vous le dites tôt et vous trouvez une passation. Un outil de suivi rempli de tickets créés puis oubliés avec des noms attachés est un registre de confiance brisée.

L’appropriation n’est pas “j’ai fait ma part”. C’est “je me soucie de savoir si l’ensemble fonctionne”. Vous pouvez être propriétaire d’un crate sans être indifférent à la santé du système dans lequel ce crate s’inscrit. Vous pouvez être propriétaire d’une fonctionnalité sans être indifférent au fait que les utilisateurs puissent réellement l’utiliser. Une appropriation étroite, “j’ai fait mon bout, le reste est le problème de quelqu’un d’autre”, produit des systèmes qui ont techniquement des propriétaires pour chaque pièce et fonctionnellement personne de responsable de quoi que ce soit.

La propriété inclut le suivi. Livrer du code n’est pas la fin de la propriété. C’est le début de la responsabilité de s’assurer que cela fonctionne, de corriger ce qui casse, et d’enseigner à la prochaine personne qui travaillera dans ce domaine ce que vous avez appris.

Accompagner une personne qui traverse une période difficile

À un moment donné de ce projet, vous serez plus expérimenté qu’une autre personne dans un fil de discussion. Peut-être que vous êtes ici depuis plus longtemps. Peut-être que vous connaissez la partie du codebase dans laquelle ils travaillent. Peut-être que vous avez déjà vu ce mode d’échec particulier.

Ce que vous faites avec ce poste compte.

Ne vous contentez pas de corriger le problème pour eux. Fournir une solution fonctionnelle sans expliquer ce qui ne va pas ou pourquoi votre correction fonctionne aboutit à une PR fusionnée, mais à aucun apprentissage. La prochaine fois qu’ils rencontreront un problème similaire, ils se retrouveront dans la même situation. Prenez les cinq minutes supplémentaires nécessaires pour expliquer ce que vous avez observé et pourquoi la correction fonctionne.

Relire avec l’intention d’enseigner. Une mauvaise PR n’est pas seulement un problème à clore. C’est une occasion d’enseigner. Une revue expéditive (« cela ne respecte pas l’architecture ») est moins utile qu’une revue qui nomme ce qui a été manqué, explique le principe enfreint et indique où le contributeur peut en apprendre davantage. Cet effort supplémentaire est un investissement dans un contributeur qui écrira de meilleures PR à partir de ce moment-là.

Si quelqu’un est bloqué et ne demande pas d’aide, dites quelque chose. Parfois, les gens ne demandent pas parce qu’ils ne veulent pas donner l’impression d’être en difficulté. Parfois, ils ne savent pas à qui demander. Parfois, ils sont en difficulté depuis si longtemps qu’ils ont cessé de remarquer à quel point ils sont coincés. Un discret « on dirait que celui-ci est ouvert depuis un moment. y a-t-il quelque chose que je puisse aider à débloquer ? » ne coûte presque rien et peut tout changer pour quelqu’un qui tourne en rond.

Rendez-le sûr de ne pas savoir des choses. Si les membres de votre équipe se sentent jugés pour ne pas savoir quelque chose, ils feront semblant de savoir. Cela conduit à de moins bonnes décisions, pas à de meilleures. L’équipe qui rend possible de dire « Je ne sais pas, laissez-moi chercher » prend de meilleures décisions que celle où tout le monde affiche une confiance feinte.

4. Travailler avec l’IA

Cette section aborde un sujet que la plupart des guides de contribution ne couvrent pas : comment utiliser les outils de codage avec l’IA de manière à vous rendre meilleur, et non simplement plus rapide.

Le modèle mental de délégation

Voici le cadre le plus utile pour travailler efficacement avec l’IA :

Travailler avec une IA est la même compétence que de déléguer à une personne.

Lorsque vous déléguez une tâche à un collègue ou à un ingénieur junior, vous fournissez du contexte. Vous expliquez l’objectif, les contraintes, ce qui constitue un bon résultat et les limites à respecter. Vous ne vous contentez pas de dire « développe-moi une fonctionnalité ». Vous précisez : voici ce que l’utilisateur cherche à faire, voici comment cela s’intègre dans le système, voici comment nous saurons que le travail est terminé, et voici les éléments qu’il ne faut pas faire.

Ensuite, et c’est essentiel, vous examinez de manière critique ce qui vous est renvoyé. Vous n’acceptez pas la PR d’un ingénieur junior sans la lire. Vous vérifiez si elle fait ce qui a été demandé, si elle s’intègre à l’architecture, si elle dispose d’une couverture de tests, si la gestion des erreurs est correcte. Vous donnez du feedback. Vous pouvez itérer.

Les outils d’IA fonctionnent exactement de la même manière. La qualité du résultat obtenu dépend presque entièrement de la qualité de ce qui est fourni en entrée. Une requête vague produit un résultat vague. Une requête avec un contexte clair, des contraintes spécifiques et des critères d’acceptation concrets produit un résultat réellement utile comme point de départ.

Les ingénieurs qui peinent avec les outils d’IA sont généralement ceux qui apprennent encore à donner des directives claires à quiconque : humain ou IA. Les ingénieurs qui s’épanouissent avec ces outils sont ceux qui savent déjà ce qu’ils veulent avant de le demander.

Ce modèle mental signifie également que la sortie est votre responsabilité. Vous ne pouvez pas soumettre une PR et dire « l’IA l’a écrite ». Vous l’avez revue. Vous avez ouvert la PR. C’est votre travail.

L’IA fonctionne au niveau de l’implémentation.

C’est la limitation technique la plus importante à comprendre.

La génération de code par l’IA fonctionne à la couche d’implémentation de la hiérarchie des décisions :

Vision          ← AI cannot set this. You must.
Architecture    ← AI cannot make these decisions. You must.
Design          ← AI will sometimes guess. You must verify.
Implementation  ← AI can help here.
Testing         ← AI can help, but you define what to test.
Documentation   ← AI can draft. You must review for accuracy.
Release         ← Human judgment required.

Un outil d’IA générera une fonction qui fait ce que vous avez décrit. Il ne vous dira pas si cette fonction appartient à ce crate ou à un autre. Il ne signalera pas que l’approche contredit une décision architecturale prise il y a trois mois. Il ne vous demandera pas si vous avez bien réfléchi aux implications en matière de sécurité. Il ne remarquera pas que vous résolvez le mauvais problème.

ZeroClaw lui-même est un exemple utile. La base de code initiale a été amorcée avec l’assistance de l’IA. Le résultat, tel que le décrit la RFC d’architecture, est « impressionnant de fonctionnalité mais architecturalement accidentel ». Le code fait ce qu’il doit faire aujourd’hui, mais il n’a pas été conçu, il s’est accumulé. Ce n’est pas un échec des outils d’IA. C’est le résultat prévisible de l’utilisation d’outils de la couche d’implémentation sans avoir d’abord effectué le travail de vision, d’architecture et de conception qui donne sa direction à l’implémentation.

La solution n’est pas d’utiliser moins l’IA. Il s’agit de faire vous-même le travail de haut niveau de la hiérarchie, toujours, avant de demander à l’IA de construire quoi que ce soit.

L’amplification n’est pas de la magie.

Les outils d’IA amplifient vos capacités existantes. C’est la description honnête de ce qu’ils font.

Si vous avez une vision claire, une architecture définie, des critères de qualité que vous pouvez exprimer et la capacité d’évaluer les résultats avec un regard critique, l’IA est un véritable multiplicateur de force. Vous avancez plus vite. Vous explorez plus d’options. Vous écrivez plus de tests. Vous rédigez plus de documentation.

Si vous n’avez pas ces éléments. L’IA génère beaucoup de code qui semble convaincant mais qui ne tient pas la route. Elle génère des tests qui passent sans rien tester de significatif. Elle génère de la documentation qui décrit le code mais pas l’intention. Elle génère une architecture localement cohérente et globalement incohérente.

L’amplification est neutre. Elle amplifie les entrées positives et négatives avec la même intensité.

Cela signifie que la compétence la plus précieuse dans un flux de travail assisté par l’IA n’est pas l’ingénierie des prompts. C’est la capacité d’évaluer la sortie. Cela nécessite de savoir ce qui constitue une bonne sortie avant de demander quoi que ce soit. Ce qui vous ramène, à chaque fois, au sommet de la hiérarchie des décisions.

Un auto-vérification utile avant d’utiliser un outil d’IA pour implémenter quelque chose :

• Puis-je décrire le problème en une phrase sans mentionner les détails d’implémentation ?
• Puis-je nommer la section de la RFC ou la décision de conception que cette implémentation sert ?
• Puis-je décrire à quoi ressemble une implémentation correcte avant d’en voir une ?
• Puis-je expliquer pourquoi une implémentation générée est correcte ou incorrecte après en avoir vu une ?

Si la réponse à l’une de ces questions est non, vous n’êtes pas encore prêt à procéder à l’implémentation. Vous êtes toujours en phase de conception.

La discipline de révision

Le code généré par l’IA nécessite la même rigueur de revue que le code écrit par des humains. Dans certains cas, il en exige davantage, car la surface des problèmes à vérifier est plus large.

Lorsque vous examinez une sortie générée par l’IA, qu’elle soit la vôtre ou celle de quelqu’un d’autre, vérifiez les points suivants :

Adéquation architecturale. Cela respecte-t-il les règles de dépendance ? Ce code vit-il dans le bon crate ? Introduit-il un couplage que la conception évite explicitement ?

Précision aux limites. Les modèles d’IA sont très performants dans le cas courant et souvent erronés dans les cas limites. Vérifiez ce qui se passe lorsque les entrées sont vides, nulles, malformées ou à la taille maximale attendue. Vérifiez ce qui se passe lorsqu’une dépendance est indisponible.

Implications en matière de sécurité. Les outils d’IA n’ont pas par défaut une approche axée sur la sécurité. Ils généreront du code qui accepte des entrées utilisateur sans validation, qui consigne des valeurs sensibles, qui utilise des primitives cryptographiques obsolètes, qui ouvre des chemins de fichiers sans les vérifier. Vous devez explicitement adopter une perspective de sécurité.

Qualité des tests. Les tests générés par IA testent fréquemment l’implémentation plutôt que le comportement. Un test qui vérifie qu’une fonction renvoie une valeur de struct interne spécifique n’est pas un test de comportement. C’est un instantané de l’implémentation qui échouera dès que l’implémentation changera. Posez-vous la question : ce test vérifie-t-il que le système fait ce dont l’utilisateur ou l’appelant a besoin, ou vérifie-t-il que le code fait ce qu’il fait actuellement ?

Exhaustivité. Les outils d’IA optimisent pour une complaisance plausible. Ils généreront du code qui gère en profondeur le cas nominal et superficiellement le cas d’erreur. Vérifiez que les erreurs sont propagées, gérées ou exposées d’une manière réellement utile pour l’appelant.

Ce que cela signifie pour votre carrière

Les compétences décrites ici : donner des directives clairement, évaluer les résultats de manière critique, comprendre où un composant s’intègre dans un système plus vaste, savoir à quoi ressemble un bon résultat avant de construire, ne sont pas des compétences spécifiques à l’IA. Ce sont les compétences qui font de quelqu’un un ingénieur efficace, un tech lead efficace, et finalement un responsable d’ingénierie efficace.

Les ingénieurs qui seront les plus précieux dans un monde saturé de code généré par l’IA ne sont pas ceux qui peuvent écrire le plus de code le plus rapidement. Ce sont ceux qui peuvent déterminer si le code est correct. Cela nécessite une pensée systémique, un jugement architectural et la capacité d’évaluer le travail par rapport à un standard que vous avez intériorisé.

Tout ce que vous pratiquez ici : comprendre la RFC avant de l’implémenter, demander « pourquoi » avant de construire, relire la sortie de l’IA avec le même regard que vous porteriez sur la PR d’un ingénieur junior, est un entraînement à ce type de jugement. Cela se cumule. Chaque PR où vous vous engagez sérieusement dans l’architecture est un point de données qui facilite la prochaine décision architecturale.

Les contributeurs de ce projet ont un avantage inhabituel : vous développez ces habitudes sur un système réel, avec des contraintes architecturales réelles, et avec des personnes qui examineront votre travail et vous expliqueront pourquoi. Cette combinaison est rare. Il est important de prendre cela au sérieux.

5. La taxonomie des retours

Chaque commentaire de revue sur ce projet porte un poids explicite. L’utilisation cohérente de ces poids permet aux relecteurs de communiquer clairement et aux auteurs de savoir exactement ce qui nécessite une action.

Les catégories ci-dessous décrivent l’intention de revue du projet. Les revues de PR traduisent cette intention via les titres emoji du protocole de revue : 🔴 bloquant, 🟡 avertissement, 🔵 suggestion, 🟢 félicitations, et ✅ résolu. Consultez docs/book/src/contributing/pr-review-protocol.md pour le format exact de revue de PR.

✅ Félicitations

Un point que l’auteur a bien saisi, nommé spécifiquement et expliqué afin que le pattern soit réutilisé.

Il ne s’agit pas de politesse. Les éloges génériques (« bon travail ! ») n’enseignent rien. Des éloges précis accompagnés d’une explication permettent de comprendre le principe sous-jacent à ce qui a été bien fait, ce qui s’applique à chaque décision future dans la même catégorie.

Les félicitations ne nécessitent aucune action. Leur but est de renforcer.

Exemple : « Extraire l’analyseur d’appels d’outils dans son propre crate était la bonne décision : ce code n’a aucune dépendance à l’état de l’agent et est désormais testable de manière indépendante. Les 91 tests que vous avez ajoutés constituent exactement le type de couverture qu’il serait impossible d’atteindre lorsque cette logique résidait dans loop_.rs. »

🔴 Blocage

Un élément qui doit être résolu avant la fusion de la PR. Les éléments bloquants se divisent en deux catégories :

• Violations architecturales : code qui franchit une limite de dépendance explicitement interdite par la conception, ou qui contredit une décision enregistrée dans une RFC ou un ADR.
• Régressions de qualité : manque de couverture de test pour un nouveau comportement, problèmes de sécurité, rupture de compatibilité du contrat ou code introduisant un défaut.

Un commentaire bloquant explique en quoi consiste le problème, pourquoi il est important et, dans la mesure du possible, à quoi ressemble une voie de résolution. Un commentaire bloquant n’est pas un jugement porté sur l’auteur. C’est la responsabilité du relecteur envers la base de code et les utilisateurs qui en dépendent.

Les auteurs ne doivent pas interpréter un commentaire bloquant comme un rejet. Il s’agit d’un problème spécifique et résoluble. Corrigez-le et passez à la suite.

🟡 Conditionnel

Un élément acceptable à reporter, mais uniquement avec un problème suivi et un assigné. Un élément conditionnel est ce que dit le réviseur : Je fais confiance au fait que cela sera traité, mais j’ai besoin de cet engagement consigné avant que nous fusionions.

La distinction entre bloquant et conditionnel repose souvent sur le timing et le risque. Une fonctionnalité manquante qui sera livrée dans le prochain PR est conditionnelle. Une fonctionnalité manquante qui crée une faille de sécurité est bloquante.

Un report conditionnel sans responsable n’est pas un report. C’est un vœu. Les tickets suivis sans propriétaire ont tendance à rester ouverts indéfiniment. Lorsqu’un relecteur marque quelque chose comme conditionnel, il demande un engagement nominatif, pas une intention future théorique.

🔵 Décision de l’équipe

Une question soulevée par la PR à laquelle aucun relecteur ou auteur ne devrait répondre unilatéralement. Les décisions d’équipe impliquent des compromis qui affectent la direction du projet, son architecture ou ses utilisateurs, et elles appartiennent au groupe.

L’utilisation de cette étiquette permet aux relecteurs d’éviter de retarder les contributeurs individuels avec des questions qui relèvent en réalité d’une orientation commune. Elle met en évidence la décision, présente les compromis et invite l’équipe à donner son avis, sans donner à l’auteur l’impression que sa PR est bloquée par quelque chose qui échappe à son contrôle.

Les décisions de l’équipe doivent être prises dans le fil de la PR, de manière traçable, par les personnes qui doivent assumer la responsabilité du résultat. Une décision prise dans une conversation parallèle qui n’apparaît pas dans le fil de la PR n’existe pas pour quiconque lira l’historique ultérieurement.

6. Une note pour les réviseurs et les mentors

Si vous êtes en position de réviser le travail de quelqu’un d’autre, que ce soit en tant que propriétaire du code, contributeur plus expérimenté, ou simplement quelqu’un qui est là depuis plus longtemps, cette section est pour vous.

Vous modélisez ce à quoi ressemble la collaboration. Chaque revue que vous rédigez apprend à l’auteur comment faire une revue. Chaque question que vous posez dans un fil de discussion de PR apprend aux nouveaux contributeurs quelles questions méritent d’être posées. Vous ne pouvez pas vous y soustraire : le seul choix est de le faire intentionnellement ou accidentellement.

La rigueur est une marque de respect. Une revue approfondie qui explique son raisonnement est plus respectueuse du travail de l’auteur qu’une approbation rapide. L’auteur a consacré du temps à son travail. Il mérite de comprendre pourquoi il est ou n’est pas prêt à être fusionné, et ce qu’il peut retenir de cette interaction.

L’objectif de chaque interaction de revue est de laisser l’auteur mieux outillé qu’il ne l’était auparavant. Pas seulement de produire une PR fusionnée. Pas de démontrer vos propres connaissances. Pas d’imposer des règles. De laisser à l’auteur quelque chose qu’il peut utiliser : un principe, un modèle, une compréhension d’un compromis, qui s’applique au-delà de la PR immédiate.

Nommez le motif, pas seulement l’instance. Lorsque vous demandez une modification, expliquez le principe qui la sous-tend. « Renommez cette variable avec un nom qui décrit ce qu’elle contient » est moins utile que « les noms de variables doivent décrire leur rôle du point de vue de l’appelant, pas de celui de l’implémentation : qu’est-ce que l’appelant de cette fonction se soucie réellement que cette valeur représente ? » La seconde version s’applique à chaque variable de chaque fonction que l’auteur écrira un jour.

Soyez honnête sur ce qui relève de votre préférence et ce qui relève d’une exigence. « J’aurais écrit cela différemment » n’est pas la même chose que « cela doit changer ». Si vous exprimez une préférence, dites-le. Si vous invoquez une exigence stricte : architecture, sécurité, compatibilité, citez la raison précise. Les auteurs qui ne savent pas faire la différence entre une préférence du relecteur et une nécessité architecturale changeront soit tout, soit rien. Aucune de ces deux options ne leur rend service.

L’équipe que vous aidez à construire est celle dans laquelle vous travaillerez. L’investissement que vous faites dans une revue attentive et éducative aujourd’hui se traduit par un contributeur qui écrit un meilleur code, ouvre de meilleures PR et examine les contributions des autres avec plus de réflexion. Cela améliore le projet. Cela facilite également votre propre travail, car les personnes qui vous entourent progressent.

Ce n’est pas une compétence relationnelle. C’est du travail d’ingénierie.