Anthropic chiude il suo pezzo sulla code review con una regola: quando il reviewer si perde qualcosa, chiediti cosa mancava davanti al modello e metti il fix in un CLAUDE.md, in una skill o in un nuovo check (l'articolo (si apre in una nuova scheda)). Leggendolo, Theo ha detto che è il default sbagliato, e qui sto con lui. Io lavoro così da mesi: cambio il codice perché l'errore diventi difficile da fare, aggiungo un check che lo intercetti, e solo dopo scrivo istruzioni. Prima di smanettare con CLAUDE.md e REVIEW.md, chiediti se l'architettura o il codice vanno cambiati per rendere l'errore impossibile by design. Spoiler: spesso è così.
Le istruzioni sono il posto più fragile per una regola
Un'istruzione la paghi in contesto a ogni sessione, può essere letta nel modo più costoso, e invecchia quando il codice si muove. L'ho imparato sul mio setup. Le mie istruzioni dicevano di usare il modello più forte per le decisioni, e l'orchestratore lo lanciava come subagent anche per il lavoro ordinario. Oggi quella regola è scritta in maiuscolo (la storia). Anche le maiuscole sono parole. Il passo successivo è un check nell'harness che rifiuta quel lancio, come un linter rifiuta un import.
Una traduzione mancante rompe la build
Questo sito è scritto in italiano, inglese e polacco. Avrei potuto dire agli agenti di ricordarsi di tradurre ogni saggio. Invece la build fallisce se un saggio esiste in una lingua e manca in un'altra, così né io né un agente possiamo pubblicare mezza modifica. Questo saggio esiste in tre lingue perché altrimenti il sito non compila.
Nel colophon c'è una riga che sottoscrivo ancora: il contesto minimo sufficiente è una proprietà della repo, non del prompt.
Togli l'opzione sbagliata e mettici una fence
In Intarget, sulla piattaforma agentica, due librerie facevano lo stesso lavoro di prendere dati dal server, ed era facile per persone e agenti scegliere quella sbagliata. Ne abbiamo tolta una, e ora una lint rule fallisce ogni volta che qualcuno la importa di nuovo. Un'istruzione con scritto “usa l'altra libreria” sarebbe stata rispettata, quasi sempre. La lint rule non si aggira con le parole.
La stessa idea in piccolo: nell'agente WhatsApp di CVing ho spostato i check di sicurezza dal prompt al codice che esegue ogni azione (i dettagli). Quello che deve valere sempre va dove il modello non lo può interpretare.
Se l'agente fa review peggio di te, guarda prima la codebase
La hot take di Theo, e la mia: la maggior parte degli agenti oggi fa code review meglio della maggior parte delle persone, e se il tuo non ci riesce sulla tua repo, parti dalla repo. Boris Cherny lo dice dall'altro lato: il codice difficile da controllare fa una codebase difficile da lavorare.
Il test che uso è quello di Theo. Immagina un new hire molto sveglio, che ha lavorato in migliaia di codebase e mai nella tua, e che fa lavoro noioso tutto il giorno senza lamentarsi. Quello che fa inciampare lui fa inciampare anche l'agente, e il fix è lo stesso per entrambi: confini più chiari, nomi che dicono cosa fanno le cose, un solo modo ovvio per fare ogni cosa.
Vale per i modelli frontier con un budget di token vero. Se hai il modello piccolo o un piano con i token contati il limite è davvero il modello, e questo si perdona a tutti. L'ho scritto anche quando ho corretto un mio pezzo precedente.
Lo stesso ragionamento vale per scrivere codice. Se pensi che il tuo valore sia scrivere codice migliore di Opus, stai misurando il lavoro sbagliato. Il mio è architettura, vincoli e criteri di accettazione, e decidere cosa non va costruito affatto.
Le istruzioni cambiano quando cambia il progetto
Theo ha mostrato un numero che mi è piaciuto: le istruzioni per gli agenti della sua repo cambiano circa una volta al giorno, mentre il componente della chat cambia trenta o cinquanta volte al giorno. L'ultima modifica alle istruzioni è arrivata perché la repo era passata a un nuovo setup. È un ritmo sano: le istruzioni descrivono il progetto, e il codice previene gli errori.
Quando code-os, il framework open source che usiamo in Yempik, è passato alla seconda versione, abbiamo tolto le nostre regole duplicate. Ogni duplicato è un'ambiguità in più, pagata in contesto a ogni sessione.
L'obiezione: quindi i file di istruzioni non servono
Servono, e devono essere corti. Il consiglio di Anthropic sul REVIEW.md è buono, e lo seguo: chi possiede una parte del codice scrive che aspetto ha un errore lì (per la documentazione, che mente; per la configurazione, che instrada male), mette un cap ai nit, elenca i percorsi da saltare e chiede un file e una riga come prova. È conoscenza che il codice da solo non riesce a esprimere. L'errore è usarli per rattoppare codice che invita all'errore.
Da lunedì
- Dopo ogni errore ripetuto di un agente, chiediti prima cosa nel codice l'ha invitato.
- Rendi l'errore impossibile dove puoi: tipi, una build che fallisce, una dipendenza tolta con una fence.
- Poi un check: una lint rule, un test, un hook nell'harness.
- Solo dopo una riga nelle istruzioni, e tieni il file corto.
- Usa il new hire molto sveglio come test per la tua codebase.
- Aggiorna le istruzioni quando cambia il progetto.
// la regola in maiuscolo è ancora nelle mie istruzioni. l'hook che la sostituisce è il prossimo della lista.