Claude Opus 5.5, guida al prompting: sforzo, agenti, rifiuti e modelli di prompt

Per scrivere buoni prompt per Claude Opus 5.5, tieni i prompt che usavi con Claude Opus 5, imposta il livello di sforzo (effort) prima di toccare la formulazione e poi aggiungi al prompt di sistema una riga mirata per ogni comportamento che vuoi cambiare. La guida di Anthropic dice che i prompt esistenti per Claude Opus 5 "dovrebbero funzionare bene senza modifiche" e che lo sforzo è "la prima impostazione da regolare per bilanciare intelligenza, latenza e costo". La maggior parte dei consigli nuovi riguarda gli agenti: tenere in funzione un'esecuzione non sorvegliata, ottenere aggiornamenti di avanzamento nei turni lunghi e dare il ritmo a un team di agenti. Tutto ciò che segue viene dalla guida "Prompting Claude Opus 5.5" di Anthropic e dal riferimento API del modello, verificati il 3 ottobre 2026.

Le regole di richiesta condivise con Claude Fable 5.1, come niente precompilazione della risposta dell'assistente e niente temperatura personalizzata, sono nella guida al prompting di Claude Fable 5.1. Questo articolo copre ciò che è specifico di Claude Opus 5.5.

I prompt di Claude Opus 5 funzionano su Claude Opus 5.5?

Sì. Anthropic dice che "dovrebbero funzionare bene senza modifiche" e che gli schemi di prompting di Claude Opus 5 "restano un punto di partenza ragionevole". Cambia il modo in cui il modello distribuisce il suo sforzo. Claude Opus 5.5 genera token di output oltre il 30% più velocemente di Claude Opus 5 e tende a completare lo stesso compito con meno token.

Anthropic indica quattro aree in cui il modello è migliorato, ed è da queste che dipende quali parti di questa guida ti riguardano:

• Programmazione agentica e code review. Lavoro in più passaggi in un repository reale, lunghe esecuzioni autonome con subagenti e code review che trovano più bug con meno falsi allarmi.
• Lavoro di conoscenza. È molto meno probabile che indichi un numero sbagliato o citi la fonte sbagliata, e nota piccole incongruenze in input molto grandi, come una data che cade nel giorno della settimana sbagliato.
• Comunicazione. Gli aggiornamenti di avanzamento e i resoconti finali dicono chiaramente cosa ha fatto, cosa ha trovato e di cosa ha bisogno da te.
• Grafici, diagrammi, screenshot e uso del computer. Legge il materiale visivo con più precisione di Claude Opus 5, anche al livello di sforzo più basso.

Se i tuoi prompt servono soprattutto per la chat, leggi le sezioni sullo sforzo e sulla chat. Se usi agenti, i consigli nuovi sono nelle sezioni sugli agenti.

Quale livello di sforzo usare con Claude Opus 5.5?

Parti da medium, il valore predefinito di Claude Opus 5.5 (Claude Opus 5 usa high per impostazione predefinita). Impostalo in modo esplicito e prova diversi livelli sui tuoi compiti invece di riprendere il valore usato con Claude Opus 5. I nomi dei livelli di sforzo non corrispondono alla stessa quantità di ragionamento da un modello all'altro: nei test di Anthropic, Claude Opus 5.5 su medium "eguaglia o supera Claude Opus 5 su high nelle valutazioni di programmazione e lavoro di conoscenza", e in diverse valutazioni di programmazione low ci si avvicina a un costo molto più basso.

Impostare medium in modo esplicito equivale esattamente a omettere effort.

A parità di livello, Claude Opus 5.5 tende a ragionare di più per turno rispetto a Claude Opus 5, soprattutto su xhigh e max. Tieni presenti tre cose:

• Lascia margine in max_tokens. Il ragionamento conta in max_tokens anche quando non lo vedi, quindi un limite pensato per Claude Opus 5 senza ragionamento può troncare le risposte. Per i turni lunghi di programmazione agentica, Anthropic ha visto che un max_tokens di 128.000, il massimo del modello, funzionava bene.
• Abbassa lo sforzo prima di scrivere "pensa di meno". Abbassare lo sforzo riduce ragionamento, costo e latenza in modo più affidabile delle istruzioni nel prompt.
• Mantieni fisso lo sforzo se ti affidi alla cache dei prompt. Cambiare il valore di sforzo di primo livello tra una richiesta e l'altra invalida la cache dei prompt.

Lo sforzo si imposta in output_config:

{
  "model": "claude-opus-5-5",
  "max_tokens": 128000,
  "output_config": {"effort": "medium"},
  "messages": [{"role": "user", "content": "Review this pull request for bugs and explain each one."}]
}

