Was passiert → was zu tun ist
Schlagen Sie nach Symptom nach, nicht nach Titel. Der Link unter „was zu tun ist“ führt zu dem Abschnitt, der diese Maßnahme beschreibt. Das vollständige Inhaltsverzeichnis aller Artikel steht unten auf dieser Seite.
Diese Tabelle setzt Claude Code (den Coding-Agenten von Anthropic) voraus. hook, CLAUDE.md, subagent und auto memory sind die Namen seiner Funktionen.
| Was passiert | Was zu tun ist |
|---|---|
| Jedes Mal, wenn die KI die Tests laufen lässt, strömen Zehntausende Ausgabezeilen in den Kontext |
Bündeln Sie alle Testläufe in einem einzigen Wrapper-Skript, schreiben Sie die vollständige Ausgabe in eine Logdatei und geben Sie der KI nur eine Zusammenfassung der Fehlschläge zurück. |
| Je mehr Wissensnotizen die KI speichert, desto mehr muss jede künftige Session lesen |
Lassen Sie die KI über einen PreToolUse-Hook, der unmittelbar vor jedem Speichern in die Memory läuft, zuerst eine Checkliste lesen, und beschränken Sie die Instruktionsdatei (CLAUDE.md) auf eine einzige Zeile: "Vor dem Schreiben lesen." |
| Die Tests sind grün, aber es ist unklar, ob sie tatsächlich etwas absichern |
Fassen Sie die Richtlinie zu mutation testing (dem Verfahren, den Code absichtlich zu beschädigen und zu prüfen, ob die Tests es bemerken) auf einer Seite zusammen und lassen Sie die KI sie lesen, sobald Sie eine Prüfung der Tests anfordern. |
| Die KI nutzt eine registrierte Skill mal, mal nicht |
Lassen Sie den Befehl ein gewöhnliches Skript bleiben, blockieren Sie falsche Aufrufe mit einem PreToolUse-Hook und verweisen Sie dabei auf die Dokumentation, die gelesen werden soll. |
| Ist eine Aufgabe an einen Subagent übergeben, sieht man erst beim Abschluss, was passiert ist |
Definieren Sie in YAML, welche Aufgaben an einen Subagent delegiert werden dürfen und welche Eingabedateien vor dem Start vorliegen müssen, und prüfen Sie das per Hook, bevor er startet. |
| Je mehr Regeln der Instruktionsdatei hinzugefügt werden, desto weniger werden die früheren Regeln befolgt |
Schreiben Sie jede "Tu X nicht"-Regel einzeln in einen automatisierten Test (Minitest) um, der einen Verstoß erkennen kann. |
| Die von parallel laufenden Sessions gemeinsam genutzte Memory verwahrlost, und sie die Richtlinie lesen zu lassen hilft nicht |
Verschieben Sie dieselbe Richtliniendatei in einen PostToolUse-Hook und zeigen Sie sie direkt nach dem Speichern zusammen mit dem Diff an. Der Inhalt bleibt unverändert — nur der Zeitpunkt ändert sich. |
| Selbst wenn der Umgang mit einem Fehlschlag dokumentiert ist, macht die KI beim nächsten Mal denselben Fehler wieder |
Fassen Sie die Retry-Richtlinie in wenigen Zeilen in einer Datei zusammen und lassen Sie einen Hook, der den Fehlschlag erkennt, sie automatisch einfügen. |
| Selbst beim Lesen von Übergabetext und Abschlussbericht fehlen die unbequemen Stellen |
Stellen Sie dem Abschlussbericht jedes Mal maschinell ermittelte Zahlen gegenüber — etwa aus git diff --stat. |
| Von der Maschine gezählte Zahlen werden auf dem Weg in den Bericht zu anderen Zahlen |
Versehen Sie die Zeile mit der Zahl mit einem festen Präfix und prüfen Sie per Hook, ob sie wortgetreu übernommen wurde. |
| Unterbricht man die KI mitten in der Arbeit, gerät alles Folgende aus dem Takt |
Statt dass ein Mensch mitten in der Arbeit unterbricht, lassen Sie einen PostToolUse-Hook, der direkt nach dem Speichern die Richtlinie zurückgibt, und einen Hook, der Fehlschläge erkennt und die Arbeit zurückweist, eingreifen. Der Mensch wartet bis zum nächsten Einschnitt. |
| Am Ende einer Session ist nicht festgelegt, was gelesen werden muss und was nicht |
Weder das Ergebnis noch das Arbeitsprotokoll lesen — bestehen oder nicht bestehen wird allein anhand des exit code von Tests oder Linter entschieden. |
| Ein bereits abgelehnter Vorschlag taucht in der nächsten Session wieder auf |
Fassen Sie alle abgelehnten Entscheidungen in einem einzigen Dokument mit festem Format zusammen. |
| Selbst ein niedergeschriebenes Verbot in einer Zeile wird sowohl zu weit als auch zu eng ausgelegt |
Fügen Sie in dem einen Dokument, das die abgelehnten Entscheidungen sammelt (z. B. non_goals.md), zu jedem Verbot eine Überschrift "Begründung" hinzu, direkt neben der Schlussfolgerung. |
| Das Verbot ist korrekt formuliert, wird aber nicht befolgt, und jedes Mal kommt eine Rückfrage |
Fügen Sie im Dokument der abgelehnten Entscheidungen zu jedem Verbot eine Überschrift "Geltungsbereich" hinzu und listen Sie die verwirrenden Grenzfälle Zeile für Zeile auf. |
| Erhalten mehrere Subagenten dieselbe Anweisung, kommt jeder in einer anderen Form zurück |
Vermerken Sie in der Liste der an einen Subagent delegierbaren Aufgaben ausdrücklich, welche Eingabedateien vor dem Start bereitliegen müssen. |
| Verbote ohne automatisierten Test häufen sich an und bleiben bloßer Text auf einer Seite |
Fügen Sie der Liste im Dokument der abgelehnten Entscheidungen eine Überschrift "maschinell geprüft" hinzu und vermerken Sie zu jedem Eintrag, ob ein entsprechender automatisierter Test (Minitest) existiert. |
| Jede Arbeit der KI endet mit "Bitte öffnen Sie den Bildschirm und prüfen Sie es" |
Richten Sie einen einzigen Smoke-Test mit Playwright ein und entscheiden Sie über Bestehen oder Nichtbestehen anhand des in der Datenbank hinterlassenen Datensatzes, nicht anhand des Bildschirms. |
| Sagt die KI etwas leicht Danebenliegendes, erklärt und korrigiert man es jedes Mal selbst |
Statt dass ein Mensch jede Abweichung erklärt und korrigiert, schreiben Sie den Hinweis in die stderr eines Hooks (exit 2) und in die Fehlermeldungen der automatisierten Tests, sodass er die KI auf diesem Weg erreicht. |
| Die Liste der abgelehnten Entscheidungen wächst immer weiter und droht, irgendwann von niemandem mehr gelesen zu werden |
Fügen Sie am Ende des Dokuments der abgelehnten Entscheidungen einen Abschnitt "nicht übernommene Vorschläge" hinzu und verzeichnen Sie dort die abgelehnten Vorschläge. |
| Die "Bitte immer ausführen"-Zeilen der Instruktionsdatei werden einfach nicht weniger |
Prüfen Sie mit einem automatisierten Abgleich-Test, ob jeder in der Instruktionsdatei als "immer ausführen" markierte Befehl auch in einem pre-commit hook existiert. |
| Selbst wenn genau beschrieben ist, wie es zu tun ist, kommt die Korrektur nicht so zurück |
Statt das Vorgehen vorzuschreiben, definieren Sie pro Anwendungsfall die Eingabedateien, die vor dem Start eines Subagent vorliegen müssen. |
| Einen Fehler zu melden bedeutet jedes Mal, Schritte und Symptome selbst niederzuschreiben |
Richten Sie ein Fehlerformular ein, in das die Person nur einen Satz zum Symptom eingibt, während JavaScript URL, Bedienverlauf und Browserinformationen automatisch erfasst. |
| "Erst einen Plan vorlegen" zu tippen ist selbst eine wiederkehrende Last |
Es ist keine neue Implementierung nötig. Legen Sie ein einziges Design-Dokument an, dann liest die KI die vorhandenen Dokumente und übernimmt dasselbe Format. |
| Gerade die Zeilen, die am meisten befolgt werden sollen, sind am stärksten betont, doch es ist unklar, ob das etwas bringt |
Verzichten Sie darauf, die Wirkung zu messen — zählen Sie stattdessen die Zeilen mit Betonung in der Instruktionsdatei und richten Sie einen automatisierten Test (ein Ratchet) ein, der fehlschlägt, sobald diese Zahl einen Schwellenwert überschreitet. |
| Das Ergebnis eines Subagent kommt in einer anderen Form zurück als erwartet |
Definieren Sie für jeden Anwendungsfall eines Subagent die Abnahmekriterien für dessen Ergebnis — Dateiname, Format, Pflichtfelder — in einem einzigen Dokument. |
| Findet man einen Fehler, will man fragen: "Haben Sie das wirklich gelesen?" |
Statt nachzuhaken, legen Sie den zweiten Satz jeder Anfrage auf die Frage-Vorlage "Ist es nicht so, dass ...?" fest. |
| Auf die erhaltene Antwort mit "das ist es nicht" zu reagieren, macht sie nicht besser |
Statt es selbst anzumerken, zeigen Sie Verbote ohne Alternativvorschlag über einen PostToolUse-Hook direkt nach dem Speichern zusammen mit dem Diff an. |
| Die KI spricht über den Inhalt einer Datei, als hätte sie sie geöffnet, obwohl sie es nicht hat |
Lassen Sie die KI in dem referenzierten Dokument und im Code jeweils zueinander passende marker eintragen, und prüfen Sie mit einem automatisierten Test, ob die marker tatsächlich vorhanden sind. |
| Die KI fragt immer wieder "A oder B?", und die Arbeit stockt, während man sich entscheidet |
Antworten Sie nicht mehr sofort — sorgen Sie stattdessen dafür, dass die Wahl von einem automatisierten Test oder einem Hook entschieden wird. |
| Die KI übernimmt die Review, aber es ist unklar, was dabei nicht betrachtet wird |
Erkennen Sie mit einem von außen zählenden automatisierten Test jeden automatisierten Test, der Dateien durchsucht, aber keine Untergrenzen-Assertion für die Anzahl hat (z. B. assert_operator ... :>=). |
| Screenshots häufen sich an, aber es ist unklar, welcher was überprüft hat |
Lassen Sie vor jeder Bildschirmprüfung zwei Fragen beantworten — "was wird verifiziert" und "warum reicht ein günstigeres Mittel nicht" — und legen Sie eine einseitige Richtlinie fest, die stets die günstigste Option zuerst versucht, in der Reihenfolge Unit-Test → Integrationstest → E2E. |
| Ein Schritt, der eine schriftliche Erklärung verlangt, ist eingerichtet, aber es lässt sich nicht zählen, wie viele Durchläufe ihn übersprungen haben |
Lassen Sie vor einem Screenshot oder E2E-Lauf eine Erklärungsdatei schreiben, die festhält, was verifiziert wird (z. B. tmp/visual_verification.md), machen Sie deren Vorhandensein zur Voraussetzung eines PreToolUse-Hooks, und ohne sie startet weder Screenshot noch E2E. |
| Derselbe Test läuft erneut, obwohl sich der Code nicht geändert hat, und man wartet trotzdem darauf |
Fügen Sie dem Test-Wrapper-Skript eine Option --last hinzu, die das letzte Log erneut anzeigt, sodass kein erneuter Lauf nötig ist. |
| Nichts wurde kaputt gemacht, trotzdem erscheint eine Wand unbekannter Fehler |
Lassen Sie das Test-Wrapper-Skript einen exklusiven Lock setzen (unter Nutzung der Atomarität von mkdir) und den Lauf verweigern, wenn es ihn nicht bekommt. |
| Ein Bericht, der "die Tests bestehen" meldet, erwähnt nicht die Teile, die nie gelaufen sind |
Versehen Sie schwergewichtige E2E-Tests mit einem Bereichs-Tag, überspringen (skip) Sie sie standardmäßig und geben Sie jedes Mal die Liste der nicht gelaufenen Bereiche aus. |
| Im Nachhinein lässt sich nicht erkennen, ob eine Anweisung zum Vorgehen tatsächlich befolgt wurde |
Wenn ein Vorgehen befolgt werden soll, verschärfen Sie nicht die Formulierung der Anweisung — ändern Sie sie stattdessen so, dass die Befolgung eine Spur im Ergebnis hinterlässt (etwa indem für jede geöffnete Datei eine Zeile ausgegeben wird). |
| Ein eingerichteter Wrapper wird mittendrin fallen gelassen und durch den rohen Befehl ersetzt |
Wenn der Wrapper genutzt werden soll, verschärfen Sie nicht die Anweisung — prüfen Sie stattdessen, ob noch ein Grund besteht, auf den rohen Befehl zurückzugreifen, weil dem Wrapper eine Fähigkeit fehlt. |
| Stellt man dieselbe Frage wiederholt, fällt die Antwort jedes Mal anders aus, und beim Zusammenfassen geht etwas verloren |
Geben Sie vor dem Zusammenführen mehrerer Antworten zu einer aus, wie oft jede Art von Befund vorkam — wie viele von wie vielen sie genannt haben. |
| Es lässt sich nicht erkennen, ob eine Zeile mit "falls nötig, tun Sie X" jemals ausgelöst wurde |
Schreiben Sie keine bedingten Anweisungen wie "falls nötig, tun Sie X" — erzwingen Sie den Schritt stattdessen mit einem Hook, der ohne ihn keinen Fortschritt zulässt. |
| Sagt man "Denken Sie noch einmal nach", ändert sich die Antwort, aber es ist unklar, ob die KI wirklich überzeugt ist |
Statt es mit "Denken Sie noch einmal nach" zurückzuweisen, benennen Sie konkret, welche Annahme falsch ist. |
| Nach der Anweisung "Nicht raten" kommt die KI zurück, ohne überhaupt etwas gebaut zu haben |
Geben Sie nicht nur ein Verbot vor — ergänzen Sie es um eine Ausweich-Ausgabe, etwa "falls nichts zutrifft, geben Sie 'nicht zutreffend' aus". |
| Je länger eine gut laufende Unterhaltung fortgesetzt wird, desto mehr Aufwand kostet die Überprüfung |
Beenden Sie die Session an jeder Aufgabengrenze und starten Sie die nächste Aufgabe in einer neuen Session. |
| Alle Ergebnisse sind korrekt, doch Verschwendung, die darin nicht sichtbar wird, häuft sich an |
Sobald die Ergebnisse vorliegen, werten Sie das Arbeitsprotokoll (transcript) selbst einmal per Skript aus. |
| Für die nächste Person hinterlassene Notizen laufen der Realität davon und veralten |
Belassen Sie das Wissen nicht in einem Dokument — betten Sie es in die Fehlermeldung eines automatisierten Tests oder die Stopp-Meldung eines Hooks ein, sodass es genau im nötigen Moment erscheint. |
| Die Ursachensuche geht weiter, und das Lesen läuft auch nach gefundener Antwort weiter |
Zählen Sie im Arbeitsprotokoll Serien von Lesevorgängen, die nichts verändert haben, und formulieren Sie vor Beginn der Suche eine Abbruchbedingung in einer Zeile. |
| Das preisgünstigste Modell wird zum Standard gemacht, ohne zu messen, ob es zum Einsatzzweck passt |
Geben Sie dem günstigeren und dem teureren Modell dieselbe Aufgabe, und entscheiden Sie erst, nachdem Sie getrennt die Runden bis zum Abschluss sowie die neu gelesene, wiederverwendete (cache read) und geschriebene Menge gezählt haben. |
| Wenn etwas nicht funktioniert, greift man zu einem größeren Modell statt zu einem besseren Mechanismus |
Geben Sie dieselbe Aufgabe sowohl dem teureren als auch dem günstigeren Modell, und machen Sie die Stellen, an denen nur das günstigere scheitert, zu einer dauerhaften Prüfung. |
| Recherchen, die die Hauptsession selbst beenden könnte, werden vorsichtshalber an einen Subagent übergeben |
Prüfen Sie vor der Delegation, ob der übergeordnete Agent den nötigen Kontext bereits hat. Falls ja, machen Sie dort weiter; übergeben Sie einem Subagent nur die umfangreiche Lektüre, die dort noch fehlt. |
| Standardmäßig wird die Arbeit einfach in vier Teile gesplittet und gleichzeitig laufen gelassen |
Geben Sie jedem Subagent nur so viel, wie er in einer einzigen Antwort zurückgeben kann. Die Kosten bestimmt nicht die Anzahl der Subagenten, sondern wie viele Umläufe jeder aufgeteilte Subagent mit dem übergeordneten Agenten braucht. |
| Mitten in der Arbeit wird von außen ein "Schauen Sie sich auch das an" eingeschoben |
Warten Sie einen natürlichen Einschnitt der Arbeit ab und bringen Sie die zusätzliche Anfrage dann mit engerem Zuschnitt ein. Wenn Sie die KI selbst nach Lücken fragen, ergänzen Sie stets: "Falls es ausreicht, schreiben Sie das ausdrücklich." Das gibt ihr einen Ausweg (escape hatch), sodass sie keine Lücke erfinden muss. |
| Welches Modell verwendet wird, soll durch einen direkten Vergleich entschieden werden |
Zählen Sie vor dem Vergleich von Modellen, wie viele Hooks oder automatisierte Tests dieser Vergleich an Aufwand kostet. Lassen sich mehr Mechanismen aufschreiben als diese Zahl, richten Sie diese vor dem Vergleich ein. |
| "Es gab keinen Unterschied" wird als Grund benutzt, um die Verifikation abzuschließen |
Zählen Sie vor dem Abschluss mit "Es gab keinen Unterschied" zwei Dinge: Wurden Ergebnisse aus der Auswertung ausgeschlossen (etwa gescheiterte Subagenten), nehmen Sie sie zurück auf und zählen neu; liegt bei mehr als der Hälfte der Punkte unter allen Bedingungen null vor, formulieren Sie die Aufgabe um und messen erneut. |
Inhaltsverzeichnis aller Artikel
Serie für Serie, von der Einführung bis zum letzten Teil.
はじめに —— 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 分前に開いたページに、答えが書いてありました
- あとがき —— 本当の事実はどうでもいい話