Claude Platform Docs
Best practicePrompt engineering

Scrivere prompt per Claude Sonnet 5.5

Pattern di prompting specifici per Claude Sonnet 5.5: effort, iniziativa e ambito, esecuzione senza ragionamento iniziale, output JSON, aggiornamenti sui progressi, uso degli strumenti, messaggi a metà turno, verifica nelle attività di coding, chiamate agli strumenti, input visivi e rifiuti.

Questa guida tratta i pattern di prompting specifici per Claude Sonnet 5.5. Per le modifiche all’API del modello, consulta Novità di Claude Sonnet 5.5. Per le tecniche valide per tutti gli attuali modelli Claude, consulta Best practice per il prompting.

I prompt esistenti per Claude Sonnet 5 dovrebbero funzionare bene senza modifiche, e i pattern descritti in Scrivere prompt per Claude Sonnet 5 restano un punto di partenza ragionevole. Per il lavoro a lungo orizzonte più difficile, un modello Opus è la scelta migliore. Inizia dalla sezione che corrisponde a ciò che osservi:

Calibra l’effort

L’“effort” (livello di impegno) è il controllo principale di quanto Claude Sonnet 5.5 ragiona e, di conseguenza, di qualità, “latency” (latenza) e costo. I suoi livelli sono stati ricalibrati: un livello non produce la stessa quantità di ragionamento dello stesso livello su Claude Sonnet 5. Esegui una nuova serie di prove con le tue valutazioni invece di riutilizzare l’impostazione che usavi su Claude Sonnet 5. Inizia con high, il valore predefinito nella Claude API, a meno che il tuo carico di lavoro non sia agentico o sensibile alla latenza. Per il coding agentico e l’uso degli strumenti in più passaggi, inizia con medium per le attività ben specificate e passa a high per quelle più difficili o più lunghe. Per la chat e altri lavori sensibili alla latenza, inizia con medium o low, perché un effort più alto comporta un’attesa più lunga prima che inizi la risposta. Aumenta l’effort se la qualità lo richiede.

Un effort più basso cambia anche il modo in cui il modello completa il lavoro agentico. Con low, mantiene il ragionamento breve e può saltare la verifica di una modifica. Consulta Verifica nelle attività di coding. Con low e medium, nelle attività agentiche lunghe, è più probabile che si fermi a chiedere conferma all’utente prima di completare il lavoro. Consulta Orientare iniziativa e ambito.

Tre accorgimenti aiutano:

  • Imposta max_tokens lasciando spazio per il ragionamento e per la risposta che ti aspetti. Il ragionamento viene conteggiato in max_tokens anche quando il suo contenuto non ti viene restituito. Un limite dimensionato per una richiesta senza ragionamento può troncare la risposta. Per il coding agentico, imposta max_tokens a 128.000, il massimo del modello, e usa lo streaming per la risposta.
  • Riserva xhigh e max al lavoro in cui hai misurato un miglioramento della qualità, perché a quei livelli il ragionamento e le risposte diventano molto più lunghi. A quei livelli, between_tools non è accettato, quindi il ragionamento iniziale non può essere disattivato.
  • Per ottenere meno ragionamento, abbassa il livello di effort. Chiedere al modello nel prompt di sistema di ragionare meno non riduce in modo affidabile il suo ragionamento.

Modificare il valore effort di primo livello tra una richiesta e l’altra invalida la cache dei prompt. Per cambiare il livello a metà conversazione, usa invece una modifica dell’effort per messaggio, che preserva la cache. L’effort per messaggio è in beta. Una modifica resta valida per tutti i turni successivi finché un’altra non la sostituisce. Ad esempio, in una sessione interattiva con low, aggiungi una modifica a high prima del problema difficile dell’utente e una modifica di ritorno a low dopo che Claude ha risposto. Le modifiche dell’effort per messaggio richiedono il ragionamento adattivo. Con between_tools, restituiscono un errore 400, come spiega Esecuzione senza ragionamento iniziale.

Orienta iniziativa e ambito

Quanto Claude Sonnet 5.5 procede in autonomia dipende dal livello di effort e dalla richiesta. Con un effort più basso, a volte chiede conferma prima che un’attività di coding sia completata. Con un effort più alto, o con una richiesta aperta, può fare più di quanto richiesto. Orientalo con il livello di effort e con istruzioni nel tuo prompt di sistema.