Si può disattivare il ragionamento su Claude Opus 5.5?

No. Claude Opus 5 accettava "thinking": {"type": "disabled"} con sforzo high o inferiore; Claude Opus 5.5 non lo accetta e la richiesta restituisce un errore 400. Il ragionamento è adattivo e sempre attivo. Se la tua integrazione funzionava senza ragionamento, Anthropic consiglia quattro modifiche:

1. Parti dallo sforzo low e misura. Su low il modello ragiona poco. Se il tempo al primo token conta ancora, una riga nel prompt di sistema come "Answer directly without deliberating." può ridurre ulteriormente il ragionamento, ma controlla la qualità dopo averla aggiunta.
2. Elimina le istruzioni che sostituivano il ragionamento. Se il tuo prompt chiedeva al modello di scrivere il ragionamento nella risposta, togli quella riga e leggi il ragionamento dal ragionamento riassunto. Un prompt che spinge il modello a riprodurre il ragionamento nella risposta ora può essere rifiutato (vedi la sezione sui rifiuti più sotto).
3. Riprova i vecchi accorgimenti. Le regole aggiunte per evitare gli artefatti del funzionamento senza ragionamento potrebbero non servire più. Elimina qualsiasi regola che dica al modello di non ragionare.
4. Leggi la risposta per tipo di blocco. Una risposta può iniziare o meno con un blocco thinking, quindi controlla il tipo di ogni blocco invece di dare per scontato che il primo sia testo.

Per vedere il ragionamento, chiedi il ragionamento riassunto:

{
  "model": "claude-opus-5-5",
  "max_tokens": 16000,
  "thinking": {"type": "adaptive", "display": "summarized"},
  "output_config": {"effort": "low"},
  "messages": [{"role": "user", "content": "Which of these three invoices has a total that does not match its line items?"}]
}

Come evito che un agente Claude Opus 5.5 non sorvegliato si fermi troppo presto?

Nei compiti lunghi, Claude Opus 5.5 tiene informato l'utente mentre lavora, e alcuni di questi aggiornamenti chiudono il turno con del testo invece che con una chiamata a uno strumento (stop_reason: "end_turn"). Un ciclo di agente che tratta ognuno di questi turni come "compito finito" si ferma a metà strada. La soluzione di Anthropic ha una parte nell'harness e una nel prompt.

Nell'harness, tratta un turno che finisce con solo testo come un resoconto, non come la prova che il lavoro è finito. Tieni le parti del compito in una checklist che il modello aggiorna, come uno strumento di to-do o un file. Se un turno finisce con voci ancora aperte e nessun blocco indicato, invia un breve messaggio utente che le elenchi:

Your task list still has open items: migrate the remaining two endpoints and update their tests. Continue with them. If one is blocked, say what is blocking it.

Fermati dopo due o tre continuazioni automatiche sullo stesso compito, così un'esecuzione davvero bloccata termina e si può esaminare. Se un comando in background o un subagente è ancora in corso, aspetta che finisca e restituisci il suo output come messaggio utente successivo.

Nel prompt di sistema, nomina i tipi di arresto prematuro che non vuoi. L'esempio di Anthropic, scritto per agenti che girano senza alcuna supervisione, va alla fine del prompt di sistema fin dalla prima richiesta della sessione. Aggiungerlo a metà cambia il prompt di sistema e invalida i blocchi di ragionamento precedenti della conversazione.

A standing instruction from the user, the person you are working for. It is about how your turns end. A message with no tool call in it ends your turn, and the work stops there until you are asked to continue. The user has seen you end turns in four ways while work they asked for was still owed, and does not want any of them. One: a long summary of what was done that closes by announcing the next step and has no tool call, so the next thing never starts. Two: an offer to carry on with something unless the user would prefer otherwise, which stops to wait for an answer the user was not going to give. Three: a list of decisions for the user when, by your own account, none of them blocks the rest of the work. Four: deciding that this is a good place to report, because the turn has been long or a milestone is done. Status notes are welcome, and so are your recommendations on open decisions, but put them in the same message as your next tool call and carry on with whatever does not depend on the user's answer. If you notice yourself inviting the user to redirect you or offering to wait, delete it and do the next thing. The stops the user does want are the ones where nothing can move without them, or where the thing blocking you is deliberately protected from you. This does not override the need for confirmation on risky or destructive actions.

Non aggiungere questo testo alle applicazioni con una persona nel ciclo, dove qualcuno può rispondere, e mantieni il tuo passaggio di conferma per le azioni rischiose o irreversibili. Aspettati qualche chiamata a strumenti e qualche token di output in più per compito.

Come ricevo aggiornamenti di avanzamento da un agente Claude Opus 5.5 nelle esecuzioni lunghe?

