Operator Core

Un operatore non 'usa' l'IA da un sito web: la opera dalla sua macchina, con accesso ai suoi file, al suo git e al suo terminale. Questo è Claude Code. Prima di installarlo ti servono tre fondamenta: un terminale dove esegui comandi, un editor (VS Code) dove vedi e modifichi il codice, e un gestore di pacchetti per installare strumenti. Su macOS il terminale è Terminal.app o iTerm2; su Windows usa WSL2 (Ubuntu) perché Claude Code e la maggior parte degli strumenti assumono un ambiente di tipo Unix. Non provare a operare da PowerShell puro: ti costerà il doppio.

Per prima cosa controlla cosa hai. Apri il terminale ed esegui `node --version` e `git --version`. Se `node` non esiste o è inferiore alla v18, installa Node LTS. Su macOS la via pulita è Homebrew: `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` e poi `brew install node git`. Dopo aver installato Homebrew, l'installer ti stampa DUE righe `eval "$(/opt/homebrew/bin/brew shellenv)"` che devi aggiungere al tuo `~/.zprofile` — se le salti, `brew` 'sparisce' quando apri un nuovo terminale. Questo è il primo errore di PATH che incontrerai e conviene capirlo: il PATH è la lista di cartelle dove la shell cerca i comandi; se lo strumento non è in una di esse, la shell dice `command not found` anche se il file esiste sul disco.

Installa Claude Code con `npm install -g @anthropic-ai/claude-code` e verifica con `claude --version`. Se npm si lamenta dei permessi (`EACCES`) NON usare `sudo npm` — ti lascia file di proprietà di root che poi non riesci a cancellare. La soluzione corretta è puntare npm a un prefisso nella tua home: `npm config set prefix ~/.npm-global` e aggiungere `export PATH=~/.npm-global/bin:$PATH` al tuo `~/.zshrc`. Ricarica con `source ~/.zshrc`. Ora `claude` parte e ti chiede di autenticarti con il tuo account Anthropic tramite browser; quel token resta salvato e non lo reinserisci più.

VS Code è la tua finestra sul codice, mentre Claude Code sono le tue mani. Installalo da code.visualstudio.com e, al suo interno, apri la palette dei comandi (Cmd+Shift+P) → 'Shell Command: Install code command in PATH'. Questo ti dà il comando `code .` per aprire la cartella corrente in VS Code dal terminale — il gesto che farai cento volte al giorno. Installa almeno queste estensioni: quella ufficiale del tuo linguaggio, GitLens e un formattatore come Prettier. Non gonfiare l'editor con 40 estensioni; ognuna è superficie di attacco e rumore.

Il flusso di lavoro reale è sempre lo stesso e lo interiorizzerai in questo modulo. Apri un terminale, navighi al tuo progetto con `cd ~/mio-progetto`, scrivi `claude` per avviare la sessione, e in un'altra scheda (o pannello diviso di VS Code) hai l'editor aperto con `code .`. Claude Code propone modifiche, tu le rivedi nell'editor o con `git diff`, e le accetti. Il terminale e l'editor non competono: il terminale è dove avviene l'azione, l'editor è dove verifichi. In MOONKEY LAB, per esempio, una sessione tipica è `cd ~/xop && claude` e gli chiedi di toccare un componente Astro mentre tu guardi il file in VS Code.

Verifica l'intero ambiente con una prova del fuoco prima di dare il modulo per chiuso. Crea una cartella `mkdir ~/lab-01 && cd ~/lab-01`, inizializza git con `git init`, lancia `claude` e chiedigli di creare un `hola.txt` con il tuo nome. Esci da Claude, esegui `cat hola.txt` per confermare che il file esiste su disco, e `code .` per vederlo nell'editor. Se i quattro passaggi funzionano (il terminale naviga, claude parte e scrive, il file compare, VS Code lo apre) il tuo ambiente è operativo. Documenta in una nota personale le versioni esatte che hai installato: quando qualcosa si romperà tra un mese, quella nota ti farà risparmiare un pomeriggio.

