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 conclude 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 finire. Consulta Orienta 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. Da medium in su, il modello ragiona brevemente prima di quasi ogni risposta, anche a un saluto, il che aumenta il tempo prima del primo token visibile. Chiedergli nel prompt di sistema di ragionare meno non riduce in modo affidabile il suo ragionamento. Con low, salta il ragionamento nella maggior parte delle richieste semplici.

Modificare il valore effort di primo livello tra una richiesta e l'altra invalida la cache dei prompt. Per eseguire singoli turni a un livello diverso, usa invece una modifica dell'effort per messaggio (beta), che mantiene la cache. Ad esempio, esegui una sessione interattiva con low e aumenta l'effort a high quando l'utente sottopone un problema difficile. Le modifiche dell'effort per messaggio richiedono il ragionamento adattivo. Con between_tools, restituiscono un errore 400, come spiegato in 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 conformi alle convenzioni del tuo repository, anche quando non li richiedi. Lo fa a ogni livello di effort, e di più con un 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 esplicitamente richiesto, 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 scrupoloso. Dopo aver completato un'attività, può avviare propri cicli di revisione e verifica, a volte con "subagents" (sottoagenti) se il tuo harness li mette a disposizione. Può anche apportare correzioni correlate che ha notato lungo il percorso. Questo richiede più tempo e token, quindi esegui il lavoro di routine con high o inferiore, dove accade raramente. Se desideri la maggiore accuratezza 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 sub-agents 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 creare 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. Istruzioni di questo tipo 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 l'impostazione predefinita 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 per un'attività che richiede alcuni passaggi di elaborazione. Alcuni esempi sono 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 "structured outputs" (output strutturati) dove sono disponibili. Il testo della risposta è quindi un 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 fino a raggiungere max_tokens. Con effort high e superiore, questo non accade quasi mai. Considera 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 Calibra 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 considera 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 correttamente, prosegui dalla fine di quel valore, in modo che i valori annidati al suo interno non vengano conteggiati separatamente. Conserva l'ultimo valore trovato. Non prendere tutto dalla prima { all'ultima }. Il modello occasionalmente scrive una bozza prima del JSON finale, e quell'intervallo li includerebbe entrambi. Se la tua risposta è composta da più valori JSON consecutivi, ad esempio un record per riga, conserva l'ultima sequenza di valori separati solo da spazi, virgole o interruzioni di riga. Verifica che il risultato contenga i campi che ti aspetti e riprova una volta se non è così. Nei test, questo ha reso utilizzabile quasi ogni risposta senza modificarne l'accuratezza.
  • 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 vengono restituite con il testo del riepilogo, quindi non è necessario alcun campo display. between_tools non accetta altri campi: display, budget_tokens o block_binding inviati insieme a esso restituiscono un errore 400. La guida alla migrazione 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 contenuti di questo tipo. Dichiara lo strumento nella prima richiesta della sessione, in modo che l'elenco tools non cambi in seguito.

Successivamente, rimuovi le istruzioni precedenti come "conserva tutti i risultati per la risposta finale". Se poi desideri aggiornamenti in punti prevedibili, ad esempio una riga su cosa il modello sta per fare prima della sua prima chiamata a uno strumento e un breve riepilogo alla fine, indicalo nel prompt di sistema. Il modello segue istruzioni di questo tipo. Gli aggiornamenti in punti prestabiliti sono particolarmente utili nel lavoro "human-in-the-loop" (con supervisione umana).

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 passaggi consecutivi, ad esempio cinque, aggiungi un promemoria valido per un turno dopo gli ultimi risultati degli strumenti. Invialo come messaggio di sistema limitato al turno (beta), con un testo come questo:

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. Un testo frequente dell'harness dopo i risultati degli strumenti può far sospettare al modello una "prompt injection" (iniezione di prompt), 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 poi eliminato, la cache dei prompt e il ragionamento preservato restano intatti. Con effort high, con a disposizione uno strumento per inviare un messaggio all'utente, il promemoria porta il modello ad aggiornare l'utente più spesso e accorcia i suoi periodi di silenzio più lunghi, senza variazioni misurabili nella qualità dell'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 se il tuo prompt contiene 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 comportamento. Lo stesso vale se consenti agli utenti di inviare messaggi mentre il modello è a metà di un turno in più passaggi, o se il tuo harness aggiunge istruzioni o contesto dopo i risultati degli strumenti a ogni passaggio. In ciascun caso, il testo arriva subito dopo i risultati degli strumenti. Con un conto alla rovescia o con istruzioni a ogni passaggio, questo può accadere a ogni chiamata a uno strumento. Un promemoria occasionale valido per un turno, come quello in Aggiornamenti sui progressi per l'utente, arriva molto meno spesso. Se noti questa reazione a un tuo promemoria, invialo 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 task budget (beta) aggiungono un conto alla rovescia simile, ma non è stato osservato che causino questa errata interpretazione. Se la noti mentre è impostato un task budget, 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 (e.g. npm install, pip install -r requirements.txt), never via 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 contribuire allo 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 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 (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").

Was this page helpful?