Portare a termine il lavoro. Nelle attività di coding agentico con effort low e medium, il modello a volte chiede conferma prima che il lavoro sia completato. Potrebbe fermarsi per confermare un piano, porre una domanda a cui potrebbe rispondere da solo, oppure fermarsi dopo una parte di un’attività in più parti per chiedere se continuare. Prova prima un livello di effort più alto. Per far continuare il modello senza modificare l’effort, aggiungi questo al tuo prompt di sistema:

Keep working until everything the user asked for is done, and only stop to ask when you can't go on without the user or before a risky step.

When the work the user asked for is done and checked, stop and report. Don't add features, tests, files, docs, or refactors that weren't asked for. If you think one would help, mention it at the end instead of doing it.

Con questo prompt, il modello porta a termine una parte maggiore del lavoro con effort low e medium, quindi le sessioni a quei livelli durano più a lungo e costano di più. Il prompt non sostituisce le tue regole sulle azioni rischiose o irreversibili. Mantieni quelle regole nel tuo prompt di sistema.

Aggiunte non richieste durante il coding. Il modello tende ad aggiungere test, documentazione e piccoli file di supporto che rispettano le convenzioni del tuo repository, anche quando non li chiedi. Lo fa a ogni livello di effort, e di più con effort più alto. La modifica richiesta in sé resta vicina a quanto chiesto. La maggior parte dei team lo apprezzerà. Se preferisci modifiche limitate a quanto richiesto esplicitamente, aggiungi solo il secondo paragrafo di quel prompt, che inizia con “When the work the user asked for is done.” Con effort xhigh e max, quel paragrafo riduce queste aggiunte e rende le modifiche complessivamente più piccole.

Accuratezza con effort xhigh e max. A questi livelli il modello è particolarmente accurato. Dopo aver completato un’attività, può avviare propri cicli di revisione e verifica, a volte con subagenti se il tuo harness li fornisce. Può anche apportare correzioni correlate che ha notato lungo il percorso. Ciò richiede più tempo e più token, quindi esegui il lavoro di routine con high o inferiore, dove questo accade raramente. Se desideri questa accuratezza extra di questi livelli di effort, ma vuoi indirizzarla sull’attività stessa, aggiungi questo al tuo prompt di sistema:

When the work the user asked for is done and its checks pass, stop and report. Don't start extra rounds of review or hardening on your own, and don't launch reviewer subagents unless the user asked for a review. If you think a deeper review is worth doing, say so at the end.

Nei test su attività di coding con effort max, questo ha impedito al modello di avviare sottoagenti revisori e ha ridotto il costo della sessione di circa un terzo, senza variazioni nella qualità. Rende meno frequenti i cicli di revisione avviati autonomamente dall’agente principale, ma non li elimina del tutto.

Richieste aperte. Quando una richiesta è aperta, ad esempio “mostrami cosa puoi fare con questo”, il modello può iniziare a costruire una presentazione, un report o un video quando volevi solo delle idee. Se vuoi prima idee o un piano, dillo nella richiesta oppure aggiungi questo al tuo prompt di sistema:

When the user asks for ideas, options, or a plan, give them that and stop. Don't start building or changing anything until they say to go ahead.

Esecuzione senza ragionamento iniziale

