Prompt seri su Claude e Claude Code: il loop

C'è una cosa che noto ogni volta che guardo qualcuno usare Claude per la prima volta in modo serio: il salto di qualità non arriva quando impara una tecnica nuova, arriva quando smette di pensare al prompt come a un messaggio e inizia a pensarlo come a un'istruzione di lavoro. Sono due categorie diverse di scrittura. Una la ascolta una persona che ti risponde subito; l'altra la esegue un sistema che, in molti casi, andrà avanti da solo per dieci minuti prima di farti rivedere qualcosa.

Voglio raccontare come scrivo i prompt che funzionano davvero — su Claude in chat e su Claude Code dalla riga di comando — e perché i due strumenti, che a un occhio distratto sembrano lo stesso modello con un'interfaccia diversa, in realtà chiedono due discipline opposte.

Una distinzione che cambia tutto: one-shot contro loop

Quando scrivi a Claude nella web app, fai una domanda e ricevi una risposta. È un turno. Anche se la conversazione è lunga, ogni tuo messaggio è un'unità singola che produce un output singolo. Il modello legge, scrive, si ferma. Tu valuti, riprendi, riformuli.

Claude Code è un'altra cosa. Quando gli dai un'istruzione, parte un loop: il modello decide quale tool chiamare (leggere un file, scrivere, lanciare un comando bash, fare una fetch), osserva il risultato, decide la mossa successiva, e itera finché non considera concluso il compito. Tu vedi i passi mentre accadono, ma il modello non si sta fermando per chiederti permesso a ogni iterazione. La tua istruzione iniziale deve reggere anche al passo nove, quando l'agente ha già toccato sei file e sta decidendo se installare una dipendenza.

Questa differenza ha una conseguenza pratica enorme. Un prompt in chat può essere ambiguo: tanto se sbaglia, riformuli e basta. Un prompt per un agente in loop, se è ambiguo, produce dieci minuti di lavoro sbagliato che poi devi disfare. Il costo dell'imprecisione cambia ordine di grandezza.

L'anatomia minima: quattro caselle, non sette

Dimentichiamoci i modelli a sei o sette blocchi che circolano sui caroselli. Il minimo indispensabile sta in quattro caselle:

1. Chi sta rispondendo — il ruolo, abbastanza specifico da pesare sulle scelte di vocabolario e priorità
2. Cosa deve produrre — il deliverable esatto, mai l'argomento
3. Con quale materiale — il contesto fattuale: numeri, vincoli, cosa è già stato provato
4. In quale forma e con quali limiti — lunghezza, struttura, cosa NON fare

Quattro caselle bastano per la stragrande maggioranza dei prompt seri. Quando la posta in gioco sale — analisi complesse, decisioni strategiche, lavoro creativo lungo — aggiungo un quinto pezzo: il come pensare, cioè la strategia di ragionamento che voglio attivare ("ragiona passo passo prima di concludere", "valuta tre alternative e scarta le più deboli", "fai l'avvocato del diavolo sulle tue stesse raccomandazioni"). Ma se le quattro caselle base sono vuote, nessun "ragiona passo passo" salva il prompt.

Esempio pratico, perché senza esempio queste cose sembrano astratte.

Versione che la gente scrive cento volte al giorno:

"Scrivimi una email di onboarding per il mio prodotto."

Versione con le quattro caselle piene:

"Sei la responsabile customer success di un tool SaaS B2B a €19/mese che genera fatture elettroniche per partite IVA italiane. Scrivi un'email di benvenuto di 130 parole per chi si è appena registrato al trial di 14 giorni. Obiettivo: portare l'utente a emettere la prima fattura entro 48 ore. Tono: diretto, niente entusiasmo americano, niente emoji. Una sola CTA: link al wizard di onboarding. Non promettere supporto h24, non parlare di altri piani, non usare la parola 'rivoluzionario'."

Stesso modello, stesso giorno, due output incomparabili. Il secondo non è più intelligente: ha più informazione strutturata su cui lavorare.

(Il numero €19 è illustrativo; serve solo a mostrare come incollare un prezzo reale nel contesto.)

