Cosa sta succedendo → cosa fare
Si cerca per sintomo, non per titolo. Il link sotto «cosa fare» porta alla sezione che descrive quel rimedio. L'indice completo di tutti gli articoli si trova in fondo a questa pagina.
Questa tabella presuppone Claude Code (l'agente di programmazione di Anthropic). hook, CLAUDE.md, subagent e auto memory sono i nomi delle sue funzionalità.
| Cosa sta succedendo | Cosa fare |
|---|---|
| Ogni volta che l'AI esegue i test, decine di migliaia di righe di output finiscono nel context |
Convogliare tutte le esecuzioni dei test attraverso un unico script wrapper, scrivere l'output completo in un file di log e restituire all'AI solo un riepilogo dei fallimenti. |
| Più note di conoscenza l'AI salva, più aumenta la quantità che ogni sessione futura deve leggere |
Usare un hook PreToolUse che si attiva subito prima di ogni scrittura in memoria per far leggere prima una checklist, e ridurre il file di istruzioni (CLAUDE.md) a una sola riga: "leggi prima di scrivere". |
| I test passano, ma non è chiaro se stiano davvero proteggendo qualcosa |
Scrivere una policy di una pagina sul mutation testing (la tecnica che rompe di proposito il codice per vedere se i test lo rilevano) e farla leggere all'AI ogni volta che le si chiede di revisionare i test. |
| A volte l'AI usa una skill registrata, a volte no |
Lasciare il comando come un normale script, bloccare le invocazioni scorrette con un hook PreToolUse e indicare la documentazione da leggere. |
| Una volta affidato il lavoro a un sub-agent, non si vede cosa sta succedendo finché non finisce |
Definire in YAML quali task possono essere delegati a un sub-agent e quali file di input devono esistere prima dell'avvio, poi verificarlo con un hook prima che parta. |
| Più regole si aggiungono al file di istruzioni, meno vengono rispettate quelle aggiunte prima |
Riscrivere ogni regola del tipo "non fare X", una alla volta, come un test automatico (Minitest) in grado di rilevarne la violazione. |
| La memoria condivisa tra sessioni parallele diventa disordinata, e far leggere la policy non basta |
Spostare lo stesso file di policy in un hook PostToolUse e mostrarlo insieme al diff subito dopo il salvataggio. Il contenuto da leggere resta lo stesso, cambia solo il momento. |
| Anche scrivendo come gestire un certo errore, l'AI ripete lo stesso errore la volta successiva |
Riassumere la policy per i retry in un file di poche righe e farla inserire automaticamente da un hook che rileva l'errore. |
| Anche leggendo le note di handoff e il report finale, le parti scomode mancano sempre |
Affiancare sempre al report finale numeri ottenuti meccanicamente, ad esempio con git diff --stat. |
| Il numero contato dalla macchina cambia in un altro numero prima di arrivare nel report |
Aggiungere un prefisso fisso alla riga con il numero e usare un hook per verificare che sia stato copiato alla lettera. |
| Interrompere l'AI a metà del lavoro manda in tilt tutto ciò che fa dopo |
Invece di far interrompere una persona a metà del lavoro, lasciare che intervengano un hook PostToolUse che restituisce la policy subito dopo il salvataggio e un hook che rileva l'errore e rimanda indietro il lavoro. La persona aspetta un confine naturale. |
| Alla fine della sessione, non è stabilito cosa leggere e cosa si può saltare |
Non leggere né il risultato né il log di lavoro: giudicare solo in base all'exit code dei test o del linter. |
| Una proposta già rifiutata ritorna nella sessione successiva |
Raccogliere ogni decisione respinta in un unico documento, con un formato fisso. |
| Anche con un divieto scritto in una riga, viene interpretato sia in modo troppo ampio sia troppo restrittivo |
Nell'unico documento che raccoglie le decisioni respinte (per esempio non_goals.md), aggiungere una sezione "motivo" a ogni divieto, accanto alla conclusione. |
| Il divieto è scritto correttamente ma non viene rispettato, e ogni volta arriva una domanda a riguardo |
Nel documento delle decisioni respinte, aggiungere a ogni divieto una sezione "ambito di applicazione" ed elencare, una riga alla volta, i casi limite che generano dubbi. |
| Dando la stessa istruzione a più sub-agent, ognuno restituisce un formato diverso |
Nell'elenco dei task che possono essere affidati a un sub-agent, specificare esplicitamente i file di input da preparare prima dell'avvio. |
| I divieti senza un test automatico si accumulano restando solo scritti sulla carta |
Nel documento delle decisioni respinte, aggiungere all'elenco una sezione "verifica automatica" e indicare, voce per voce, se esiste il test automatico (Minitest) corrispondente. |
| Ogni lavoro dell'AI finisce con "apri la schermata e verifica" |
Preparare un unico smoke test con Playwright e giudicare l'esito non dall'aspetto della schermata ma dal record rimasto nel database. |
| Ogni volta che l'AI dice qualcosa leggermente fuori strada, tocca a te spiegare e correggere |
Invece di far spiegare e correggere ogni scostamento a una persona, scrivere la segnalazione nello stderr di un hook (exit 2) e nei messaggi di fallimento dei test automatici, così che arrivi all'AI per quella via. |
| L'elenco delle decisioni respinte continua a crescere e rischia di non essere più letto |
Aggiungere in fondo al documento delle decisioni respinte una sezione "proposte non adottate" e registrare lì le proposte respinte. |
| Le righe "esegui sempre questo" nel file di istruzioni non diminuiscono mai |
Usare un test automatico che verifica se i comandi che il file di istruzioni segna come "da eseguire sempre" esistono anche in un pre-commit hook. |
| Anche scrivendo esattamente come farlo, la correzione non torna fatta in quel modo |
Invece di dettare la procedura, definire per ogni caso d'uso i file di input che devono esistere prima di avviare un sub-agent. |
| Per segnalare un bug, tocca sempre scrivere a mano i passaggi e i sintomi |
Predisporre un modulo di segnalazione bug in cui la persona scrive solo una frase sul sintomo, mentre URL, cronologia delle azioni e informazioni sul browser vengono raccolti automaticamente via JavaScript. |
| Scrivere ogni volta "prima fammi vedere il piano" è una fatica che si ripete |
Non serve nessuna nuova implementazione. Basta un documento di design: l'AI leggerà i documenti esistenti e seguirà lo stesso formato. |
| Le righe che si vorrebbero rispettate di più sono scritte con più enfasi, ma non si sa se serva a qualcosa |
Smettere di misurarne l'effetto e contare invece le righe del file di istruzioni che usano espressioni enfatiche, aggiungendo un test automatico (un ratchet) che fallisce quando il conteggio supera una soglia. |
| Il risultato di un sub-agent torna in un formato diverso da quello previsto |
Per ogni caso d'uso di un sub-agent, definire in un unico documento i criteri di accettazione del risultato: nome del file, formato, campi obbligatori. |
| Trovare un errore fa venire voglia di chiedere "ma l'hai davvero letto?" |
Invece di interrogare, fissare la seconda frase di ogni richiesta sul modello di domanda "non è forse vero che ...?". |
| Rispondere "non è questo" alla risposta ricevuta non la migliora |
Invece di segnalarlo di persona, presentare i divieti privi di alternativa tramite un hook PostToolUse, mostrato insieme al diff subito dopo il salvataggio. |
| L'AI parla del contenuto di un file come se lo avesse aperto, anche quando non lo ha fatto |
Far scrivere marker corrispondenti sia nel documento di riferimento sia nel codice, e verificare con un test automatico che i marker esistano davvero. |
| L'AI continua a chiedere "A o B?" e il lavoro si blocca in attesa di una decisione |
Smettere di rispondere sul momento e far decidere la scelta a un test automatico o a un hook. |
| L'AI sta facendo la revisione, ma non è chiaro cosa non stia guardando |
Usare un test automatico esterno che conta dall'esterno per individuare i test automatici che scansionano file ma non hanno un limite minimo sul conteggio (assert_operator ... :>=). |
| Gli screenshot si accumulano, ma non è chiaro quale abbia verificato cosa |
Prima di controllare la schermata, far rispondere a due domande — "cosa si sta verificando" e "perché un metodo più economico non basta" — e tenere una linea guida di una pagina che privilegia l'opzione più economica, nell'ordine unit test → test di integrazione → E2E. |
| È stato introdotto un passaggio che richiede di scrivere qualcosa, ma non si riesce a contare quante esecuzioni lo hanno saltato |
Prima di uno screenshot o di un E2E, far scrivere un file di dichiarazione che dica cosa si sta verificando (per esempio tmp/visual_verification.md), rendere la sua esistenza una precondizione di un hook PreToolUse, e senza di esso screenshot ed E2E non partono. |
| Lo stesso test viene rieseguito anche senza modifiche al codice, e si perde tempo ad aspettarlo |
Aggiungere un'opzione --last allo script wrapper dei test, che rimostra il log precedente rendendo inutile la riesecuzione. |
| Senza aver rotto nulla, compare comunque una lunga lista di errori mai visti |
Far acquisire allo script wrapper dei test un lock esclusivo (sfruttando l'atomicità di mkdir), ed evitare l'esecuzione se non riesce a ottenerlo. |
| Il report "i test passano" non menziona la parte che non è stata eseguita |
Assegnare ai test E2E pesanti un tag per area e saltarli (skip) di default, stampando ogni volta l'elenco delle aree non eseguite. |
| Non è possibile capire in seguito se un'istruzione che specificava come procedere sia stata seguita |
Per far rispettare una procedura, invece di rafforzare il testo dell'istruzione, modificarla in modo che seguirla lasci una traccia nel risultato (per esempio, far stampare una riga per ogni file aperto). |
| Il wrapper introdotto viene abbandonato a metà, tornando al comando grezzo |
Per far usare il wrapper, invece di rafforzare l'istruzione, verificare se resta ancora un motivo per tornare al comando grezzo, cioè se al wrapper manca qualche funzionalità. |
| Ponendo più volte la stessa domanda, la risposta cambia ogni volta; riassumendo, qualcosa va perso |
Prima di unire più risposte in una sola, stampare per ogni tipo di segnalazione quante volte è comparsa (quante su quante l'hanno sollevata). |
| Non si sa se una riga del tipo "se necessario, fai X" sia mai scattata |
Non scrivere istruzioni condizionali come "se necessario, fai X": imporre invece quel passaggio con un hook che blocca l'avanzamento finché non viene eseguito. |
| Dire "ripensaci" fa cambiare la risposta, ma non è chiaro se l'AI sia davvero convinta |
Invece di rimandare indietro con "ripensaci", indicare in modo specifico quale premessa è sbagliata. |
| Dopo aver scritto "non fare supposizioni", l'AI ha iniziato a tornare senza aver costruito nulla |
Non dare solo un divieto: affiancarlo a un'uscita alternativa, come "se non si applica, scrivi 'non applicabile'". |
| Continuare una conversazione che sta andando bene fa aumentare la fatica di verifica |
Chiudere la sessione a ogni confine tra task e iniziare il task successivo in una sessione nuova. |
| I risultati sono tutti corretti, ma si accumula uno spreco che non compare in essi |
Una volta pronti i risultati, aggregare una sola volta con uno script il log di lavoro (transcript). |
| Le note lasciate per chi verrà dopo perdono aderenza alla realtà e diventano obsolete |
Non lasciare la conoscenza in un documento: incorporarla nel messaggio di fallimento di un test automatico o nel messaggio di blocco di un hook, così che venga mostrata proprio nel momento in cui serve. |
| Si continua a scavare nella causa, e la lettura prosegue anche dopo aver trovato la risposta |
Contare, dal log di lavoro, le sequenze di letture che non hanno cambiato nulla, e scrivere in una riga la condizione di fine prima di iniziare a scavare. |
| Il modello con il prezzo unitario più basso viene impostato come predefinito senza misurarne l'adeguatezza all'uso |
Dare lo stesso compito sia al modello economico sia a quello costoso, poi decidere solo dopo aver contato separatamente i turni fino al completamento e la quantità letta ex novo, riutilizzata (cache read) e scritta. |
| Quando qualcosa non funziona, la soluzione cercata è un modello più potente invece di un meccanismo migliore |
Dare lo stesso compito sia al modello più costoso sia a quello più economico, e trasformare in un controllo permanente i punti in cui fallisce solo quello economico. |
| Una ricerca che la sessione principale potrebbe concludere da sola viene comunque affidata a un sub-agent per sicurezza |
Prima di delegare, verificare se l'agente padre possiede già quella premessa. Se sì, continuare lì; affidare a un sub-agent solo la grande mole di lettura che non possiede già. |
| Per abitudine si divide il lavoro in quattro e lo si fa girare tutto insieme |
Affidare a ciascun sub-agent solo ciò che può restituire in una sola risposta. Il costo non è determinato dal numero di sub-agent, ma da quanti andirivieni fa ciascun sub-agent risultante dalla suddivisione con l'agente padre. |
| A metà del lavoro arriva dall'esterno un "guarda anche questo" |
Aspettare un confine naturale del lavoro e poi introdurre la richiesta aggiuntiva con un ambito ristretto. Quando si chiede all'AI stessa se manca qualcosa, aggiungere sempre: "se è sufficiente, scrivilo esplicitamente". Le lascia una via d'uscita (escape hatch), così non deve inventare una mancanza. |
| Si cerca di decidere quale modello usare confrontandoli direttamente |
Prima di iniziare a confrontare i modelli, contare a quanti hook o test automatici equivale lo sforzo di quel confronto. Se si riescono a scrivere più meccanismi di quel numero, metterli in atto prima del confronto. |
| "Non c'è stata alcuna differenza" viene usato come motivo per chiudere la verifica |
Prima di chiudere con "non c'è stata alcuna differenza", contare due cose: se qualche risultato è stato escluso dal conteggio (per esempio sub-agent falliti), reinserirlo e ricontare; se più della metà delle voci ha zero in tutte le condizioni, riformulare il compito e misurare di nuovo. |
Tutti gli articoli
Serie per serie, dall'introduzione all'ultimo capitolo.
はじめに —— 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 分前に開いたページに、答えが書いてありました
- あとがき —— 本当の事実はどうでもいい話