CLAUDE.md è un file di testo nella radice del tuo progetto che Claude Code legge automaticamente all'avvio di ogni sessione. Non è documentazione per umani (anche se serve pure a quello): è il contesto che l'IA carica prima di fare qualsiasi cosa. Se il tuo `package.json` dice React ma tu usi Astro, o se hai una regola del tipo 'non aggiungere mai dipendenze senza giustificarle', quel file è dove vive. L'IA non indovina il tuo criterio; tu glielo scrivi una volta e lo riutilizza per sempre.

L'errore del principiante è scrivere un CLAUDE.md generico ('questo è un progetto web, usa buone pratiche'). Questo non aggiunge nulla perché l'IA assume già buone pratiche. Il valore sta nel SPECIFICO e nel NON-OVVIO: quale stack REALE usi (non quello che sembra), quali tabelle del tuo database appartengono a un altro progetto e non deve toccare, quale pattern di i18n segui, cosa si traduce e cosa no. Guarda il CLAUDE.md reale di MOONKEY LAB: ha una sezione '⚠️ Il DB Supabase è CONDIVISO con XHUB IRON' che elenca le tabelle vietate (`iron_*`, `world_*`) e quelle permesse (`profiles, progress, feedback, leads, proofs`). Quell'unica riga evita che l'IA cancelli dati di un altro prodotto. Questo è il tipo di conoscenza che solo tu hai e che il file cattura.

Struttura un CLAUDE.md efficace in sezioni chiare con intestazioni Markdown. Quelle che contano: (1) Visione — una frase su cos'è il progetto. (2) Stack REALE — versioni e strumenti esatti, segnalando dove la realtà differisce dall'apparenza. (3) Modello di sicurezza o di dati — chi può toccare cosa. (4) Convenzioni — nomi, struttura delle cartelle, tipografia, qualsiasi cosa abbia regole. (5) Tono — come deve suonare il testo che genera. (6) Regole di costo — cosa NON fare. In MOONKEY quest'ultima sezione dice letteralmente 'Non aggiungere dipendenze senza giustificazione. Niente JS dove basta HTML/CSS.' — divieti concreti, non consigli vaghi.

La regola d'oro è: ogni riga di CLAUDE.md deve cambiare una decisione. Se una frase non altera ciò che l'IA farebbe di default, toglila. 'Scrivi codice pulito' non cambia nulla. 'Gli href devono essere locale-aware: usa localizedPath(/percorso, locale), mai /percorso grezzo (si rompe sotto il prefisso di lingua)' cambia ogni link che genera. La seconda è oro; la prima è riempitivo. Un CLAUDE.md di 80 righe dense vale più di uno di 300 righe di ovvietà, e consuma meno contesto a ogni sessione.

CLAUDE.md è un documento vivo, non un atto fondativo. Ogni volta che l'IA fa qualcosa di sbagliato in modo sistematico — aggiunge una dipendenza che non volevi, usa il pattern di i18n sbagliato, traduce un termine di marca che non si traduce — quello è un difetto del file, non dell'IA. Torna e aggiungi la regola. Col tempo il file diventa il distillato di tutte le correzioni che hai fatto. In pratica, una buona sessione finisce con 'aggiungi questo a CLAUDE.md così non si ripete'. Tieni anche le cose della tua macchina e le preferenze personali fuori dal CLAUDE.md del repo (quelle vanno nella memoria utente o in un CLAUDE.local.md non versionato): quello del repo lo condivide il team.

Per scriverlo, non partire da un template vuoto. Esegui `claude` nel tuo progetto e chiedigli: 'Percorri la struttura del repo, leggi package.json e i file di config, e proponi una bozza di CLAUDE.md che catturi lo stack reale e le convenzioni che rilevi.' L'IA è bravissima a leggere il tuo stesso codice e a riassumerlo. Poi TU correggi: aggiungi i divieti che lei non può conoscere (le tabelle di un altro progetto, i termini che non si traducono, le decisioni di business) e cancelli il generico. Quel ciclo — l'IA propone dal codice, tu inietti la conoscenza che sta solo nella tua testa — produce un file onesto in venti minuti.