Il contesto è materiale, non cortesia

Il fraintendimento più comune è trattare il contesto come una premessa educata, qualcosa che metti in cima "per dare un'idea". Non è così. Il contesto è la materia prima con cui il modello costruisce la risposta. Senza contesto specifico, attinge alla media statistica del web — che è precisamente quello che produce gli output che ti fanno dire "questo l'avrei scritto io".

Tre abitudini che spostano la qualità più di qualsiasi tecnica.

Numeri, non aggettivi. "Ho un piccolo seguito" è inutile. "420 follower su Instagram, 0 lista email, 3 vendite negli ultimi 30 giorni a €29 ciascuna" è utile. I numeri costringono Claude a calibrare consigli realistici per la tua scala, non a sputare la dispensa per startup serie A. (Anche qui: €29 è un esempio illustrativo.)

Cosa hai già provato e cosa è fallito. "Ho postato ogni giorno su X per due mesi, reach collassato, account sospeso a marzo" risparmia a Claude di consigliarti esattamente la cosa che hai già scoperto non funzionare. È il singolo pezzo di contesto che genera più ROI: gli risparmi il consiglio sbagliato.

Cosa non vuoi. I vincoli negativi pesano quanto quelli positivi. "Non propormi soluzioni che richiedano budget ads", "non suggerirmi di assumere", "non usare il lessico motivazionale americano". Senza vincoli negativi, il modello esplora lo spazio in cui ha più dati di training — che per chi opera in solitaria, in italiano, con budget reale, è quasi sempre la direzione sbagliata.

Cosa cambia davvero su Claude Code

Su Claude Code valgono tutte le regole di sopra, ma ne cambiano tre in modo profondo.

Il prompt definisce un loop, non risponde a una domanda. Stai scrivendo le regole d'ingaggio di una sessione di lavoro che farà N passi non visti da te. Devono reggere al passo 9, non solo al passo 1. Questo significa scrivere istruzioni che continuano a guidare anche quando l'agente ha già letto sei file, modificato due, e sta valutando se serve un terzo.

Le condizioni di stop sono confini d'azione, non limiti di parole. In chat, se Claude scrive troppo, scrolli. In Code, se l'agente decide che per chiudere il task serve refactorare tre moduli e installare un framework, ha appena fatto un danno. Le condizioni di stop diventano: "non modificare file fuori da src/auth/", "non eseguire comandi che scrivono fuori dalla repo", "se serve installare un pacchetto, fermati e chiedi". Sono guardrail, non gentilezze.

Il contesto è ambiente, non testo che incolli. Quello che il modello "vede" in Code include il filesystem, il CLAUDE.md, i tool abilitati, i permessi configurati. Un prompt brillante in una directory mal preparata produce comunque risultati mediocri, perché l'agente sta leggendo uno stato del mondo che non è quello che pensavi.

Stesso esempio, due versioni. Quella che fa danni:

"Aggiungi i test per il modulo auth."

L'agente sceglierà il framework di test che decide lui, lo stile che decide lui, e ti consegnerà qualcosa che probabilmente compila ma che potresti non riconoscere come tuo.

Quella che produce lavoro revisionabile:

"Aggiungi unit test per src/auth/login.ts e src/auth/refresh.ts. Usa Vitest, già configurato in package.json. Segui lo stile dei test in src/users/__tests__/. Coverage obbligatoria su tutti i path di errore. Non modificare i file sotto test, non installare dipendenze nuove. Se trovi un caso ambiguo, ferma il loop e chiedi. A fine lavoro lancia npm test e mostrami l'output completo."

Tre righe in più che fanno la differenza fra "ho generato codice" e "ho un PR revisionabile in cinque minuti".

Come si scrive davvero una sessione: investimento iniziale, iterazione veloce

C'è un errore che fanno quasi tutti quelli che imparano a scrivere prompt strutturati: li scrivono sempre, per ogni messaggio. È un errore meno ovvio del primo, ma costa più tempo.

