Wat er gebeurt → wat je eraan doet
Zoek op symptoom, niet op titel. De link onder "wat je eraan doet" gaat naar de sectie die de aanpak beschrijft. De volledige inhoudsopgave van alle artikelen staat onderaan deze pagina.
Deze tabel gaat uit van Claude Code (de coding-agent van Anthropic). hook, CLAUDE.md, subagent en auto memory zijn de namen van zijn functies.
| Wat er gebeurt | Wat je eraan doet |
|---|---|
| Elke keer dat de AI de tests laat draaien, stromen er tienduizenden regels output de context in |
Bundel alle testruns in één wrapper-script, schrijf de volledige output naar een logbestand en geef de AI alleen een samenvatting van de mislukkingen terug. |
| Hoe meer kennisnotities de AI opslaat, hoe meer elke volgende sessie moet lezen |
Laat een PreToolUse hook die vlak voor het schrijven naar memory draait eerst de checklist lezen, en laat het instructiebestand (CLAUDE.md) slechts één regel bevatten: "lees voordat je schrijft". |
| De tests slagen, maar het is onduidelijk of ze werkelijk iets beschermen |
Leg het beleid voor mutation testing (de code doelbewust breken om te zien of de tests dat opmerken) vast in één document, en laat de AI dit lezen wanneer je vraagt om de tests te controleren. |
| De AI gebruikt een geregistreerde skill de ene keer wel en de andere keer niet |
Laat het commando een gewoon script blijven, blokkeer verkeerd gebruik met een PreToolUse hook en verwijs naar de documentatie die gelezen moet worden. |
| Zodra werk aan een sub-agent wordt overgedragen, is niet zichtbaar wat er gebeurt totdat het klaar is |
Definieer in YAML welke taken aan een sub-agent mogen worden gedelegeerd en welke invoerbestanden vóór het starten aanwezig moeten zijn, en controleer dit met een hook voordat de sub-agent start. |
| Hoe meer regels aan het instructiebestand worden toegevoegd, hoe minder de eerder toegevoegde regels worden nageleefd |
Herschrijf elke "doe dit niet"-regel, één voor één, als een geautomatiseerde test (Minitest) die een overtreding kan detecteren. |
| De memory die parallel draaiende sessies delen, raakt rommelig; ze laten lezen van het beleid helpt niet |
Verplaats hetzelfde beleidsbestand naar een PostToolUse hook en toon het samen met de diff direct na het opslaan. Verander niet wat er gelezen wordt, alleen het moment. |
| Zelfs als is vastgelegd hoe met een fout om te gaan, maakt de AI de volgende keer dezelfde fout opnieuw |
Vat het beleid voor een retry samen in een bestand van enkele regels, en laat een hook die de fout detecteert dit automatisch invoegen. |
| Zelfs na het lezen van de overdrachtstekst en het opleveringsrapport ontbreken de ongemakkelijke details |
Zet elke keer, naast het opleveringsrapport, cijfers die machinaal zijn verkregen, bijvoorbeeld met git diff --stat. |
| Een getal dat door de machine is geteld, verandert onderweg naar het rapport in een ander getal |
Geef de regel met het getal een vast voorvoegsel, en laat een hook controleren of dit letterlijk is overgenomen. |
| Als je de AI tijdens het werk onderbreekt, raakt alles wat daarna komt verstoord |
In plaats van dat een mens midden in het werk onderbreekt, laat je een PostToolUse hook die direct na het opslaan het beleid teruggeeft en een hook die een fout detecteert en het werk terugstuurt ingrijpen. De mens wacht tot een natuurlijk breekpunt. |
| Aan het einde van een sessie staat niet vast wat wel en niet gelezen hoeft te worden |
Lees noch het opgeleverde werk noch het werklog; beoordeel alleen op basis van de exit code van de tests of de linter. |
| Een voorstel dat al eens is afgewezen, duikt in de volgende sessie weer op |
Verzamel elke afgewezen beslissing in één document, in een vast format. |
| Ondanks een verbod van één regel wordt het zowel te ruim als te strikt geïnterpreteerd |
Voeg in het ene document dat de afgewezen beslissingen verzamelt (bijvoorbeeld non_goals.md) voor elk verbod een kopje "reden" toe, naast de conclusie. |
| Het verbod staat correct beschreven maar wordt niet nageleefd, en elke keer komt er een vraag over binnen |
Voeg in het document met afgewezen beslissingen voor elk verbod een kopje "toepassingsbereik" toe en som de grensgevallen waarover twijfel bestaat één voor één op. |
| Als dezelfde instructie naar meerdere sub-agents gaat, komt elk resultaat in een andere vorm terug |
Vermeld in de lijst van taken die aan een sub-agent mogen worden gegeven, expliciet welke invoerbestanden vóór het starten klaar moeten liggen. |
| Verboden zonder geautomatiseerde test stapelen zich op als niets meer dan tekst op een pagina |
Voeg in het document met afgewezen beslissingen een kopje "machinale controle" aan de lijst toe en geef per item aan of er een bijbehorende geautomatiseerde test (Minitest) bestaat. |
| Elke keer eindigt het werk van de AI met "open het scherm en controleer het zelf" |
Zet één smoke test met Playwright op, en bepaal slagen of falen aan de hand van de record die in de database is achtergebleven, niet aan het uiterlijk van het scherm. |
| Telkens als de AI iets net niet goed zegt, moet jij het zelf uitleggen en corrigeren |
In plaats van dat een mens elke afwijking uitlegt en corrigeert, schrijf je de opmerking in de stderr van een hook (exit 2) en in de foutmeldingen van geautomatiseerde tests, zodat die langs die weg bij de AI aankomt. |
| De lijst met afgewezen beslissingen blijft groeien en dreigt op een gegeven moment niet meer gelezen te worden |
Voeg aan het einde van het document met afgewezen beslissingen een sectie "niet overgenomen voorstellen" toe en leg afgewezen voorstellen daar vast. |
| De "voer dit altijd uit"-regels in het instructiebestand blijven zich ophopen |
Verifieer met een geautomatiseerde test of elk commando dat het instructiebestand als "altijd uitvoeren" markeert, ook daadwerkelijk in een pre-commit hook staat. |
| Zelfs met de exacte werkwijze erbij, komt de fix niet op die manier terug |
Definieer, in plaats van de procedure voor te schrijven, per toepassing welke invoerbestanden moeten bestaan voordat een sub-agent mag starten. |
| Om een bug te melden, schrijf je zelf steeds opnieuw de stappen en de symptomen uit |
Zet een bugmeldingsformulier op waarin de gebruiker alleen één zin over het symptoom hoeft in te vullen, en laat JavaScript automatisch de URL, de handelingsgeschiedenis en de browserinformatie verzamelen. |
| Elke keer opnieuw "geef eerst een plan" typen kost telkens moeite |
Er is geen nieuwe implementatie nodig. Plaats één ontwerpdocument, en de AI leest de bestaande documenten en volgt dezelfde opzet. |
| Juist de regels die het meest moeten worden nageleefd, zijn het sterkst benadrukt, maar het is onduidelijk of dat helpt |
Stop met het meten van het effect; tel in plaats daarvan het aantal regels met nadruksbewoording in het instructiebestand, en plaats een geautomatiseerde test (een ratchet) die faalt zodra dat aantal een drempel overschrijdt. |
| Het opgeleverde werk van een sub-agent komt terug in een andere vorm dan verwacht |
Definieer per toepassing van een sub-agent de acceptatiecriteria voor het opgeleverde werk (bestandsnaam, formaat, verplichte velden) in één document. |
| Als je een fout vindt, wil je vragen: "heb je dit wel echt gelezen?" |
Leg, in plaats van het verwijt te maken, de tweede zin van elk verzoek vast op de vraagvorm "is het niet zo dat ...?". |
| Reageren met "nee, zo bedoel ik het niet" op het antwoord maakt het niet beter |
Presenteer, in plaats van het zelf aan te wijzen, een verbod zonder alternatief via een PostToolUse hook, samen met de diff direct na het opslaan. |
| De AI praat over de inhoud van een bestand alsof het is geopend, terwijl dat niet zo is |
Laat de AI bij elkaar horende markers in zowel het gerefereerde document als de code schrijven, en verifieer met een geautomatiseerde test dat die markers echt bestaan. |
| De AI blijft vragen "A of B?" en het werk komt stil te liggen terwijl jij beslist |
Stop met direct antwoord geven, en laat de keuze bepalen door een geautomatiseerde test of een hook. |
| De AI voert de review uit, maar het is onduidelijk wat er niet wordt bekeken |
Detecteer met een geautomatiseerde test van buitenaf elke geautomatiseerde test die wel bestanden doorloopt maar geen ondergrens op het aantal heeft (assert_operator ... :>=). |
| Screenshots stapelen zich op, maar het is onduidelijk welke wat heeft geverifieerd |
Laat, voordat het scherm wordt gecontroleerd, twee vragen beantwoorden — "wat wordt er geverifieerd" en "waarom volstaat een goedkopere methode niet" — en leg één richtlijn vast om eerst de goedkoopste optie te proberen, in de volgorde unit test → integratietest → E2E. |
| Er is een stap ingebouwd die iets moet vastleggen, maar het aantal runs dat dit oversloeg valt niet te tellen |
Laat vóór een screenshot of E2E-run een verklaringsbestand schrijven dat vastlegt wat er wordt geverifieerd (bijvoorbeeld tmp/visual_verification.md), maak het bestaan ervan een voorwaarde voor een PreToolUse hook, en zonder dat bestand start screenshot noch E2E. |
| Dezelfde test draait opnieuw terwijl de code niet is veranderd, en je wacht er onnodig op |
Voeg een --last-optie toe aan het test-wrapperscript die het vorige log opnieuw toont, zodat een herhaalde run overbodig wordt. |
| Er is niets kapotgemaakt, maar er verschijnt een hele rij onbekende fouten |
Laat het test-wrapperscript een exclusieve lock nemen (met gebruik van de atomiciteit van mkdir), en niet uitvoeren als die lock niet kan worden verkregen. |
| Het rapport "de tests slagen" vermeldt niet welk deel niet is gedraaid |
Geef zware E2E-tests een tag met de naam van het domein, sla ze standaard over (skip) en print elke keer de lijst van domeinen die niet zijn uitgevoerd. |
| Achteraf is niet vast te stellen of een instructie die de werkwijze voorschreef, ook is gevolgd |
Versterk niet de bewoording van de instructie als je wilt dat een procedure wordt gevolgd; zorg er in plaats daarvan voor dat het volgen ervan een spoor achterlaat in het opgeleverde werk (bijvoorbeeld: laat voor elk geopend bestand één regel afdrukken). |
| Een geïnstalleerde wrapper wordt halverwege weer vervangen door het kale commando |
Versterk niet de instructie als je wilt dat de wrapper wordt gebruikt; controleer in plaats daarvan of er nog een reden is om terug te vallen op het kale commando, oftewel of de wrapper een functie mist. |
| Dezelfde vraag herhaaldelijk stellen levert elke keer een ander antwoord op, en bij het samenvatten verdwijnt er iets |
Print, voordat meerdere antwoorden tot één worden samengevoegd, per type bevinding hoe vaak het voorkwam (hoeveel van de hoeveel het noemden). |
| Onduidelijk is of een regel als "doe dit indien nodig" ooit daadwerkelijk in werking is getreden |
Schrijf geen voorwaardelijke instructies als "doe dit indien nodig"; dwing de stap in plaats daarvan af met een hook die verdergaan blokkeert totdat die stap is doorlopen. |
| Terugsturen met "denk er nog eens over na" verandert het antwoord, maar het is onduidelijk of de AI echt overtuigd is |
Stuur het niet terug met "denk er nog eens over na"; wijs in plaats daarvan concreet aan welke aanname onjuist is. |
| Sinds "geen aannames doen" is voorgeschreven, komt de AI terug zonder iets te hebben gebouwd |
Geef niet alleen een verbod mee; voeg er een alternatieve uitkomst aan toe, zoals "geef 'niet van toepassing' op als niets van toepassing is". |
| Hoe langer een goedlopend gesprek wordt voortgezet, hoe meer moeite het kost om te verifiëren |
Beëindig de sessie bij elke taakgrens en start de volgende taak in een nieuwe sessie. |
| Alle opgeleverde resultaten kloppen, maar er stapelt zich verspilling op die daarin niet zichtbaar is |
Laat, zodra het opgeleverde werk compleet is, een script eenmalig het werklog (transcript) zelf analyseren. |
| Kennis die voor de volgende persoon is vastgelegd, raakt achterhaald en komt niet meer overeen met de werkelijkheid |
Leg kennis niet vast in een document; bed die in plaats daarvan in de foutmelding van een geautomatiseerde test of het stopbericht van een hook, zodat die precies op het juiste moment verschijnt. |
| Het uitzoeken van de oorzaak gaat door, en het lezen blijft doorgaan zelfs nadat het antwoord al is gevonden |
Tel in het werklog reeksen van lezen zonder dat er iets wordt veranderd, en schrijf voordat je begint met uitzoeken een stopvoorwaarde in één regel. |
| Het goedkoopste model per eenheid wordt standaard ingesteld zonder te meten of het bij het gebruiksdoel past |
Geef dezelfde taak aan zowel het goedkopere als het duurdere model, en beslis pas nadat je apart het aantal beurten tot voltooiing en de hoeveelheid nieuw gelezen, hergebruikte (cache read) en geschreven inhoud hebt geteld. |
| Als iets niet werkt, wordt er gegrepen naar een groter model in plaats van naar een beter mechanisme |
Geef dezelfde taak aan zowel het duurdere als het goedkopere model, en maak van de plekken waar alleen het goedkopere model faalt een blijvende controle. |
| Onderzoek dat de hoofdsessie zelf kan afronden, wordt uit voorzorg toch aan een sub-agent overgedragen |
Controleer voordat je delegeert of de bovenliggende agent die context al heeft. Zo ja, ga dan door in de bovenliggende agent; geef een sub-agent alleen de omvangrijke leesarbeid die daar nog ontbreekt. |
| Het werk wordt zomaar in vieren gesplitst en gelijktijdig uitgevoerd |
Geef elke sub-agent alleen zoveel als in één antwoord teruggeleverd kan worden. Niet het aantal sub-agents bepaalt de kosten, maar hoeveel rondes elke afgesplitste sub-agent met de bovenliggende agent nodig heeft. |
| Halverwege het werk wordt van buitenaf "kijk hier ook nog even naar" ingebracht |
Wacht tot een natuurlijk breekpunt in het werk en breng het extra verzoek dan met een beperkter bereik in. Voeg bij het vragen aan de AI zelf naar tekortkomingen altijd toe: "schrijf expliciet op als het voldoende is". Dat geeft haar een uitweg (escape hatch), zodat ze geen tekortkoming hoeft te verzinnen. |
| Welk model te gebruiken wordt bepaald door ze rechtstreeks te vergelijken |
Tel, voordat je modellen gaat vergelijken, hoeveel hooks of geautomatiseerde tests die vergelijking aan moeite kost. Als er meer mechanismen zijn uit te schrijven dan dat aantal, zet die dan neer vóór de vergelijking. |
| "Er was geen verschil" wordt gebruikt als reden om de verificatie af te sluiten |
Tel, voordat je afsluit met "er was geen verschil", twee dingen: als er resultaten buiten de telling zijn gelaten (zoals mislukte sub-agents), zet ze terug en tel opnieuw; als bij meer dan de helft van de items onder elke conditie nul uitkomt, herformuleer de taak en meet opnieuw. |
Alle artikelen
Per reeks, van de inleiding tot het laatste deel.
はじめに —— 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 分前に開いたページに、答えが書いてありました
- あとがき —— 本当の事実はどうでもいい話