Ce qui se passe → quoi faire
Recherchez par symptôme plutôt que par titre. Le lien sous « quoi faire » renvoie à la section qui décrit le mécanisme. La table des matières complète se trouve en bas de page.
Ce tableau suppose l'utilisation de Claude Code (l'agent de programmation d'Anthropic). hook, CLAUDE.md, subagent et auto memory sont les noms de ses fonctionnalités.
| Ce qui se passe | Quoi faire |
|---|---|
| Chaque fois que l'IA lance les tests, des dizaines de milliers de lignes de sortie envahissent le contexte |
Faites passer tous les lancements de tests par un seul script wrapper, écrivez la sortie complète dans un fichier de log, et ne renvoyez à l'IA qu'un résumé des échecs. |
| Plus l'IA enregistre de notes de connaissance, plus chaque session future doit en lire |
Utilisez un hook PreToolUse qui s'exécute juste avant l'écriture en mémoire pour faire lire une checklist à l'IA, et ne laissez dans le fichier d'instructions (CLAUDE.md) qu'une seule ligne : « lire avant d'écrire ». |
| Les tests passent, mais on ne sait pas s'ils protègent réellement quelque chose |
Rédigez une politique d'une page sur le mutation testing (casser délibérément le code pour voir si les tests le détectent), et faites-la lire à l'IA chaque fois que vous lui demandez de vérifier les tests. |
| L'IA utilise parfois une skill enregistrée, et parfois non |
Gardez la commande sous forme de script ordinaire, bloquez les invocations incorrectes avec un hook PreToolUse, et indiquez à l'IA la documentation à lire. |
| Une fois le travail confié à un sub-agent, on ne voit ce qui se passe qu'une fois qu'il a terminé |
Définissez en YAML les tâches délégables à un sub-agent et les fichiers d'entrée requis avant son lancement, puis vérifiez cela avec un hook avant le démarrage. |
| Plus on ajoute de règles au fichier d'instructions, moins les règles ajoutées précédemment sont respectées |
Réécrivez chaque règle « ne pas faire X », une par une, sous forme de test automatisé (Minitest) capable de détecter une violation. |
| La mémoire partagée entre sessions parallèles devient désordonnée, et leur faire lire la politique n'y change rien |
Déplacez le même fichier de politique dans un hook PostToolUse et affichez-le à côté du diff juste après l'enregistrement. Ne changez pas le contenu, seulement le moment où il est lu. |
| Même en ayant écrit comment traiter un échec, l'IA refait la même erreur la fois suivante |
Résumez la politique de nouvelle tentative en quelques lignes dans un fichier, et faites-la insérer automatiquement par un hook qui détecte l'échec. |
| Même en lisant la note de passation et le rapport d'achèvement, les points gênants en sont absents |
Placez systématiquement, à côté du rapport d'achèvement, des chiffres obtenus mécaniquement — par exemple via git diff --stat. |
| Les chiffres comptés par la machine deviennent d'autres chiffres avant d'arriver dans le rapport |
Ajoutez un préfixe fixe à la ligne contenant le chiffre, et faites vérifier par un hook qu'elle a été copiée mot pour mot. |
| Interrompre l'IA en plein travail déstabilise tout ce qu'elle fait ensuite |
Plutôt qu'une personne n'interrompe en plein travail, laissez intervenir un hook PostToolUse qui renvoie la politique juste après l'enregistrement et un hook qui détecte l'échec et renvoie le travail. La personne attend une pause naturelle. |
| À la fin d'une session, on ne sait pas ce qu'il faut lire et ce qu'on peut ignorer |
Ne lisez ni le livrable ni le journal de travail — jugez uniquement sur l'exit code des tests ou du linter. |
| Une proposition déjà refusée revient à la session suivante |
Rassemblez toutes les décisions rejetées dans un seul document, selon un format fixe. |
| Même avec une interdiction écrite en une ligne, elle est tantôt interprétée trop largement, tantôt trop étroitement |
Dans le document unique qui rassemble les décisions rejetées (par exemple non_goals.md), ajoutez une rubrique « raison » à chaque interdiction, à côté de la conclusion. |
| L'interdiction est correctement écrite mais n'est pas suivie, et à chaque fois quelqu'un vient demander |
Dans le document des décisions rejetées, ajoutez une rubrique « périmètre » à chaque interdiction et listez, une ligne à la fois, les cas limites qui prêtent à confusion. |
| Donnez les mêmes instructions à plusieurs sub-agents, et chacun revient sous une forme différente |
Dans la liste des tâches délégables à un sub-agent, indiquez explicitement les fichiers d'entrée à préparer avant le lancement. |
| Les interdictions sans test automatisé s'accumulent, restant de simples lignes de texte |
Dans le document des décisions rejetées, ajoutez une rubrique « vérification automatique » à la liste et indiquez, pour chaque élément, si un test automatisé (Minitest) correspondant existe. |
| Chaque tâche de l'IA se termine par « veuillez ouvrir l'écran et vérifier » |
Préparez un seul smoke test Playwright, et jugez le résultat sur l'enregistrement laissé dans la base de données plutôt que sur l'apparence de l'écran. |
| Chaque fois que l'IA dit quelque chose d'un peu à côté, c'est vous qui expliquez et corrigez |
Plutôt qu'une personne n'explique et ne corrige chaque écart, écrivez la remarque dans le stderr d'un hook (exit 2) et dans les messages d'échec des tests automatisés, pour que ce soit par cette voie qu'elle parvienne à l'IA. |
| La liste des décisions rejetées ne cesse de croître, au point qu'elle finira par ne plus être lue |
Ajoutez une section « propositions non retenues » à la fin du document des décisions rejetées, et consignez-y les propositions rejetées. |
| Les lignes « exécutez toujours ceci » du fichier d'instructions ne cessent jamais de s'accumuler |
Vérifiez avec un test automatisé que chaque commande marquée « exécuter toujours » dans le fichier d'instructions existe aussi dans un pre-commit hook. |
| Même en détaillant exactement la marche à suivre, le résultat ne revient pas conforme |
Plutôt que de dicter la procédure, définissez, pour chaque usage, les fichiers d'entrée qui doivent exister avant de lancer un sub-agent. |
| Signaler un bug oblige à rédiger soi-même, à chaque fois, les étapes et les symptômes |
Mettez en place un formulaire de rapport de bug où la personne ne saisit qu'une phrase décrivant le symptôme, et laissez JavaScript collecter automatiquement l'URL, l'historique des actions et les informations du navigateur. |
| Taper « donnez-moi d'abord un plan » à chaque fois est en soi une corvée récurrente |
Aucune nouvelle implémentation n'est nécessaire. Placez un seul document de conception, et l'IA lira les documents existants pour reproduire le même format. |
| Les lignes que vous voulez le plus voir respectées sont écrites avec le plus d'emphase, sans qu'on sache si cela sert à quelque chose |
Renoncez à mesurer l'effet — comptez plutôt les lignes du fichier d'instructions qui utilisent l'emphase, et mettez en place un test automatisé (un ratchet) qui échoue dès que ce nombre dépasse un seuil. |
| Le livrable d'un sub-agent revient sous une forme différente de celle attendue |
Pour chaque usage de sub-agent, définissez dans un seul document les critères d'acceptation du livrable — nom de fichier, format, champs obligatoires. |
| Trouver une erreur donne envie de demander : « avez-vous vraiment lu cela ? » |
Plutôt que d'interroger, fixez la deuxième phrase de chaque demande sur le modèle de question « n'est-ce pas que ... ? ». |
| Répondre « ce n'est pas ça » à la réponse reçue ne l'améliore pas |
Plutôt que de le signaler vous-même, présentez les interdictions sans alternative via un hook PostToolUse, affichées à côté du diff juste après l'enregistrement. |
| L'IA parle du contenu d'un fichier comme si elle l'avait ouvert, alors qu'elle ne l'a pas fait |
Faites écrire des markers correspondants à la fois dans le document référencé et dans le code, et vérifiez avec un test automatisé que ces markers existent réellement. |
| L'IA demande sans cesse « A ou B ? », et le travail s'arrête le temps de trancher |
Cessez de répondre sur le champ — faites en sorte que le choix soit tranché par un test automatisé ou un hook. |
| L'IA fait la revue, mais on ne sait pas ce qu'elle ne regarde pas |
Détectez, avec un test automatisé externe qui compte, tout test automatisé qui parcourt des fichiers sans borne inférieure sur le nombre (par exemple assert_operator ... :>=). |
| Les captures d'écran s'accumulent, sans qu'on sache laquelle a vérifié quoi |
Avant de vérifier l'écran, exigez une réponse à deux questions — « que vérifie-t-on » et « pourquoi une méthode moins coûteuse ne suffit pas » — et gardez une directive d'une page pour essayer d'abord l'option la moins coûteuse, dans l'ordre test unitaire → test d'intégration → E2E. |
| Une étape exigeant une déclaration écrite est en place, mais on ne peut pas compter combien d'exécutions l'ont contournée |
Avant une capture d'écran ou un run E2E, faites écrire un fichier de déclaration qui précise ce qui est vérifié (par exemple tmp/visual_verification.md), faites de son existence une condition d'un hook PreToolUse, et sans lui ni la capture ni le E2E ne démarrent. |
| Le même test s'exécute à nouveau alors que le code n'a pas changé, et vous attendez quand même |
Ajoutez une option --last au script wrapper des tests, qui rejoue le log précédent pour éviter une nouvelle exécution. |
| Rien n'a été cassé, et pourtant une série d'erreurs inconnues apparaît |
Faites prendre un verrou exclusif (lock) au script wrapper des tests, en s'appuyant sur l'atomicité de mkdir, et refusez l'exécution si le verrou ne peut être obtenu. |
| Un rapport disant « les tests passent » ne mentionne pas les parties qui n'ont jamais tourné |
Étiquetez les tests E2E lourds par nom de domaine et faites-les skip par défaut, en affichant systématiquement la liste des domaines non exécutés. |
| Impossible de savoir après coup si une instruction précisant la marche à suivre a bien été respectée |
Pour faire respecter une procédure, ne renforcez pas la formulation de l'instruction — changez-la plutôt pour que suivre la procédure laisse une trace dans le livrable (par exemple, faire afficher une ligne pour chaque fichier ouvert). |
| Le wrapper mis en place est abandonné en cours de route, au profit de la commande brute |
Pour faire utiliser le wrapper, ne renforcez pas l'instruction — vérifiez plutôt s'il reste une raison de revenir à la commande brute, c'est-à-dire une fonctionnalité manquante dans le wrapper. |
| Poser la même question plusieurs fois donne une réponse différente à chaque fois, et résumer fait disparaître quelque chose |
Avant de fusionner plusieurs réponses en une seule, affichez la fréquence d'apparition de chaque type de remarque — combien l'ont soulevée sur combien au total. |
| Impossible de savoir si une ligne du type « faites X si nécessaire » s'est un jour vraiment déclenchée |
N'écrivez pas d'instructions conditionnelles du type « faites X si nécessaire » — imposez plutôt l'étape avec un hook qui bloque la progression tant qu'elle n'est pas faite. |
| Dire « réfléchissez-y encore » change la réponse, sans qu'on sache si l'IA est réellement convaincue |
Plutôt que de renvoyer avec « réfléchissez-y encore », indiquez précisément quelle prémisse est erronée. |
| Écrire « ne devinez pas » a fait que l'IA revient désormais sans avoir rien construit |
Ne donnez pas qu'une interdiction — associez-y une sortie de repli, comme « si rien ne s'applique, affichez "non applicable" ». |
| Plus une conversation qui se passe bien se prolonge, plus la vérification devient coûteuse |
Terminez la session à chaque fin de tâche, et démarrez la tâche suivante dans une nouvelle session. |
| Tous les livrables sont corrects, mais du gaspillage qui n'y apparaît jamais s'accumule |
Une fois les livrables réunis, faites analyser une seule fois le journal de travail (transcript) lui-même par un script. |
| Les notes laissées pour la personne suivante finissent par diverger de la réalité et devenir obsolètes |
Ne laissez pas la connaissance dans un document — intégrez-la dans le message d'échec d'un test automatisé ou le message d'arrêt d'un hook, pour qu'elle apparaisse exactement au moment où elle est utile. |
| L'investigation de la cause se poursuit, et la lecture continue même après avoir trouvé la réponse |
Comptez, à partir du journal de travail, les séries de lectures qui n'ont rien changé, et écrivez en une ligne une condition d'arrêt avant de commencer à creuser. |
| Le modèle le moins cher est choisi par défaut sans mesurer s'il convient réellement à l'usage |
Confiez la même tâche au modèle le moins cher et au plus cher, puis décidez seulement après avoir compté séparément le nombre d'échanges jusqu'à l'achèvement, ainsi que les quantités lues pour la première fois, réutilisées (cache read) et écrites. |
| Quand quelque chose ne fonctionne pas, le réflexe est de monter en gamme de modèle plutôt que d'améliorer le mécanisme |
Confiez la même tâche au modèle le plus cher et au moins cher, et transformez en vérification permanente les endroits où seul le moins cher échoue. |
| Une recherche que la session principale pourrait terminer seule est confiée à un sub-agent par précaution |
Avant de déléguer, vérifiez si l'agent parent possède déjà ce contexte. Si oui, continuez dans l'agent parent ; ne confiez à un sub-agent que le gros volume de lecture qu'il n'a pas déjà. |
| Le réflexe par défaut est de découper le travail en quatre et de tout lancer en même temps, sans raison précise |
Ne confiez à chaque sub-agent que ce qu'il peut restituer en une seule réponse. Ce n'est pas le nombre de sub-agents qui détermine le coût, mais le nombre d'allers-retours de chaque sub-agent issu de la division avec l'agent parent. |
| « Regardez aussi ceci » s'immisce de l'extérieur en plein milieu du travail |
Attendez une pause naturelle du travail, puis introduisez la demande supplémentaire avec un périmètre restreint. Quand vous demandez à l'IA elle-même s'il manque quelque chose, ajoutez toujours : « si c'est suffisant, dites-le explicitement ». Cela lui laisse une porte de sortie (escape hatch), pour qu'elle n'ait pas à inventer un manque. |
| Le choix du modèle à utiliser se fait en les comparant directement l'un à l'autre |
Avant de commencer à comparer des modèles, comptez à combien de hooks ou de tests automatisés équivaut l'effort de cette comparaison. Si vous pouvez formuler davantage de mécanismes que ce nombre, mettez-les en place avant de comparer. |
| « Il n'y avait pas de différence » sert de prétexte pour clore la vérification |
Avant de clore avec « il n'y avait pas de différence », comptez deux choses : si des résultats ont été exclus du décompte (par exemple des sub-agents en échec), réintégrez-les et recomptez ; si plus de la moitié des éléments sont à zéro dans toutes les conditions, reformulez la tâche et mesurez à nouveau. |
Tous les articles
Série par série, de l'introduction jusqu'au dernier article.
はじめに —— 3 つの連載を、1 冊に
バイブコーディングにおける読まない技術
- 読まない技術 序論 AIの出力を、もうほとんど読んでいない
- 読まない技術 第1回 テスト結果を読まない技術
- 読まない技術 第2回 メモリを読まない技術
- 読まない技術 第3回 単体テストを読まない技術
- 読まない技術 第4回 スキルを使わない技術
- 読まない技術 第5回 サブエージェントの出力だけは読め
- 読まない技術 第6回 ルールを読まない技術
- 読まない技術 第7回 共有メモリを整理しない技術
- 読まない技術 第8回 修正履歴を読まない技術
- 読まない技術 第9回 引き継ぎを読まない技術
- 読まない技術 第10回 AIに要約しろと言わない技術
- 読まない技術 第11回 口を挟まない技術
- 読まない技術 第12回 作業結果を読まない技術
- 読まない技術 最終回 AIの出力を、ほとんど読まなくなった
AIの意見を聞かない技術
言わない技術
- 言わない技術 序論 AI に指示することが、ほとんどなくなった
- 言わない技術 第1回 検証を指示しない技術
- 言わない技術 第2回 具体的な指示を出さない技術
- 言わない技術 第3回 不具合詳細を書かない技術
- 言わない技術 第4回 計画を書けと言わない技術
- 言わない技術 第5回 念を押さない技術
- 言わない技術 第6回 サブエージェントの出力だけは、細かく指示しろ
- 言わない技術 第7回 AI を問い詰めない技術
- 言わない技術 第8回 AI にダメ出ししない技術
- 言わない技術 第9回 AI に考えさせない技術
- 言わない技術 第10回 質問に答えない技術
- 言わない技術 第11回 AI にレビューをさせない技術
- 言わない技術 最終回 何もしない技術
付録
はじめに —— 前巻の続きを、もう 1 冊に
確かめない技術
動かさない技術
追わない技術
番外編
- 番外編 A-1 整理する技術 —— 記録が増えたときに、何が起きているか
- 番外編 A-2 指示を残す技術 —— 「調べるだけ」が通らなかった日
- 番外編 A-3 参照するタイミングを変える技術 —— 2,000 行の壁
- 番外編 A-4 導出を依頼者の言葉と分ける技術 —— 誰も言っていない条件が、memory に載った日
- 番外編 A-5 memory を要約しない技術 —— 整理から、要約を抜く
- 番外編 A-6 責務で線を引く技術 —— 仕組みが増えたときに、どれを消すか
- 番外編 A-7 読まれたかを確かめる技術 —— 確かめるのをやめて、読めていない形を止めた
- 番外編 A-8 面積で数える技術 —— 読ませた量で数えていたら、102 倍外していました
- 番外編 A-9 ルールを短くする技術 —— 読みに来るのは、止められた直後の人です
- 番外編 B-1 連載を本にする技術 —— 本単位のスイッチでは、足りなかった日
- 番外編 C-1 校正の方法に、先に本編を当てる技術 —— 方法を決める文が、本文と同じ地雷を踏んでいた日
- 番外編 C-2 仕組みと人を分ける技術 —— 検査を置いたその手で、検査の外側で 2 度転んだ日
- 番外編 C-3 要素ごとに観点を変える技術 —— 一様に当てた点検が、要素をまたいだところで数を落としていた
- 番外編 C-4 指示の揺れを、事故として残す技術 —— 事故を見て置いた仕組みは、まだ一度も鳴っていない
- 番外編 C-5 作業の流れを見る技術 —— 終わりにしたつもりの日に、まだ起きていたこと
- 番外編 C-6 作業を進める技術 —— 選ぶ場面が、1 つも残らなかった日
- 番外編 C-7 基準の出どころを見る技術 —— 2 分前に開いたページに、答えが書いてありました
- あとがき —— 本当の事実はどうでもいい話