Il metodo che uso, sia in chat che in Code: un prompt grosso all'apertura della sessione — quello che stabilisce ruolo, contesto, vincoli, output desiderato — e poi prompt brevi e iterativi che lavorano dentro il contesto già stabilito. "Rendi più tagliente l'apertura". "Riscrivilo per pubblico italiano, non americano". "Spiegami perché hai scelto questa metafora". Sono prompt di una riga, ma stanno operando dentro un contesto che vale 800 parole stabilite in apertura.

Su Claude Code la stessa logica vale ancora di più: la prima istruzione fissa lingua dei commit, stile di codice, branch su cui lavorare, file off-limits, comportamento desiderato in caso di ambiguità. Da quel momento i comandi diventano "ora aggiungi la validazione email" e basta. Se ti accorgi che stai ripetendo le stesse istruzioni di contesto a ogni turno, hai sbagliato l'apertura.

Quattro errori che vedo più di tutti

In ordine di frequenza, sono questi.

Dare l'argomento invece del compito. "Parliamo della mia strategia social" non è un compito, è un invito a chiacchierare. "Dammi tre angoli di posizionamento per un account TikTok che vende un PDF a €29 a freelancer over-35" è un compito. La differenza si vede nel primo verbo.

Impilare più cose in un prompt solo. Chiedere email + caption + ad copy + headline in un turno produce quattro cose mediocri al 60%. Chiederle una alla volta, ciascuna costruita sul deliverable precedente, ne produce quattro al 95%. Si scrive un po' più lentamente, si arriva al risultato usabile molto più velocemente.

Chiedere "creatività" senza vincoli. "Sii creativo" è la richiesta meno creativa che si possa fare. La creatività vive nel vincolo: "scrivi un hook di dodici parole massimo, niente domande retoriche, niente parole vuote tipo 'rivoluzionario', e che funzioni letto ad alta voce". Quello è un brief; "sii creativo" è un'abdicazione.

Non fare il debug del prompt. Quando l'output è deludente, il riflesso comune è "oggi Claude fa schifo". Il riflesso corretto è chiedere a Claude stesso: "Quale informazione ti mancava per fare meglio? Cosa avrei dovuto darmi in più nel prompt?". Nove volte su dieci elenca esattamente i pezzi di contesto che non hai fornito. È il debug più veloce ed economico che esista, e quasi nessuno lo usa.

Il contesto è un budget, non uno spazio

Un'ultima cosa che vale per entrambi gli strumenti, e che a Claude Code conta il doppio. Il contesto non è gratis e non è infinito. Ogni token che metti dentro è un token che il modello deve leggere, pesare, integrare. Riempire il contesto di materiale poco rilevante non aiuta: distrae. Tre file letti per intero, quando ne bastava la sezione utile, sono rumore, non ricchezza.

In Code questo si vede a occhio: un agente che legge venti file di cui solo tre rilevanti fa più fatica di un agente che ne legge tre scelti bene. Quando definisci un compito, definisci il perimetro: quali file guardare, quali ignorare, fino a che profondità. Il contesto curato batte sempre il contesto abbondante.

La domanda finale, prima di mandare

Non è il numero di tecniche che usi a separare chi lavora bene con Claude da chi lo subisce. È un'abitudine: rileggere il prompt prima di mandarlo e chiedersi se arrivasse a un collaboratore umano competente, capirebbe in modo univoco cosa deve fare?. Se la risposta è no, il prompt non è pronto, indipendentemente da quanto sembra elaborato. Claude non legge nella tua testa. Legge i tuoi token. Token ambigui, output ambiguo. Token precisi, output che cambia quello che ti sembra possibile fare in un'ora.

Le quattro caselle di questo articolo sono il minimo che ti porta lontano. Quando vuoi il sistema completo dietro il metodo — i sei blocchi estesi del prompt, i ruoli pronti, le checklist di contesto, le cinque strategie di ragionamento con esempi end-to-end e i template per Claude Code — l'ho raccolto in Prompt Anatomy, la guida operativa di YUKIMORI sul prompting con Claude. È pensata per chi vuole smettere di improvvisare e iniziare a lavorare con un sistema riusabile. Prendila qui.