Un prompt non è una domanda: è un'istruzione di lavoro. Quando chiedi a un collega competente di fare qualcosa, non dici 'sistema il login'; dici 'il magic-link di Supabase non reindirizza dopo l'autenticazione, controlla il callback in src/lib/supabase.ts, il problema è probabilmente l'URL di redirect nella config'. Gli dai un ruolo implicito, contesto, focus e un'ipotesi. Un buon prompt fa lo stesso in modo esplicito. I quattro pilastri sono: RUOLO (chi deve essere l'IA: 'sei un ingegnere Postgres che revisiona le RLS'), CONTESTO (cosa deve sapere: lo stack, il file, il vincolo), STRUTTURA (come vuoi l'output: 'restituisci solo l'SQL, senza spiegazione' oppure 'elenca 3 opzioni con i trade-off'), e INTENZIONE (l'obiettivo reale dietro la richiesta, non solo il passaggio).

Il RUOLO non è teatro: cambia quale conoscenza attiva l'IA e quale standard applica. 'Revisiona questo codice' produce una revisione blanda. 'Sei un auditor di sicurezza avversariale: il tuo compito è confutare l'affermazione che questa RLS sia sicura, cerca il percorso di escalation' produce un'analisi completamente diversa, perché gli hai dato una postura. In XCAP, i prompt di research portano il ruolo di 'analista che non mente a sé stesso' proprio perché il bias di default di un modello è compiacere; il ruolo lo contrasta.

La STRUTTURA dell'output è ciò che ti fa risparmiare più tempo e ciò che si dimentica più spesso. Se non specifichi il formato, l'IA ne sceglie uno e di solito è prosa lunga che devi accorciare. Di' esattamente cosa vuoi: 'Restituisci un unico blocco di SQL pronto da incollare, senza commenti né spiegazione.' Oppure 'Rispondi con una tabella a tre colonne: opzione, vantaggio, rischio.' Oppure 'Dammi il diff, non l'intero file.' In MOONKEY, dove il tono è 'chiaro, diretto, senza fumo né emoji', un prompt di generazione di copy include quel vincolo di formato alla lettera, perché altrimenti l'IA aggiunge orpelli che poi cancelli a mano.

L'INTENZIONE è il perché, e sblocca soluzioni che non hai chiesto. Se dici 'aggiungi un indice a questa colonna', l'IA lo aggiunge. Se dici 'questa query impiega 2 secondi nella pagina dell'account e voglio scendere sotto i 200ms; l'indice è la mia prima idea ma sono aperto ad alternative', potrebbe dirti che il vero problema è un N+1 e che l'indice non aiuta. Quando dai l'intenzione, l'IA può mettere in discussione la tua soluzione proposta e offrirne una migliore. Quando dai solo l'ordine, esegue alla cieca.

Un arsenale è una collezione versionata di questi prompt, organizzata per compito, che riutilizzi. Non partire da zero ogni volta: tieni un prompt di 'audit di sicurezza della RLS', uno di 'genera copy nella voce della marca', uno di 'rifattorizza questo componente preservando il comportamento', uno di 'scrivi il messaggio di commit a partire dal diff'. Salvali in un file `prompts.md` nel tuo progetto o in una nota. MOONKEY LAB ha una pagina intera, `/prompts`, dedicata a questo, perché un arsenale è un asset: ogni prompt affinato è lavoro che non ripeti. Parametrizza i prompt con segnaposto `[FILE]`, `[VINCOLO]` che riempi quando li usi.

Itera il prompt, non l'output. Quando un risultato esce male, il riflesso del principiante è correggere la risposta a mano. Il riflesso dell'operatore è chiedersi 'cosa è mancato al prompt come informazione' e sistemare il prompt. Se l'IA ha usato i tab e tu vuoi gli spazi, non modificare il file: aggiungi 'indentazione con 2 spazi' al prompt e salvalo così per sempre. Ogni correzione che metti nel template è una correzione che non rifai più. Col tempo i tuoi prompt dell'arsenale diventano chirurgici e i risultati escono bene al primo colpo — che è l'obiettivo: smettere di iterare.

