Note de l’auteur : en s’appuyant sur les notions de « capitulation cognitive » et de « dette de compréhension » d’Addy Osmani, cet article propose une liste de vérification avant la fusion d’une PR et des modèles d’invites. Il les compare aussi à l’approche de LobeHub, fondée sur les rapports de validation des dépendances, pour vous aider à choisir le niveau de revue adapté au risque.
Si vous utilisez Claude Code, Cursor ou Cline tous les jours pour livrer du code, cette situation vous est peut-être familière : un agent produit en quelques minutes une PR de plusieurs centaines de lignes. Les noms respectent les conventions, la structure est claire, les tests passent tous au vert : vous cliquez donc sur « approuver ». Quelques semaines plus tard, quelqu’un vous demande pourquoi cette logique a été écrite ainsi, et vous ne savez pas quoi répondre. Cet article propose des vérifications concrètes, comme demander à l’IA de vous poser des questions, pour rester responsable de chaque modification approuvée sans devoir tout examiner ligne par ligne.
Cet article ne cherche pas à vous convaincre de revenir au code écrit à la main. Addy Osmani, ingénieur Claude Code, le dit lui-même clairement : personne ne demande aux ingénieurs de mémoriser toute la base de code. La question n’est pas de lire ou non chaque ligne, mais de savoir ce que vous comprenez et ce que vous ne comprenez pas.
Ce que vous allez en retirer : vous comprendrez la progression entre « décharge cognitive », « délégation du jugement » et « capitulation cognitive ». Vous disposerez aussi d’une liste de questions et de modèles d’invites à copier avant la fusion, et saurez adapter l’intensité de la revue au risque associé aux modifications.
Ne validez pas aveuglément le travail des agents : l’essentiel sur la dette de compréhension
Selon QbitAI, cité par 36氪, Addy Osmani, ancien ingénieur chez Google et aujourd’hui impliqué dans le développement de Claude Code, a soulevé un problème préoccupant : plus les productions de l’IA sont fiables, moins les humains les vérifient attentivement. Il décrit plusieurs étapes de ce processus et présente deux nouveaux types de « dette ». Précisons que les concepts ci-dessous proviennent d’un compte rendu médiatique ; pour connaître ses termes exacts, reportez-vous au texte original d’Addy.
| Concept | Signification | Exemple typique |
|---|---|---|
| Décharge cognitive | Confier une tâche précise à l’IA tout en continuant à la comprendre et à pouvoir juger le résultat | Demander à un agent d’écrire du code standard tout en sachant ce qu’il fait |
| Délégation du jugement | Les réponses de l’IA deviennent peu à peu la base par défaut du travail suivant | À la deuxième vérification, on survole le résultat et on poursuit selon les indications de l’agent |
| Abandon cognitif | Confier à l’IA même les jugements qu’on devrait porter soi-même | « Si l’IA le dit, c’est sûrement justifié » : tous les tests passent, on fusionne directement |
| Dette de compréhension | La complexité du code et du système augmente, mais la compréhension des développeurs ne suit pas | Au moment de modifier une fonctionnalité, personne ne maîtrise vraiment la structure interne |
| Dette d’intention | L’IA décide à votre place des objectifs, contraintes et compromis mal définis dans les exigences | On ne sait pas clairement ce qu’on veut, mais l’agent livre tout de même un résultat convaincant |
Comment s’installent l’abandon cognitif et la dette de compréhension
L’abandon cognitif ne se produit pas du jour au lendemain. Au départ, vous vous contentez de « décharger » un travail précis, ce qui n’a rien de problématique en soi : c’est comme utiliser un compilateur au lieu d’écrire de l’assembleur à la main. Le danger apparaît à la deuxième étape : après plusieurs résultats fiables, les conclusions de l’agent deviennent discrètement vos hypothèses par défaut et vous commencez à sauter les vérifications. À la troisième étape, le bouton « Approuver » devient un simple tampon : d’ingénieur, vous passez à valideur automatique.
Addy donne un exemple parlant : un agent soumet d’un coup 600 lignes de code, bien structurées et dont les tests passent. Le développeur les fusionne en confiance. Mais l’agent a peut-être modifié l’ordre de traitement des transactions à un endroit peu visible, ou ajusté un cas limite. Ces changements ne provoquent pas d’erreur sur le moment. Ce n’est que lorsqu’un problème survient réellement que le développeur découvre qu’il ne sait pas expliquer pourquoi le code fonctionne ainsi. Ce sont les « intérêts » de la dette de compréhension, et ils arrivent toujours à échéance au pire moment.
La dette d’intention apparaît plus en amont. Les agents sont aujourd’hui très doués pour compléter les exigences : même si vous n’avez pas tout clarifié, ils peuvent livrer un résultat qui semble tout à fait cohérent. Le problème, c’est que l’IA a discrètement tranché à votre place les objectifs, le périmètre et les compromis que vous n’aviez pas précisés. Les deux dettes s’accumulent souvent : vous ne savez pas clairement ce que vous vouliez au départ, ni ce que l’agent a finalement réalisé.
6 méthodes pour rembourser la dette de compréhension
Dans son article, Addy partage de nombreux conseils pratiques. Voici six méthodes, avec le type de dette qu’elles permettent de réduire et le moment où les utiliser dans le flux de travail.
| Méthode | Quand l’utiliser | Dette principalement réduite | Action en bref |
|---|---|---|---|
| 1. Demander à l’agent de vous interroger | Après une modification importante, avant la fusion | Dette de compréhension | Résumer les changements et leurs raisons, puis répondre aux questions. Ne fusionner que si toutes les réponses sont justes |
| 2. Rédiger une liste d’exigences avant de commencer | Avant de rédiger l’invite | Dette d’intention | Préciser à qui s’adresse le travail, quel problème il résout, ce qu’il exclut et les critères de réussite |
| 3. Demander quelles décisions n’étaient pas autorisées | À la fin d’une tâche longue | Dette de compréhension, dette d’intention | Demander quelles décisions ont été prises sans votre autorisation et sur quelles hypothèses elles reposent |
| 4. Demander ce qui n’a pas été testé | Lors de l’examen des résultats des tests | Dette de compréhension | Examiner les tests réellement exécutés et leurs résultats avant de lire le résumé de l’IA |
| 5. Conserver les documents sources | Lorsque plusieurs agents travaillent en parallèle | Dette de compréhension | Conserver les documents sources et les éléments de vérification des tâches importantes. Réduire le parallélisme si vous n’arrivez plus à tout examiner |
| 6. Pratiquer régulièrement sans agent | Chaque semaine, chaque mois | Dégradation des compétences | Coder une fois par semaine sans agent et faire chaque mois le point sur les compétences déléguées |
Demander à l’IA de vous interroger : le contrôle essentiel de la dette de compréhension
C’est l’une des idées les plus intéressantes de cette approche. Après une modification importante réalisée par un agent, ne vous précipitez pas pour l’approuver. Demandez-lui plutôt de jouer le rôle d’examinateur : il résume les changements et explique pourquoi il les a faits, puis pose quelques questions à leur sujet. Fixez ensuite une règle : la fusion n’a lieu que si vous répondez correctement à toutes les questions.
L’intérêt est de transformer une impression vague — « je crois avoir compris » — en un résultat vérifiable. Les questions auxquelles vous ne savez pas répondre indiquent précisément où se trouve votre dette de compréhension.
Demander ce qui a été décidé sans autorisation et ce qui n’a pas été testé
Au cours d’une tâche longue, un agent peut choisir lui-même des paramètres par défaut, ajuster le périmètre de l’implémentation ou même trancher entre des exigences contradictoires. Ces décisions ne figurent pas forcément dans le résumé final, parce qu’elles lui ont semblé « naturelles ». Plutôt que de simplement demander « c’est terminé ? », mieux vaut poser des questions précises : quelles décisions as-tu prises sans mon autorisation explicite ? Quels points reposent sur tes propres hypothèses ? Que reste-t-il à vérifier ? Quelles modifications pourraient affecter d’autres fonctionnalités ?
Il en va de même pour les tests. Addy rappelle qu’une suite de tests au vert prouve seulement que les conditions couvertes par ces tests ont été validées. Si les cas limites n’y figurent pas, le rapport peut tout de même être impeccable. Le bon réflexe est donc de regarder d’abord quels tests ont réellement été exécutés et quels résultats ils ont renvoyés, puis de lire le résumé généré par l’IA. Pour les modifications à haut risque, vous pouvez aussi demander à un autre agent de chercher les problèmes de manière indépendante, sous un angle différent.
Vérification avant fusion : 5 étapes pour ne pas approuver aveuglément le travail d’un Agent
En réunissant les méthodes précédentes, on obtient un processus à appliquer avant la fusion de chaque PR. Il ne demande pas de relire chaque ligne, mais de réfléchir activement à chaque étape.
- Écrire ses attentes avant de commencer : reformulez le besoin avec vos propres mots et notez le résultat attendu. Si le résultat ne vous satisfait toujours pas après deux ajustements de l’invite, reprenez le besoin à la base au lieu d’empiler les instructions.
- Demander des comptes sur les décisions : à la fin de la tâche, demandez à l’Agent de lister les décisions non autorisées, les hypothèses et les éléments non vérifiés.
- Vérifier les tests réellement exécutés : examinez les commandes de test et leurs sorties, puis demandez quels cas limites ne sont pas couverts.
- Demander à l’Agent de vous interroger : faites-lui préparer des questions à partir du diff. Pour chaque mauvaise réponse, retournez lire le code jusqu’à bien le comprendre.
- Chercher un oubli : une fois que l’Agent a rendu son travail, trouvez au moins un élément qu’il aurait pu oublier de vérifier.
Exemple minimal d’invite pour vérifier sa dette de compréhension
Voici l’invite la plus courante pour demander à l’Agent de vous interroger. Vous pouvez la coller directement dans une conversation avec Claude Code, Cursor ou Cline :
在我合并这次改动之前，请先做两件事：
1. 用不超过 10 条要点总结本次改了哪些文件、每处改动的原因。
2. 根据本次 diff 给我出 5 道题，重点覆盖：事务/调用顺序、
边界条件、错误处理、对其他模块的影响。
先只给题目，等我作答后再批改，并指出我答错的地方对应哪段代码。
规则：我没有全部答对之前，不要建议合并。
Voir le modèle complet d’invite avant fusion
# 阶段 A：开工前（偿还意图债，由我先填写）
需求说明：
- 面向谁：
- 要解决的问题：
- 明确不做的事：
- 完成标准（做到什么程度算完成）：
- 我预期的改动范围和结果：
# 阶段 B：任务结束后（请 Agent 逐条回答）
1. 你做了哪些我没有明确授权的决定？请列出决定内容和理由。
2. 哪些地方依赖了你自己的假设？假设不成立时会发生什么？
3. 还有哪些内容没有验证？
4. 哪些改动可能影响其他功能或模块？
5. 你实际运行了哪些测试命令？请贴出原始输出，而不是总结。
6. 哪些边界情况没有写进测试？
# 阶段 C：出题考核（偿还理解债）
请根据本次 diff 出 5 道题，先只给题目。
我作答后请批改，答错的题请定位到具体代码行。
我未全部答对前，不要建议合并。
# 阶段 D：高风险改动追加（可交给另一个独立会话）
请你作为独立审查者，不参考上一个会话的总结，
只基于原始需求和 diff，找出最可能出问题的 3 个地方。
🎯 Conseil d’utilisation : remplissez impérativement l’étape A vous-même avant de commencer, sans la confier à l’Agent. Pour l’étape D, ouvrez de préférence une nouvelle session afin d’éviter que le résumé du premier Agent n’influence la revue indépendante. Cela rejoint aussi la mise en garde d’Addy sur la perte d’information lorsque plusieurs Agents se transmettent des messages.
Aide-mémoire des questions à poser avant la fusion
| Étape | Questions à poser | Signaux d’alerte |
|---|---|---|
| Avant de commencer | Suis-je capable d’expliquer le besoin et les critères de réussite avec mes propres mots ? | Impossible de préciser ce qui est hors périmètre |
| Après livraison | Quelles décisions l’agent a-t-il prises sans autorisation ? | Répondre « aucune » alors que le diff dépasse clairement le périmètre |
| Tests | Quels tests ont réellement été exécutés ? Qu’est-ce qui n’a pas été testé ? | Un résumé sans résultat brut |
| Évaluation | Si on me posait des questions, pourrais-je répondre correctement à toutes ? | Se tromper sur l’ordre des transactions ou les cas limites |
| Vérification finale | Puis-je trouver un point que l’agent a omis de vérifier ? | Ne pas réussir à en trouver un seul |
Demander à l’IA de vous interroger ou examiner un rapport de validation
Une approche très différente vient de LobeHub, une plateforme open source de collaboration entre agents qui compte environ 84 000 étoiles sur GitHub. Selon Bai Jing Lab, l’équipe affirme ne « presque plus regarder le code » et se concentre plutôt sur les rapports de validation multimodaux produits par les agents. Elle utilise Acceptance, un outil développé en interne et publié en open source en septembre de cette année : avant de livrer son travail, l’agent décompose les exigences en points de contrôle directement observables, les vérifie un par un dans le produit réel, puis rassemble captures d’écran, enregistrements vidéo et journaux dans un rapport en ligne. Un humain peut valider l’ensemble ou renvoyer un point précis pour correction.
| Critère | L’IA vous interroge | Examen d’un rapport de validation |
|---|---|---|
| Objet de l’examen | Logique interne du code, décisions non autorisées, hypothèses | Comportement externe observable du produit |
| Forme des preuves | Questions-réponses, résultats de la correction | Captures d’écran, enregistrements vidéo, journaux, historique des commandes |
| Problèmes détectables | Ordre des transactions, cas limites, compromis implicites | Conformité de l’interface, des interactions et des fonctionnalités aux exigences |
| Problèmes facilement manqués | Les questions qu’on n’a pas pensé à poser | Logique interne invisible et risques architecturaux |
| Conditions préalables | Le développeur accepte de prendre le temps de comprendre | Les exigences peuvent être décomposées en points de contrôle observables et un environnement d’exécution automatisée est disponible |
| Rôle humain | Comprendre les modifications précises et en assumer la responsabilité | Définir les critères de validation et prendre la décision finale |
Comparaison des deux approches
Examen d’un rapport de validation : cette méthode est très efficace pour vérifier les comportements observables, et les retours peuvent cibler un seul point de contrôle. Dans le test décrit par l’article, la personne chargée de l’examen n’a renvoyé que le point concernant le fond sombre ; l’agent n’a modifié qu’une seule ligne de CSS, sans toucher aux autres fichiers. Mais cette approche suppose que les exigences puissent être décomposées en points de contrôle observables. L’article précise aussi que, pour les tâches plus complexes, la sécurité, l’architecture et la qualité finale nécessitent toujours un jugement humain, et que certaines étapes de transmission des retours doivent encore être traitées manuellement. L’affirmation selon laquelle l’équipe ne regarde « presque plus le code » vient de l’équipe elle-même et n’a pas été vérifiée de manière indépendante.
L’IA vous interroge : cette approche permet mieux de faire ressortir des problèmes « invisibles à l’interface », comme l’ordre des transactions ou les cas limites. Elle couvre ainsi précisément les angles morts du rapport de validation. Son efficacité dépend toutefois de la qualité des questions et exige que le développeur prenne réellement le temps de comprendre. Les deux approches ne s’excluent pas : le plus judicieux est d’utiliser le rapport de validation pour confirmer que « le travail a été bien fait », et les questions pour vérifier que « je comprends pourquoi il a été fait ainsi ».
Adapter l’examen de la dette de compréhension au risque des modifications
Tous les PR ne justifient pas un processus complet. Addy rappelle que lorsque vous générez plus de contenu que vous ne pouvez en assumer, vous ne faites plus une revue : vous pariez simplement qu’il n’y a pas de problème. Le tableau ci-dessous propose des niveaux de revue selon le risque, à adapter à la réalité de votre équipe.
| Niveau de risque | Modifications typiques | Niveau de revue recommandé |
|---|---|---|
| Faible | Textes, styles, scripts indépendants, prototypes | Un rapport de validation ou une vérification manuelle suffit ; consignez les résultats attendus |
| Moyen | Fonctionnalités métier courantes, ajout d’interfaces | Examiner les décisions non autorisées et vérifier les résultats réels des tests |
| Élevé | Transactions, autorisations, paiements, migrations de données | Processus complet en 5 étapes, questions d’évaluation et revue par un agent indépendant |
| Au-delà de la capacité de revue | Production parallèle de plusieurs agents, impossible à examiner entièrement | Ajouter des vérifications automatisées ou réduire le nombre d’agents en parallèle |
💡 Conseil : si votre équipe dispose déjà d’un processus de validation automatisé bien établi, réservez les questions d’évaluation aux modifications à haut risque. Sinon, appliquez au minimum la règle « bonnes réponses avant fusion » aux PR qui touchent à la cohérence des données et aux autorisations.
Questions fréquentes (FAQ)
Q1 : Qu’est-ce que la dette de compréhension ? En quoi diffère-t-elle de la dette technique ?
La dette de compréhension apparaît lorsque la complexité du code et des systèmes augmente plus vite que la compréhension qu’en ont les développeurs. La dette technique concerne généralement une qualité de code insuffisante. La dette de compréhension peut, elle, exister même avec du code de bonne qualité : le problème, c’est que les personnes ne le comprennent pas assez bien. Il devient alors particulièrement visible au moment de le modifier.
Q2 : Quelle différence entre demander à l’IA de vous interroger et lui demander directement d’expliquer le code ?
Quand l’IA explique, vous recevez l’information passivement et pouvez facilement avoir l’illusion d’avoir compris. Un questionnaire vous oblige à répondre activement : les erreurs peuvent être reliées à des passages précis du code, ce qui permet de vérifier concrètement votre compréhension.
Q3 : Ne pas valider aveuglément le travail d’un agent signifie-t-il qu’il faut examiner le code de l’IA ligne par ligne ?
Non. Selon les informations rapportées, l’équipe de Claude Code ne demande pas à ses ingénieurs de mémoriser toute la base de code. Lorsqu’ils doivent modifier une partie, ils s’appuient sur Claude pour en comprendre à nouveau la logique. L’essentiel est de savoir ce que vous comprenez et ce que vous ne comprenez pas, puis d’adapter la profondeur de la revue au niveau de risque.
Q4 : À quels scénarios de développement cette méthode convient-elle ?
Elle convient surtout aux scénarios suivants :
– **Tâches d’agent de longue durée** : elles peuvent entraîner des décisions non autorisées ; une liste de questions de suivi est donc utile
– **Modifications du backend impliquant des transactions ou des cas limites** : un questionnaire permet de vérifier la compréhension
– **Développement parallèle avec plusieurs agents** : il est utile de conserver les éléments d’origine et de limiter le nombre de tâches parallèles
– **Revue de code en équipe** : la liste de questions peut être intégrée au modèle de PR
Q5 : Comment mettre en place ce processus d’autocontrôle de la dette de compréhension dans Claude Code, Cursor ou Cline ?
La méthode ne dépend pas d’un outil précis : l’essentiel réside dans les invites et le processus.
1. Enregistrez le modèle d’invite complet de cet article comme extrait réutilisable par l’équipe
2. Avant de commencer, rédigez la phase A à la main, puis collez les phases B et C une fois la tâche terminée
3. Pour les modifications à haut risque, ouvrez une nouvelle session indépendante pour exécuter la phase D
Vous pouvez aussi inscrire la règle « ne fusionner que si les réponses sont correctes » dans les critères de vérification des PR de l’équipe.
Q6 : Quelles sont les limites connues de ces méthodes ?
Il faut garder un regard objectif :
– **Données sur l’efficacité** : aucune donnée publique ne démontre actuellement dans quelle mesure ces méthodes réduisent le taux de défauts ou améliorent l’efficacité
– **Temps nécessaire** : le processus complet allonge le cycle de fusion et ne convient pas à toutes les PR
– **Angles morts des questions** : un agent peut éviter des problèmes dont il n’a pas lui-même conscience ; il ne faut donc pas sauter l’étape consistant à « trouver un élément qui a échappé à la vérification »
– **Source** : les propos d’Addy ont été rapportés par un média ; la formulation originale reste à vérifier
Q7 : Est-il vraiment nécessaire de s’exercer à coder hors ligne chaque semaine ?
Selon Addy, les compétences qu’on n’utilise plus risquent de s’émousser avec le temps. Réaliser occasionnellement une tâche seul, sans agent, permet de mesurer son niveau réel. Faire aussi le point chaque mois sur les compétences déléguées à l’IA et celles qu’il faut continuer à maîtriser demande peu d’efforts, mais peut éviter de renoncer progressivement, sans s’en rendre compte, à comprendre par soi-même.
Ne donnez pas votre approbation à l’Agent à l’aveugle : l’essentiel sur la dette de compréhension
- L’abandon du jugement est progressif : on commence par déléguer une tâche cognitive, puis une décision, avant de confier tout son jugement à l’IA.
- La dette de compréhension produit des intérêts plus tard : plus le code est écrit vite, plus les parties mal comprises risquent de poser problème au moment des modifications.
- La dette d’intention se forme en amont : rédigez vous-même une liste des exigences avant de commencer. Si le résultat ne vous satisfait toujours pas après deux invites, reprenez les exigences.
- Le geste clé : se faire interroger : demandez à l’Agent de résumer les modifications et de vous poser des questions. Ne fusionnez le code que si vous répondez correctement à toutes.
- Tous les tests au vert ne garantissent pas l’absence de problèmes : examinez d’abord les résultats des tests réellement exécutés, puis demandez ce qui n’a pas été testé.
- Le rapport de validation et les questions sont complémentaires : le premier vérifie le comportement externe, les secondes évaluent votre compréhension de la logique interne.
- Adaptez la revue au niveau de risque : si vous ne pouvez pas tout examiner, automatisez davantage ou réduisez le nombre de tâches parallèles. Ne comptez pas sur la chance.
Conclusion
À retenir pour ne pas approuver le travail d’un Agent à l’aveugle :
- Repérer le glissement : attention à ne pas passer de « confier le travail à l’IA » à « confier le jugement à l’IA ». La dette de compréhension et la dette d’intention sont deux conséquences de ce glissement.
- Passer à l’action : notez vos attentes avant de commencer, demandez à la livraison quelles décisions ont été prises sans autorisation et ce qui n’a pas été testé, puis faites-vous interroger par l’IA avant la fusion.
- Adapter l’effort au risque : pour les modifications à faible risque, utilisez un rapport de validation ou procédez à une vérification ponctuelle. Pour celles à haut risque, suivez le processus complet et ajoutez une revue indépendante.
L’IA continuera d’écrire du code de plus en plus vite, mais la personne qui approuve une modification en reste responsable. La prochaine fois que vous cliquerez sur « Approuver », demandez d’abord à l’Agent de vous poser cinq questions et voyez combien de réponses vous trouvez.
📚 Références
- QbitAI : le grand guide des agents pour développeurs Claude (repris par 36 氪) : présentation des idées et des méthodes d’Addy Osmani sur la délégation cognitive, la dette de compréhension et la dette d’intention
- Lien :
36kr.com/p/4056027738116995 -
Note : source du fil méthodologique de cet article ; il s’agit d’une reprise médiatique
-
Publication originale d’Addy Osmani : source originale citée dans l’article
- Lien :
x.com/addyosmani/status/2117512471930167377 -
Note : pour les formulations exactes, consultez le texte original ; le lien reste à vérifier
-
白鲸实验室 : une entreprise d’IA aux 80 000 étoiles décide de confier les commandes à l’IA (repris par 36 氪) : présentation de l’architecture d’agents superviseurs de LobeHub et de sa pratique des rapports de validation Acceptance
- Lien :
36kr.com/p/4056040123945860 - Note : source de comparaison pour la revue sous forme de rapport de validation ; l’affirmation selon laquelle l’équipe « ne regarde presque pas le code » vient de l’équipe elle-même
Auteur : équipe technique APIYI