Tra una chiamata a strumento e l'altra, Claude Opus 5.5 scrive brevi note di avanzamento: cosa ha appena trovato e cosa farà dopo. Su questo modello quelle note arrivano come blocchi thinking e non come blocchi text, e il loro testo è vuoto per impostazione predefinita, quindi un client che mostra solo i blocchi text può sembrare muto durante un turno lungo. Anthropic documenta una modalità di visualizzazione beta che restituisce un riassunto di ogni nota; il riferimento API di Claude Opus 5.5 elenca i valori di thinking.display documentati per l'endpoint.

Tre leve di prompt e harness funzionano senza impostazioni speciali:

• Dai al modello uno strumento per i contenuti testuali esatti. Se potrebbe dover consegnare all'utente qualcosa di preciso a metà turno, come un frammento di codice, dagli un semplice strumento "invia un messaggio all'utente" e digli di riservarlo a questo. Dichiara lo strumento dalla prima richiesta; aggiungerlo dopo invalida i blocchi di ragionamento precedenti.
• Chiedi aggiornamenti in punti fissi. Per esempio una frase di intenzione prima della prima chiamata a strumento e un breve riepilogo alla fine. Il modello segue da vicino istruzioni di questo tipo, il che aiuta soprattutto quando qualcuno sta guardando.
• Sollecita dall'harness un turno silenzioso. Conta i passaggi consecutivi di chiamata a strumento che non danno all'utente nulla da leggere. Dopo alcuni, per esempio cinque, aggiungi un promemoria dopo gli ultimi risultati degli strumenti, e smetti dopo due o tre promemoria. La formulazione di Anthropic:

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

Nei test di Anthropic su compiti di programmazione agentica, questo promemoria ha dimezzato circa la percentuale di compiti con un lungo tratto silenzioso, senza variazioni misurabili del costo.

Come faccio a far controllare il contesto a un agente Claude Opus 5.5 prima che agisca?

Claude Opus 5.5 tende a mettersi subito al lavoro. Nelle automazioni che coinvolgono email, documenti, fogli di calcolo e record del CRM, l'informazione da cui dipende un compito si trova spesso dove la richiesta non dice, come una policy in un vecchio thread email o una regola in un'altra scheda del foglio di calcolo. Una frase nel prompt di sistema spinge il modello a guardarsi intorno prima:

Before taking any action, explore broadly with tool calls: list and open the emails, documents, spreadsheet tabs and records across the available apps that could be relevant to this task, including ones the task does not explicitly mention, and use what you find.

Nei test di Anthropic su compiti che coinvolgono più app, con questa riga il modello ne ha completati correttamente molti di più, sia con sforzo medium sia con max, a fronte di qualche chiamata a strumento in più. Poiché la riga dice al modello di agire in base a ciò che trova, tieni i contenuti non affidabili fuori dai record che consulta.

Come faccio a far finire prima un team di agenti Claude Opus 5.5?

Claude Opus 5.5 presta molta attenzione al tempo trascorso. In una configurazione in cui un agente principale affida il lavoro a subagenti, dagli un budget di tempo: fai aggiungere al tuo harness una breve riga alla fine di ogni messaggio restituito al modello, come elapsed 340s / 1200s. Il modello regola il ritmo per finire entro il budget e di solito finisce ben prima, quindi fissa il budget un po' sopra il tempo che vuoi davvero spendere. Se non riesci a stimare un budget, mostra solo il tempo trascorso e aggiungi questa frase al prompt di sistema:

Time matters here: do not spend time that can be avoided, and the earlier a correct result is obtained, the better.

Il budget è indicativo e nulla ferma il modello al limite, quindi mantieni il tuo timeout se ti serve un arresto netto. Un budget più stretto non equivale a uno sforzo più basso: abbassare lo sforzo riduce il lavoro in sé, mentre un budget fa soprattutto lavorare più agenti in parallelo. Sotto pressione il modello potrebbe cercare e verificare un po' meno, quindi controlla la qualità delle risposte sui tuoi compiti.

Un prompt di sistema per la chat deve dire a Claude Opus 5.5 di pensare con attenzione?

No. Anthropic suggerisce di togliere dai prompt di sistema per la chat righe come "think carefully before answering" (pensa con attenzione prima di rispondere): il modello decide da solo quanto ragionare e il controllo è lo sforzo. Nei test di Anthropic su un prodotto di chat, togliere una riga del genere ha fatto partire prima le risposte, senza un calo evidente della qualità.