Git risolve un solo problema, ma è il più importante: poter tornare a qualsiasi stato precedente del tuo progetto. Ogni volta che fai un `commit`, congeli una foto del progetto a cui puoi sempre tornare. Questo cambia la tua psicologia di lavoro: quando sai che l'ultimo stato buono è salvato, lasci che l'IA faccia modifiche aggressive senza paura, perché il peggio che può succedere è `git restore` e torni indietro. Un operatore senza Git lavora con paura; con Git, lavora veloce. Il flusso minimo è: `git status` per vedere cosa è cambiato, `git add -p` per revisionare e scegliere le modifiche pezzo per pezzo, `git commit -m 'messaggio'` per congelare, e `git log --oneline` per vedere la tua storia.

Il ciclo quotidiano è vedere-revisionare-congelare. Dopo una sessione di Claude Code, NON fidarti MAI che la modifica sia corretta: esegui `git diff` e leggi esattamente cosa ha toccato. È qui che scopri se l'IA ha cambiato qualcosa che non doveva, ha cancellato una riga per sbaglio o ha aggiunto una dipendenza. `git diff` è il tuo strumento di revisione numero uno e lo usi a ogni sessione. Solo quando il diff ti convince, fai `git add` e `git commit`. Questa abitudine — leggere il diff prima di accettare — è ciò che separa un operatore da chi copia e incolla alla cieca.