Per eseguire Claude Sonnet 5.5 senza ragionamento iniziale, invia thinking: {"type": "between_tools"}. È l’impostazione di ragionamento più bassa su questo modello ed è accettata con effort high o inferiore. Se la tua integrazione oggi funziona con il ragionamento disattivato, passa a between_tools e verifica questi punti:

  • Invia between_tools con effort high o inferiore. Con effort xhigh o max, una richiesta con between_tools restituisce un errore 400. Con between_tools, inoltre, l’effort non può cambiare a metà conversazione: un output_config.effort per messaggio diverso dal livello in vigore restituisce un errore 400. Per variare l’effort a ogni turno, usa il ragionamento adattivo. Con between_tools, rimuovi qualsiasi istruzione che dica al modello di non ragionare. Tali istruzioni rendono più probabile che il modello scriva tag XML interni nel suo output visibile.
  • Leggi la risposta in base al tipo di blocco. Con il ragionamento adattivo, una risposta può iniziare con un blocco thinking, il cui campo thinking è vuoto con il valore predefinito display: "omitted". Con between_tools, una risposta può iniziare con un blocco thinking di aggiornamento sui progressi. Non dare per scontato che il primo blocco di contenuto sia testo.
  • Restituisci i blocchi thinking senza modificarli. Con between_tools, le note che il modello scrive tra una chiamata agli strumenti e l’altra vengono comunque restituite come blocchi thinking quando superano una o due frasi. Ogni blocco contiene un riepilogo della nota. Restituiscili senza modifiche insieme al resto del turno dell’assistente. Un blocco che rimandi fornisce al modello la nota completa che ha scritto, non il riepilogo.
  • Usa il ragionamento adattivo per le attività di ragionamento senza strumenti. In una richiesta senza strumenti, between_tools significa che il modello risponde senza ragionare prima. Per le attività che richiedono alcuni passaggi di elaborazione, usa invece il ragionamento adattivo. Consulta Attività di ragionamento con output JSON.

Attività di ragionamento con output JSON

Questa sezione si applica quando chiedi a Claude Sonnet 5.5 una risposta JSON a un’attività che richiede alcuni passaggi di elaborazione. Gli esempi includono sommare cifre da un documento, applicare una regola o ordinare elementi. In attività come queste, il modello spesso risponde senza ragionare prima, in particolare con effort low e medium. Cosa aiuta dipende da come richiedi il JSON. Usa gli output strutturati dove sono disponibili. Il testo della risposta è allora JSON conforme al tuo schema, quindi non c’è nulla da analizzare.

Con gli output strutturati, il testo della risposta contiene solo il JSON, quindi il modello può elaborare il problema solo nel suo ragionamento. Quando salta il ragionamento, può essere meno accurato in queste attività. Queste modifiche aiutano a mantenere alta l’accuratezza.

Chiedi al modello di ragionare prima. Con il ragionamento adattivo, aggiungi questa riga alla fine del tuo prompt di sistema:

Think the problem through before you answer.

Con questa riga, il modello ragiona più spesso prima di rispondere. Con effort high, la riga porta l’accuratezza vicino a quella che il modello raggiunge con xhigh, a fronte di un modesto aumento dei token di output. Con effort low e medium, aumenta l’accuratezza, anche se non fino al livello che il modello raggiunge con high, e l’aumento dei token di output è maggiore.

Oppure usa l’effort xhigh. Con il ragionamento adattivo, xhigh offre la massima accuratezza in queste attività anche senza la riga. Usa più token di output rispetto a high.

Usa il ragionamento adattivo invece di between_tools. In una richiesta senza strumenti, con between_tools il modello non ragiona prima di rispondere. Lì la riga non ha effetto e l’accuratezza in queste attività è inferiore. Usa il ragionamento adattivo per queste richieste, con i passaggi descritti in questa sezione. Nei test, dividere la richiesta in due, una per la risposta e una per il JSON, ha portato a un’elevata accuratezza delle risposte e conformità del JSON, ma con costi e latenza molto elevati.

Con gli output strutturati ed effort low e medium, il modello occasionalmente continua a ragionare finché non raggiunge max_tokens. Con effort high e superiore, questo non accade quasi mai. Tratta come fallita qualsiasi risposta il cui stop_reason sia "max_tokens", anche se il suo testo contiene JSON valido, e riprova. Imposta max_tokens abbastanza alto per il ragionamento e il JSON, come descritto in Calibrare l’effort, ma non più di quanto sei disposto a spendere per un singolo tentativo.