Ci sono altre due righe per la chat che conviene conoscere. Una fa trattare al modello le risposte precedenti come chiuse, così i turni successivi partono prima. L'altra segnala il testo incollato dall'utente, così il modello non segue istruzioni nascoste in un'email o in una pagina web. Entrambe le righe, parola per parola, sono nella sezione su Claude Opus 5.5 della guida Fable 5.1. Non usare la riga sulle "risposte chiuse" nelle analisi lunghe e nei compiti agentici, dove un passaggio successivo può rivelare un errore in uno precedente.

Come ottengo risposte migliori su grafici, diagrammi e screenshot?

Prima riprova. Senza strumenti aggiuntivi, Claude Opus 5.5 legge grafici densi, diagrammi di flusso e screenshot di calendari con molta più precisione di Claude Opus 5; nei test di Anthropic, anche al livello di sforzo più basso leggeva i valori dei grafici densi con più precisione di Claude Opus 5 al livello più alto. Le impalcature costruite per i modelli precedenti potrebbero non servire più.

Per gli input più densi, due cose aiutano ancora:

• Immagini a risoluzione più alta, soprattutto per i disegni tecnici.
• Strumenti per le immagini. Esegui il modello come agente con un container che contenga le immagini originali e abbia PIL o OpenCV installati, così può ritagliare, ingrandire e misurare. Se è troppo, anche un solo strumento di ritaglio aiuta. Il modello usa meglio questi strumenti a livelli di sforzo più alti.

Senza strumenti, alzare lo sforzo migliora la lettura dei disegni tecnici ma serve poco per i grafici. Le immagini vanno in un turno utente come blocchi image con una sorgente URL; il riferimento API mostra il formato.

Come evito che il frontend di Claude Opus 5.5 sembri generico?

Nomina gli schemi che non vuoi. Senza indicazioni di design, Claude Opus 5.5 ripiega su alcuni stili predefiniti, e un'istruzione generica come "evita l'aspetto da IA generica" di solito sostituisce solo un predefinito con un altro. L'esempio di Anthropic elenca cose concrete da evitare:

Output a vanilla HTML/CSS personal website with placeholder data. Do not use a cream or off-white background, italic accent words in headlines, numbered "01/02/03" section labels, monospace labels, or pill-shaped buttons.

Procedi per iterazioni: guarda quali stili ha usato al loro posto il primo risultato e aggiungili all'elenco.

Perché Claude Opus 5.5 restituisce stop_reason "refusal"?

Un classificatore di sicurezza ha rifiutato la richiesta. Claude Opus 5.5 usa classificatori per biologia, cybersicurezza ed estrazione del ragionamento; il rifiuto arriva come una normale risposta con stop_reason: "refusal" e un oggetto stop_details che indica la categoria.

Per i rifiuti di richieste innocue in generale, vedi perché Claude rifiuta una richiesta innocua nella guida Fable 5.1.

Domande frequenti

Esiste una guida ufficiale al prompting di Claude Opus 5.5?

Sì. Anthropic pubblica "Prompting Claude Opus 5.5" nella sua documentazione per sviluppatori, insieme a una pagina generale di buone pratiche valida per tutti i modelli Claude attuali. Questo articolo riassume la guida di Opus 5.5 al 3 ottobre 2026 e cita i modelli di prompt parola per parola.

Qual è il livello di sforzo predefinito di Claude Opus 5.5?

medium. Claude Opus 5 usa high per impostazione predefinita. I livelli sono low, medium, high, xhigh e max e si impostano in output_config.effort.

Quanti token di output può scrivere Claude Opus 5.5?

Fino a 128.000 token per richiesta, ragionamento incluso. La finestra di contesto è di 1M token.

Posso precompilare la risposta di Claude Opus 5.5 o impostare la temperatura?

No. La precompilazione della risposta dell'assistente e qualsiasi temperatura diversa da quella predefinita restituiscono un errore 400, e forzare uno strumento specifico non è supportato. Descrivi invece nel prompt il formato che vuoi. La guida al prompting di Claude Fable 5.1 spiega cosa usare al loro posto.

Per gli agenti è meglio Claude Opus 5.5 o Claude Fable 5.1?

Dipende dal compito e dal budget; il confronto tra i modelli Claude spiega quale scegliere. I consigli di prompting differiscono soprattutto nei valori predefiniti: Claude Opus 5.5 parte dallo sforzo medium, Claude Fable 5.1 da high.

Prova i prompt

Esegui questi modelli di prompt su Claude Opus 5.5 con una chiave SeedRouter, tramite l'SDK di Anthropic o i formati Chat Completions e Responses di OpenAI. Il riferimento API di Claude Opus 5.5 elenca tutti i parametri, e la pagina del modello mostra i prezzi attuali per token. SeedRouter è a consumo: ricarichi una volta, i crediti non scadono mai e le richieste non riuscite non vengono addebitate.