I commit devono essere atomici: un commit, una modifica logica, con un messaggio che spiega il PERCHÉ, non il cosa. 'Sistema il login' è pessimo (cos'aveva?). 'Corregge il redirect del magic-link: l'URL di callback non includeva il locale e si rompeva sotto /en/' è buono: tra sei mesi, quel messaggio ti dice perché hai toccato quel file. Claude Code è eccellente nello scrivere messaggi di commit a partire dal diff — chiedigli 'scrivi un messaggio di commit per queste modifiche spiegando il perché' e di solito ci azzecca. Ma controlla: a volte descrive il cosa e devi chiedergli il perché.

I branch (`branches`) sono universi paralleli per sperimentare senza toccare ciò che funziona. Il branch principale (`main`) è la tua versione stabile. Quando stai per provare qualcosa di rischioso — una rifattorizzazione grande, una nuova feature — crei un branch con `git checkout -b mio-esperimento`, ci lavori, e se va bene lo fondi; se va male, lo cancelli e `main` non se ne accorge nemmeno. Regola pratica da operatore: non lavorare mai direttamente su `main` per modifiche non banali. Crea un branch. In MOONKEY LAB ogni modifica di sicurezza o di RLS va nel suo branch e si fonde solo quando `get_advisors` dà il via libera.

GitHub è Git nel cloud: il tuo backup remoto e il posto da cui si fa il deploy del tuo progetto. Connetti il tuo repo locale con `git remote add origin git@github.com:utente/repo.git` e carichi con `git push`. Da quel momento, `git push` dopo ogni sessione buona salva il tuo lavoro fuori dalla tua macchina — se il tuo disco muore, il tuo progetto vive. Inoltre, piattaforme come Cloudflare Pages (che fa il deploy di MOONKEY LAB da `garciafradepablo-pixel/xop`) osservano il tuo repo GitHub e pubblicano automaticamente ogni push su `main`. Così Git non è solo versionamento: è il motore del tuo deploy, che vedrai nel prossimo modulo. Per parlare con GitHub dal terminale, installa la CLI `gh` e autenticati con `gh auth login`.

Un `.gitignore` è importante quanto i commit: elenca i file che Git deve IGNORARE. Qui vanno `node_modules/` (si reinstalla da package.json, non si versiona), i file `.env` (segreti — MAI caricare chiavi su GitHub), e gli artefatti di build. Caricare un `.env` con una chiave in un repo pubblico è uno degli incidenti di sicurezza più comuni al mondo, e una volta caricata la chiave, anche se cancelli il commit, resta nella storia: bisogna ruotarla. Per questo il `.gitignore` si configura PRIMA del primo commit. Chiedi a Claude Code 'genera un .gitignore per un progetto Astro con Supabase' e controlla che includa `.env` e `node_modules`.

L'automazione inizia nel piccolo: un comando che ripeti diventa uno script. Se ogni volta che finisci scrivi `npm run build && git add -A && git commit -m wip && git push`, quello è uno script `deploy.sh` di quattro righe che esegui con `./deploy.sh`. Il principio è: ciò che fai più di tre volte, lo salvi. Chiedi a Claude Code 'crea uno script bash che faccia build, commit con timestamp e push, e che si interrompa se il build fallisce' — il `&&` tra i comandi garantisce già che se uno fallisce, i successivi non girano, che è esattamente ciò che vuoi in un deploy.

Il deploy moderno di un sito statico è quasi gratis da montare e si chiama deploy continuo. Piattaforme come Cloudflare Pages osservano il tuo repo GitHub: ogni volta che fai `git push` su `main`, clonano il tuo repo, eseguono il tuo comando di build (`npm run build` per Astro), e pubblicano il risultato su un URL reale. MOONKEY LAB funziona esattamente così: `git push` al repo `garciafradepablo-pixel/xop` e qualche secondo dopo le modifiche sono su `moonkeylab.pages.dev`. Non carichi file via FTP, non tocchi un server: il tuo unico gesto di deploy è `git push`. Questo unisce il modulo di Git con questo: Git non solo versiona, è il grilletto del deploy.

Configurare il deploy continuo è un processo da fare una sola volta. Connetti il tuo account Cloudflare (o Vercel, o Netlify) a GitHub, scegli il repo, e dichiari due cose: il comando di build (`npm run build`) e la cartella di output (`dist` in Astro). Cloudflare salva quella config e da lì ogni push fa partire un build. Se il build fallisce, NON pubblica — il tuo sito precedente resta vivo. Questa è una proprietà di sicurezza enorme: un commit rotto non butta giù il tuo sito, semplicemente non viene fatto il deploy e ti avvisa. Vedrai il log del build nel pannello di Cloudflare; quando qualcosa fallisce nel deploy ma funziona in locale, quel log è la prima cosa che leggi.

Le variabili d'ambiente sono il ponte tra il tuo deploy e i tuoi segreti, e qui si incrocia con la sicurezza. Il tuo codice ha bisogno dell'URL di Supabase e della anon key, ma quelle NON vanno hardcoded nel repo (l'hai visto nel modulo di Git). In locale vivono in un `.env`; nel deploy le metti nel pannello di Cloudflare come variabili d'ambiente, e la piattaforma le inietta nel build. Distinzione critica che imparerai a fondo in Ops & Security: la anon key di Supabase PUÒ vivere nel client (è protetta da RLS), ma una service-role key MAI — quella darebbe accesso totale saltando tutta la sicurezza. Sapere quale chiave va dove è competenza da operatore.

Il livello successivo è automatizzare compiti ricorrenti che non dipendono da un push: cose che devono girare secondo un orario. Questi sono compiti programmati (cron). In XCAP, per esempio, ci sono gli 'autopilot ticks' — loop che girano periodicamente per ingerire dati di mercato e aggiornare il ledger di Market Memory senza che nessuno prema un pulsante. L'idea generale: definisci un comando e un orario ('ogni giorno alle 6:00', 'ogni 15 minuti'), e la piattaforma lo esegue da sola. Per un sito statico questo di solito vive in funzioni serverless (Cloudflare Workers) o in cron job. La chiave da operatore è che il loop sia onesto e idempotente: che girare due volte non duplichi dati, e che accumuli apprendimento invece di rumore — esattamente la disciplina del 'capital invariant' di XCAP, dove lo stato cambia solo in eventi reali, non a ogni tick.

Automatizzare senza osservabilità è pericoloso: un sistema che gira da solo e fallisce in silenzio è peggio di uno manuale. Per ogni automazione, abbi un modo per sapere se ha funzionato. Il build di Cloudflare ti manda una email se fallisce. Un compito cron deve loggare il suo risultato da qualche parte che tu controlli. La regola: non automatizzare mai qualcosa che non puoi verificare dopo. Inizia sempre da una versione che gira e ti avvisa, e solo quando ti fidi la lasci girare davvero da sola. Un deploy automatico senza revisionare il log la prima volta è come si pubblica un sito rotto in produzione senza accorgersene.

La differenza fondamentale non è di modello, è di paradigma. ChatGPT è una conversazione: tu scrivi, l'IA risponde con testo, e tu copi quel testo nel tuo progetto a mano. Il contesto vive nel thread, e quando il thread cresce troppo o lo chiudi, quel contesto evapora. Claude Code è un operatore: vive nel tuo terminale, legge e scrive i tuoi file direttamente, esegue comandi, fa commit. Il contesto non vive in una conversazione effimera — vive in CLAUDE.md e nel tuo repo, che sono permanenti e versionati. Migrare significa spostare la tua conoscenza da un posto che si cancella a uno che persiste.

Inizia controllando quale contesto prezioso hai intrappolato in ChatGPT. Probabilmente ci sono thread dove hai definito lo stack di un progetto, decisioni di architettura, convenzioni di stile, prompt che ti hanno funzionato bene. Tutto questo è un asset che ora esiste solo nei thread. Il primo passo della migrazione è estrarlo: percorri le tue conversazioni importanti ed estrai le decisioni durature (non l'intera chat, le conclusioni). 'Usiamo Astro, non React, per X', 'il tono è diretto senza emoji', 'il DB lo condivido con un altro progetto e queste tabelle sono intoccabili'. Questo è esattamente il materiale di un CLAUDE.md.

Il cuore della migrazione è costruire il CLAUDE.md a partire da quel contesto estratto. Ciò che in ChatGPT dovevi ripetere all'inizio di ogni thread ('ricorda che uso Astro e Supabase e il tono è...'), in Claude Code lo scrivi una volta in CLAUDE.md e si carica da solo a ogni sessione, per sempre. Questo si collega direttamente al modulo OC-02: la migrazione non è altro che riversare il contesto disperso dei tuoi thread nel file di memoria persistente. Un buon esercizio è chiedere a ChatGPT stesso: 'riassumi tutte le decisioni tecniche e le convenzioni di questo thread in formato bullet per un file di contesto' — e usare quell'output come bozza.

Cambia anche il tuo modo di chiedere le cose. In ChatGPT chiedi 'scrivimi il codice per X' e ricevi un blocco che incolli. In Claude Code chiedi 'crea il file src/lib/x.ts che faccia X, seguendo le convenzioni di CLAUDE.md, e mostrami il diff' — l'IA crea il file al suo posto, tu revisioni il diff con git, e fai commit. Il gesto del copia-e-incolla scompare. Questo richiede di disimparare un'abitudine: smettere di trattare l'IA come un generatore di testo e iniziare a trattarla come un collaboratore che agisce sul tuo progetto. All'inizio costa fidarsi che tocchi i file corretti; per questo `git diff` e i commit del modulo OC-04 sono la tua rete di sicurezza.

Migrare bene significa montare l'intero sistema, non solo cambiare strumento. Il sistema di un operatore è: un repo con git, un CLAUDE.md con il contesto, un .gitignore che protegge i segreti, un arsenale di prompt in un prompts.md, e il deploy continuo connesso. Quando hai questi cinque elementi, hai smesso di 'usare un'IA' e hai montato un'operazione. Ognuno dei moduli precedenti di Operator Core era un pezzo; questo modulo li assembla migrando un progetto reale dal caos dei thread di ChatGPT fino a quel sistema documentato. Il risultato è che qualsiasi sessione nuova — tua o di un collaboratore — parte con tutto il contesto caricato.

Il valore che sentirai subito è la continuità. In ChatGPT, riprendere un progetto dopo una settimana significa rileggere i thread e ricordare dov'eri. Nel sistema migrato, apri il terminale, `cd` al progetto, `claude`, e l'IA già sa lo stack, le convenzioni e i divieti perché sono in CLAUDE.md; tu vedi dov'eri in `git log`. Il progetto si documenta da solo. Quella continuità è ciò che permette di operare molti progetti in parallelo senza che si mescolino — come serve quando porti avanti XNLAB, XHUB, XCAP, Espejo e questa scuola in parallelo: ognuno con il suo CLAUDE.md, il suo repo e il suo contesto isolato, tutti operati con lo stesso flusso.

Verifica NON è testing automatizzato, e NON è solo di sicurezza. È la disciplina generale di provare che una modifica si comporta come ti aspetti PRIMA di pubblicarla. Ha quattro livelli che si applicano in ordine e quasi mai ti servono tutti e quattro: (1) compila / parte senza errore? (2) il diff dice ciò che credevi di chiedere? (3) il comportamento osservabile è cambiato come ti aspettavi? (4) hai rotto qualcosa che prima funzionava (regressione)?

Il livello economico e obbligatorio: LEGGERE IL DIFF. Prima di accettare nulla, `git diff` (o il pannello di diff dell'editor). Claude Code è eccellente nel descrivere ciò che ha fatto e mediocre nel rivelare ciò che ha fatto in più: un file che non hai chiesto di toccare, un `console.log` dimenticato, una dipendenza aggiunta, un blocco cancellato "di passaggio". Se il diff tocca più di quanto la tua frase chiedeva, quello è un segnale, non una coincidenza. Regola: non accettare mai una modifica il cui diff non capisci riga per riga.

"Sembra che funzioni" è una bugia comoda con tre facce. Faccia 1: è partito senza errore → confondi 'non crasha' con 'fa la cosa giusta'. Faccia 2: l'ho provato una volta con il caso felice → non hai provato l'input vuoto, il duplicato, l'utente senza permesso. Faccia 3: l'IA mi ha detto che l'ha verificato → l'IA non ha eseguito nulla, ha predetto testo. L'antidoto è sempre lo stesso: osservare il comportamento reale con i tuoi occhi, non accettare il resoconto di chi ha fatto la modifica (né umano né IA).

Smoke test = il percorso più corto che dimostra che il pezzo centrale respira. Non è copertura totale; è il 20% di prove che catturano l'80% dei disastri. Per un sito web: lancia `npm run dev`, apri la rotta che hai toccato, fai l'azione principale, guarda che succeda ciò che ti aspetti. Per uno script: eseguilo con un input noto e confronta l'output con ciò che SAI debba dare. Definisci lo smoke test PRIMA di chiedere la modifica, non dopo, per non ingannarti aggiustando la prova al risultato.

Asserzione sopra l'osservazione: non guardare lo schermo cercando conferma, definisci in anticipo l'affermazione falsificabile. Male: "vediamo se carica bene". Bene: "inviando il form senza email, deve comparire l'errore 'email richiesta' e NON deve essere inserita una riga in `leads`". Una buona verifica si può scrivere come una frase che sarebbe chiaramente falsa se la modifica fosse fallita. Se non riesci a scrivere quella frase, non sai cosa stai verificando.

Regressione: la modifica nuova spesso rompe quella vecchia. La domanda che separa il senior dal junior non è "la mia feature funziona?" ma "cosa funzionava prima che la mia modifica potrebbe aver rotto?". In questa scuola, toccare `galaxy.ts` può rompere la mappa SVG e tutte le pagine di costellazione, perché si generano dallo stesso file. Prima di pubblicare, elenca mentalmente quali ALTRE cose dipendono da ciò che hai toccato e verificane almeno una.

Come usare Claude Code COME verificatore, senza delegargli il giudizio: chiedigli di eseguire il comando reale (`npm run build`, il test, lo script) e di incollarti l'OUTPUT grezzo, non il suo riassunto. "Esegui il build e incollami l'output completo" è verificabile; "il build funziona?" invita all'allucinazione compiacente. L'IA verifica eseguendo e mostrando evidenza; tu verifichi leggendo quell'evidenza. Mai il contrario.

Verifica proporzionale al rischio (non ogni verifica costa uguale). Cambiare un testo di copy: leggere il diff basta. Toccare la RLS, un trigger di Postgres o il flusso di pagamento: build + smoke + regressione + revisione degli advisors. L'operatore maturo calibra lo sforzo di verifica al costo di sbagliare, non verifica tutto allo stesso modo né si fida di tutto allo stesso modo.

I segnali di degradazione del contesto, in ordine di comparsa: (1) l'IA ti chiede di nuovo qualcosa a cui hai già risposto; (2) re-implementa codice che già esisteva o annulla una modifica concordata; (3) le sue risposte diventano generiche, perdono i nomi concreti del tuo progetto; (4) modifica il file sbagliato o inventa percorsi. Appena vedi il segnale 1-2, sei nella zona rossa. Non aspettare il segnale 4: lì stai già ripulendo un disastro, non avanzando.

L'intuizione corretta è controintuitiva: quando la sessione deraglia, fermarsi e ripartire è PIÙ VELOCE che insistere. Combattere contro un contesto saturo è interesse composto negativo: ogni turno aggiunge rumore al rumore. La domanda non è "come glielo spiego meglio?" ma "questo contesto mi aiuta ancora o ormai mi ostacola?". Se ostacola, la soluzione non è un prompt migliore, è un contesto nuovo.

L'handoff: come ripartire SENZA perdere lo stato. Prima di chiudere una sessione deragliata, chiedi il riassunto di passaggio: "Riassumi in un blocco cosa stavamo cercando di fare, quali decisioni abbiamo preso, quali file abbiamo toccato, cosa è rimasto in sospeso e qual è il prossimo passo concreto". Quel blocco è il tuo stato portatile. Sessione nuova → incolli il riassunto → Claude Code riparte con contesto fresco e memoria di ciò che conta, senza trascinarsi dietro il rumore. L'handoff trasforma un riavvio a perdita totale in un riavvio a costo quasi zero.

La tua memoria persistente vive su disco, non nella finestra. Ciò che conta davvero non deve vivere solo nella chat: vive in `CLAUDE.md` (decisioni di progetto, convenzioni, cosa NON toccare) e in file di note del repo. Una sessione nuova che legge il tuo `CLAUDE.md` già sa l'essenziale. Regola: se una decisione ti servirà domani, non lasciarla nella chat — scrivila in `CLAUDE.md`. La finestra di contesto è RAM volatile; il repo è il tuo disco.

Prevenzione: sessioni corte e di focus unico superano la maratona. Una sessione = un obiettivo circoscritto. "Sistema la verifica della RLS" è una buona sessione; "rifattorizza tutto il backend" è una maratona che si degraderà a metà. Quando un compito è grande, lo spezzi in sessioni indipendenti con handoff tra loro, non lo metti intero in una finestra che non regge.

Delega ai subagenti: parallelismo e isolamento del contesto. Un subagente è una sessione figlia con la PROPRIA finestra di contesto, a cui dai un compito circoscritto e un deliverable definito. Due guadagni: (1) lavoro in parallelo — un subagente fa l'audit della sicurezza mentre un altro scrive i test; (2) isolamento — il subagente brucia il suo contesto investigando un file enorme e ti restituisce solo il riassunto, senza contaminare la tua sessione principale. Deleghi ciò che è voluminoso da esplorare ma compatto da riportare.

Come scrivere un buon incarico per un subagente: come se il subagente non avesse memoria della tua conversazione — perché non ce l'ha. Percorsi assoluti, contesto autocontenuto, e un deliverable esplicito ("restituiscimi X"). Un incarico vago a un subagente è peggio che non delegare: sprechi un'intera finestra per ricevere spazzatura generica. Il subagente brilla in compiti dal confine chiaro, non in "aiutami con questo".

Recuperare il filo quando Claude Code si perde a metà compito: non continuare a spingere. Fermati, chiedigli di dirti con PAROLE SUE cosa crede di stare facendo e perché. Se la sua versione non coincide con la tua, lì sta la deriva — correggila esplicitamente o fai handoff a una sessione pulita. L'opzione peggiore è quella del principiante: dare altre istruzioni sopra un modello che ha già capito male, accatastando correzioni su un malinteso di base.