Se non puoi usare gli output strutturati, richiedi invece il JSON nel prompt. Il modello allora spesso elabora il problema nel testo della risposta e scrive il JSON alla fine. Il JSON di solito contiene la risposta corretta, ma un parser che si aspetta che l’intera risposta sia JSON fallisce. Due accorgimenti aiutano:

  • Analizza l’ultimo valore JSON nella risposta. Leggi solo i blocchi text e tratta come fallita una risposta il cui stop_reason sia "max_tokens". A partire da ogni { o [, prova ad analizzare un valore JSON. Quando uno viene analizzato, continua dalla fine di quel valore, in modo che i valori annidati al suo interno non vengano contati separatamente. Conserva l’ultimo valore trovato. Non prendere tutto dal primo { all’ultimo }. Il modello occasionalmente scrive una bozza prima del JSON finale, e quell’intervallo includerebbe entrambi. Se la tua risposta è costituita da più valori JSON consecutivi, come un record per riga, conserva l’ultima sequenza di valori separati solo da spazi, virgole o interruzioni di riga. Verifica che il risultato abbia i campi che ti aspetti e riprova una volta se non è così. Nei test, questo ha reso utilizzabile quasi ogni risposta senza modificarne la precisione.
  • Considera anche l’effort xhigh con il ragionamento adattivo. Il modello allora elabora il problema nel suo ragionamento e restituisce quasi sempre solo il JSON. Il totale dei token di output resta più o meno lo stesso di high, perché l’elaborazione si sposta dal testo della risposta al ragionamento.

Aggiornamenti sui progressi per l’utente

Tra una chiamata agli strumenti e l’altra, Claude Sonnet 5.5 scrive note rivolte all’utente su ciò che ha appena trovato e su cosa farà dopo. Le note più lunghe di una o due frasi vengono restituite come blocchi thinking di aggiornamento sui progressi. Le osservazioni più brevi restano text. Con il valore predefinito di thinking.display, il testo di un blocco di aggiornamento sui progressi è vuoto, quindi un client che visualizza solo i blocchi text può sembrare silenzioso durante un lungo turno agentico. Questo conta soprattutto nelle interfacce di chat e in altri prodotti in cui l’utente segue il lavoro del modello in tempo reale.

Per mostrare queste note, imposta display: "updates" (beta, header thinking-display-updates-2026-08-18). Con between_tools, le note tornano con il loro testo di riepilogo, quindi non serve alcun campo display. between_tools non accetta altri campi: display, budget_tokens o block_binding inviati insieme restituiscono un errore 400. La sezione della guida alla migrazione sul testo tra le chiamate agli strumenti mostra come visualizzare le note. A volte il modello deve mostrare all’utente un testo esatto a metà di un lungo turno, come uno snippet di codice o una domanda a cui ha bisogno di una risposta. Per questo caso, forniscigli un semplice strumento per inviare un messaggio all’utente. Indica al modello di usare quello strumento solo per tali contenuti. Dichiara lo strumento nella prima richiesta della sessione, in modo che l’elenco tools non cambi in seguito.

Quindi, rimuovi le istruzioni più vecchie come “conserva tutti i risultati per la risposta finale”. Se poi vuoi aggiornamenti in punti prevedibili, ad esempio una riga su ciò che il modello sta per fare prima della sua prima chiamata agli strumenti e un breve riepilogo alla fine, dillo nel prompt di sistema. Il modello segue istruzioni di questo tipo. Gli aggiornamenti in punti stabiliti sono più utili nel lavoro human-in-the-loop.

Se i lunghi turni con chiamate agli strumenti restano comunque silenziosi più a lungo di quanto desideri, il tuo harness può sollecitare un aggiornamento. Fagli contare i passaggi consecutivi con chiamate agli strumenti che non inviano all’utente alcun testo o aggiornamento sui progressi. Dopo diversi consecutivi, ad esempio cinque, aggiungi un promemoria valido per un turno dopo gli ultimi risultati degli strumenti. Invialo come messaggio di sistema con ambito di turno (in beta), con un testo come il seguente:

The user hasn't heard from you in a while: say in a few words what you're doing, then continue.

Se il turno resta silenzioso, smetti di inviare promemoria dopo il secondo o il terzo. Testo frequente dell’harness dopo i risultati degli strumenti può portare il modello a trattare quel testo come una possibile prompt injection, come spiegato in Messaggi dell’utente a metà turno. Lascia ogni promemoria in messages nelle richieste successive. Poiché il promemoria viene aggiunto in coda anziché inserito e successivamente eliminato, la cache dei prompt e il ragionamento preservato restano intatti. Con effort high, con uno strumento disponibile per inviare un messaggio all’utente, il promemoria porta il modello ad aggiornare l’utente più spesso e accorcia i suoi tratti silenziosi più lunghi, senza variazioni misurabili nella qualità delle attività.

Uso degli strumenti nella chat e nel lavoro di conoscenza

Nelle attività di chat e di lavoro di conoscenza, Claude Sonnet 5.5 a volte risponde in base alle conoscenze acquisite durante l’addestramento quando una ricerca web rileverebbe dettagli cambiati. Alcuni esempi sono ciò che è consentito, richiesto o addebitato.

Per prima cosa, controlla il tuo prompt alla ricerca di formulazioni che scoraggiano l’uso degli strumenti, come “usa gli strumenti solo quando strettamente necessario” o “riduci al minimo le chiamate agli strumenti”, e rimuovile. Poi, se il tuo prodotto fornisce al modello uno strumento di ricerca, aggiungi questo al tuo prompt di sistema:

Use the search tool to check specifics that may have changed since your training, such as what is allowed, required, or charged, even when you feel confident. For researched work such as a report or a comparison, gather current sources rather than writing from your training knowledge.

Questo conta soprattutto per i prodotti di ricerca e assistenza, dove le risposte dipendono da dettagli aggiornati.

Messaggi dell’utente a metà turno

Claude Sonnet 5.5 è addestrato a resistere alla prompt injection indiretta, ovvero a istruzioni malevole che arrivano tramite i risultati degli strumenti e altri contenuti che legge durante un’attività. A volte tratta un messaggio autentico dell’utente come una possibile iniezione. Supponi che un messaggio digitato dall’utente durante un’attività raggiunga il modello come messaggio di sistema a metà conversazione posizionato subito dopo un risultato di uno strumento, oppure all’interno di un blocco tool_result. Il modello può allora dire all’utente che il risultato dello strumento conteneva un testo che si spacciava per un suo messaggio, e ignorare il messaggio o chiedere all’utente di confermarlo.

Un conto alla rovescia dei token che il tuo harness aggiunge dopo ogni risultato di uno strumento può causare questo. Lo stesso vale per il consentire agli utenti di inviare messaggi mentre il modello è a metà di un turno in più passaggi, o per il far aggiungere al tuo harness istruzioni o contesto dopo i risultati degli strumenti a ogni passaggio. In ogni caso, il testo arriva subito dopo i risultati degli strumenti. Con un conto alla rovescia o istruzioni per ogni passaggio, ciò può accadere a ogni chiamata agli strumenti. Un promemoria occasionale valido per un turno, come quello in Aggiornamenti sui progressi rivolti all’utente, arriva molto meno spesso. Se noti questa reazione a un tuo promemoria, invia il promemoria meno spesso. Per evitare l’errata interpretazione:

  • Non inserire mai testo dell’utente all’interno di un blocco tool_result. È la posizione che il modello interpreta erroneamente più spesso.
  • Consegna l’input dell’utente a metà turno come turno dell’utente. Aggiungi le parole dell’utente come blocco di testo nel messaggio dell’utente che contiene i blocchi tool_result, dopo l’ultimo tool_result.
  • Mantieni gli avvisi dell’harness, come i promemoria, in un messaggio di sistema a metà conversazione separato, dopo le parole dell’utente. Non inserire mai un avviso e le parole dell’utente nello stesso blocco.
  • Nelle sessioni interattive in cui gli utenti possono scrivere a metà turno, non aggiungere un tuo conto alla rovescia dei token o del budget dopo i risultati degli strumenti. I budget delle attività (in beta) aggiungono un conto alla rovescia simile, ma non è stato osservato che causino questa errata interpretazione. Se la noti mentre è impostato un budget delle attività, prova la sessione senza.

Verifica nelle attività di coding

Nelle attività di coding agentico, Claude Sonnet 5.5 in genere verifica il proprio lavoro prima di segnalare una modifica come completata. Con effort low, tuttavia, a volte segnala una modifica come completata senza eseguire un controllo che la metta alla prova. Ad esempio, potrebbe saltare i test del progetto perché le dipendenze del progetto non sono installate.

Se noti modifiche segnalate come completate senza output di test o build nella trascrizione, aggiungi questo paragrafo, o uno simile, al prompt di sistema. Con effort low, rende rari i controlli saltati o superficiali, senza variazioni misurabili nella qualità dell’attività e con un costo per attività solo leggermente più alto:

When you change code that can be run, built, or type-checked, run a real check that exercises the change before reporting it done: the project's tests, type-checker, or build, or the changed command itself. A syntax-only check, or a check command that failed to start, does not count; if all that is missing is the project's declared dependencies, install them with its own package manager and lockfile (for example, npm install or pip install -r requirements.txt), never through sudo or the system package manager, unless told not to. Only if no real check can run here, say which one you did not run and why instead of reporting the change as done.

Gestione tollerante delle chiamate agli strumenti

Claude Sonnet 5.5 occasionalmente chiama uno strumento dichiarato con un nome che differisce solo per maiuscole/minuscole, come bash per Bash. Può anche passare un parametro noto con un nome leggermente diverso. Invece di trattare una chiamata di questo tipo come un errore fatale, fai in modo che il tuo harness la gestisca in uno di questi due modi:

  • Accetta la chiamata quando la corrispondenza è univoca, anche se le maiuscole/minuscole sono errate.
  • Restituisci un tool_result con is_error: true che indichi il nome esatto previsto. Il modello di solito corregge la chiamata nel turno successivo. Consulta Gestione degli errori con is_error.

Strumenti per input visivi complessi

Per grafici densi e disegni tecnici, fornisci a Claude Sonnet 5.5 un modo per ritagliare, ingrandire o eseguire codice sull’immagine. Con strumenti di questo tipo, il modello legge questi input in modo nettamente più accurato. Sui grafici, gli strumenti aiutano a ogni livello di effort. Sui disegni tecnici, aiutano solo da effort high in su, e soprattutto con xhigh e max. Per i grafici, aggiungere strumenti aiuta più che aumentare l’effort: nei test, con gli strumenti ed effort high, il modello ha letto i grafici in modo più accurato rispetto a senza strumenti con effort max, a una frazione del costo. La ricetta dello strumento di ritaglio contiene una definizione di strumento funzionante.

Rifiuti delle misure di salvaguardia

Claude Sonnet 5.5 esegue classificatori di sicurezza che possono rifiutare una richiesta. Un rifiuto arriva come una normale risposta con stop_reason: "refusal", e stop_details.category indica la categoria del rifiuto:

  • cyber: la richiesta potrebbe favorire danni informatici, come lo sviluppo di malware o exploit. La ricerca di vulnerabilità nel codice sorgente è consentita. Il lavoro di cybersicurezza a duplice uso ad alto rischio non è consentito.
  • bio: la richiesta potrebbe favorire danni biologici, come metodi di laboratorio pericolosi. Le domande quotidiane sulla salute e quelle a scopo educativo non sono interessate.
  • frontier_llm: la richiesta potrebbe aiutare lo sviluppo di modelli di IA concorrenti.
  • reasoning_extraction: la richiesta chiede al modello di riprodurre il suo ragionamento interno nel testo della risposta.
  • general_harms: la richiesta rientra in un’altra area delle norme di utilizzo. Anche un lavoro innocuo può attivare questa categoria.

Se il classificatore cyber blocca il lavoro di sicurezza legittimo della tua organizzazione, puoi fare domanda per il Cyber Verification Program. Se il classificatore bio blocca il lavoro della tua organizzazione nel campo delle scienze della vita, puoi fare domanda per il Life Sciences Verification Program.

Se attivi il fallback lato server (in beta), questo ritenta i rifiuti cyber e frontier_llm su Claude Sonnet 5. Non ritenta i rifiuti bio, reasoning_extraction o general_harms. Consulta Rifiuti, fallback e fatturazione.

Se i tuoi prompt chiedono al modello di includere il suo ragionamento nella risposta, rimuovi quelle istruzioni, perché favoriscono i rifiuti reasoning_extraction. Con il ragionamento adattivo, leggi invece il ragionamento dai blocchi di ragionamento riassunto (display: "summarized"). Puoi comunque chiedere una breve spiegazione della risposta o un riepilogo delle azioni intraprese; consulta Mantieni il ragionamento nei blocchi di ragionamento.

Questa pagina ti è stata utile?