Prompting di Claude Opus 5

Questa guida tratta i pattern di prompting specifici di Claude Opus 5. Per le specifiche del modello, consulta Claude Opus 5. Per le tecniche valide per tutti i modelli Claude attuali, consulta Best practice di prompting.

Claude Opus 5 è progettato per il coding agentico complesso e il lavoro enterprise, con particolari punti di forza nei task agentici a lungo orizzonte. Funziona bene fin da subito con i prompt esistenti per Claude Opus 4.8. I pattern seguenti coprono i comportamenti che più spesso richiedono una messa a punto.

Miglioramenti delle capacità

Rispetto a Claude Opus 4.8, i miglioramenti più rilevanti per il prompting sono:

• Coding agentico: Claude Opus 5 dà il meglio di sé nei compiti di coding difficili: funzionalità su più file, refactoring più ampi e sviluppo di funzionalità end-to-end. Completa interi compiti invece di lasciare stub o segnaposto, e rende al meglio quando riceve fin dall'inizio la specifica completa del compito e viene lasciato lavorare. Funziona bene anche su compiti più semplici come le modifiche a singolo turno, dove la differenza rispetto ai modelli precedenti è minore.
• Revisione del codice e individuazione dei bug: Claude Opus 5 revisiona il codice con elevata "precision" (precisione) e "recall" (richiamo): trova bug reali con un tasso elevato per passaggio, e i suoi rilevamenti aggiuntivi sono per lo più problemi reali anziché falsi positivi. L'accuratezza si mantiene anche con impostazioni di effort più basse, il che consente un passaggio rapido al momento della revisione e un passaggio più approfondito in seguito. Se il tuo prompt di revisione dice "segnala solo i problemi ad alta gravità" o "sii conservativo", il modello potrebbe seguire quell'istruzione alla lettera e segnalare di meno; chiedigli invece di segnalare tutto e filtra in un passaggio separato.
• Efficienza con effort più basso: l'effort low e medium produce una qualità elevata con una frazione dei token e della "latency" (latenza) delle impostazioni più alte. Inizia con il valore predefinito (high) e regolalo in base alle tue valutazioni: usa low e medium liberamente come controllo principale per il costo dei token e il tempo di risposta ovunque la qualità si mantenga, e passa a xhigh per il lavoro di coding e agentico impegnativo. Se hai mantenuto le impostazioni predefinite di effort di un modello precedente, ripeti un confronto tra i livelli di effort sulle tue valutazioni. Consulta i livelli di effort consigliati per le indicazioni complete.
• Visione: Claude Opus 5 è forte nella comprensione di grafici, documenti e diagrammi, e nella replica visiva di UI e frontend. Riconvalida eventuali soluzioni alternative per la visione lato prompt che hai messo a punto per i modelli precedenti; potrebbero non essere più necessarie. Le prestazioni di visione sono migliori quando il modello dispone di strumenti per analizzare, ritagliare e verificare visivamente il proprio lavoro in modo iterativo, e l'"tool use" (uso degli strumenti) è una leva più conveniente rispetto al solo ragionamento.
• Lavoro a contesto lungo: Claude Opus 5 ha una "context window" (finestra di contesto) da 1M di token sia come valore predefinito sia come massimo, e il rispetto delle istruzioni, le chiamate agli strumenti e il ragionamento restano coerenti lungo tutta la finestra.
• Compiti d'ufficio e sui documenti: Claude Opus 5 genera e gestisce fogli di calcolo complessi con più fogli e formule non banali, e produce presentazioni ben strutturate. Fornisci nel prompt eventuali stili o modelli specifici che deve seguire.
• Coordinamento multiagente: Claude Opus 5 coordina bene team di subagent, con schemi writer-verifier efficaci e pochi casi di agenti che sovrascrivono il lavoro degli altri. Per i carichi di lavoro sensibili ai costi, limita la delega; consulta Controllare la creazione di subagent.

Lunghezza delle risposte e verbosità

Le risposte predefinite rivolte all'utente di Claude Opus 5 sono più lunghe di quelle dei modelli Opus precedenti. Il parametro effort controlla quanto il modello pensa piuttosto che quanto dice: abbassare l'effort può ridurre il volume di ragionamento senza accorciare in modo affidabile la risposta visibile. Per controllare la lunghezza della risposta, richiedila esplicitamente nel prompt.

Una breve istruzione di concisione è efficace. Ad esempio, per un prodotto multi-turno rivolto all'utente:

Keep responses focused, brief, and concise. Keep disclaimers and caveats short, and spend most of the response on the main answer. When asked to explain something, give a high-level summary unless an in-depth explanation is specifically requested.

In un prompt di sistema lungo, abbina l'istruzione a un breve promemoria verso la fine del prompt:

<tone_preference>
Keep outputs reasonably concise.
</tone_preference>

Aggiornamenti di avanzamento rivolti all'utente

Claude Opus 5 narra con facilità durante il lavoro agentico: tende ad annunciare ciò che sta per fare, e il suo output per messaggio nelle sessioni agentiche è spesso più lungo di quello dei modelli precedenti. Trae beneficio da indicazioni esplicite su come comunicare con l'utente durante un task. Per ridurre la narrazione, descrivi la cadenza e la forma che desideri:

Before your first tool call, say in one sentence what you're about to do. While working, give a brief update only when you find something important or change direction. When you finish, lead with the outcome: your first sentence should answer "what happened" or "what did you find," with supporting detail after it for readers who want it.

Per aumentare la narrazione, o cambiarne lo stile, la stessa leva si applica nella direzione opposta: descrivi esplicitamente come dovrebbero apparire gli aggiornamenti e fornisci esempi. Gli esempi positivi dello stile di comunicazione che desideri tendono a essere più efficaci delle istruzioni su cosa non fare.

Lunghezza dei deliverable scritti

Separatamente dalla verbosità conversazionale, i file che Claude Opus 5 scrive su disco (report, documenti Markdown, riepiloghi) sono spesso più lunghi rispetto ai modelli precedenti. Se il tuo prodotto include documenti redatti da Claude, aggiungi una calibrazione esplicita della lunghezza:

Match the length of written documents to what the task needs: cover the substance, but do not pad with filler sections, redundant summaries, or boilerplate.

Ambito del task e verifica eccessiva

Claude Opus 5 verifica il proprio lavoro senza che gli venga detto. Se il tuo prompt contiene istruzioni di verifica esplicite ("includi un passaggio di verifica finale per qualsiasi task non banale", "usa un subagente per verificare"), rimuovile: istruzioni come queste causano una verifica eccessiva su Claude Opus 5, e rimuoverle riduce i token sprecati senza perdita di qualità. Lo stesso vale per lo scaffolding legacy dell'harness che aggiunge passaggi di verifica separati.

Claude Opus 5 può anche ampliare l'ambito di un task, aggiungendo passaggi non richiesti o applicando il proprio giudizio su quale dovrebbe essere il task. Per task circoscritti, vincola l'ambito esplicitamente:

Deliver what was asked, at the scope intended. Make routine judgment calls yourself, and check in only when different readings of the request would lead to materially different work. If the request seems mistaken or a better approach exists, say so in a sentence and continue with the task as asked rather than quietly narrowing, widening, or transforming it. Finish the whole task, and stop short of actions that are clearly beyond what was asked.

Controllare la creazione di subagenti

Claude Opus 5 delega ai subagent più facilmente dei modelli precedenti. La delega è utile per filoni di lavoro realmente indipendenti e consistenti, ma moltiplica costi e tempi quando applicata a piccoli compiti. Se il tuo harness supporta i subagent, fornisci indicazioni esplicite su quali scenari giustificano la delega, oppure imposta limiti deterministici sul numero di agenti che possono essere avviati. Ad esempio:

Delegate to a subagent only for large tasks that are genuinely independent and parallelizable, such as a wide multi-file investigation. Do not delegate work you can finish yourself in a handful of tool calls, and do not use subagents to verify or double-check your own work. If one subagent can complete the task, use one rather than several, and keep spawn counts low.

Se il tuo harness è Claude Code o il Claude Agent SDK, i limiti deterministici sono le variabili d'ambiente CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH e CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS e l'opzione max_budget_usd dell'SDK. Le versioni precedenti di Claude Code non li hanno, quindi aggiorna Claude Code e qualsiasi SDK con versione fissata prima di usare il tuo harness con Claude Opus 5. Claude Code aggiunge una propria istruzione di delega su Claude Opus 5 solo quando usi il suo preset di prompt di sistema claude_code; con un prompt di sistema personalizzato o omesso, aggiungi tu stesso un'istruzione di delega come l'esempio in questa sezione. Consulta Cap subagent depth, concurrency, and spend nella documentazione dell'Agent SDK.

Autocorrezione

Claude Opus 5 individua e corregge bene i propri errori senza bisogno di prompt. Evita di istruire ricontrolli che già esegue ("ricontrolla la tua risposta", "riverifica prima di rispondere"); come le istruzioni di verifica, queste si sommano al comportamento proprio del modello e aggiungono costi senza migliorare i risultati.

Il modello inoltre narra le correzioni alle proprie affermazioni precedenti più di quanto facciano i modelli precedenti, il che può essere indesiderabile nei prodotti rivolti all'utente. Per limitare la narrazione delle correzioni a quelle che contano:

Only correct an earlier statement when the error would change the user's code, conclusions, or decisions. State corrections plainly and briefly, then continue the task. For slips that change nothing for the user, make the fix and move on without noting it.

Esecuzione con il ragionamento disabilitato

Claude Opus 5 funziona con il ragionamento attivo per impostazione predefinita, e il ragionamento può essere disabilitato solo con effort high o inferiore. Una richiesta che combina thinking: {"type": "disabled"} con effort xhigh o max restituisce un errore 400. Con il ragionamento disabilitato, nell'output visibile del modello possono occasionalmente comparire due artefatti. La mitigazione principale per entrambi è mantenere il ragionamento abilitato e controllare il costo in token con livelli di effort più bassi invece di disabilitare il ragionamento: per la maggior parte dei task, il ragionamento abilitato con effort low offre prestazioni migliori del ragionamento disabilitato a un costo simile.

Chiamate agli strumenti come testo. Con il ragionamento disabilitato, il modello occasionalmente scrive una chiamata a uno strumento nel testo rivolto all'utente invece di emettere un blocco tool_use strutturato. Il turno si completa normalmente e la chiamata non viene mai eseguita, e nei loop agentici il testo trapelato resta nella cronologia della conversazione, quindi anche i turni successivi ne risentono. Questo è più comune nei carichi di lavoro con uso intensivo di strumenti, come la ricerca.

Tag XML interni nell'output. Con il ragionamento disabilitato, il modello può emettere tag <thinking> o altri tag XML interni nella risposta visibile. Se il tuo prompt di sistema contiene una regola che istruisce il modello a non pensare o a non ragionare, rimuovila; quel tipo di istruzione aumenta la fuoriuscita di tag.

Per le integrazioni che devono mantenere il ragionamento disabilitato, una singola istruzione combinata mitiga entrambi gli artefatti: dà al modello il permesso esplicito di parlare prima di una chiamata a uno strumento, un'alternativa al forzare una chiamata quando nessuno strumento è adatto, e una regola generale contro i tag interni:

When you use a tool, you may say a brief sentence first. If no tool can express what the user asked for, say so instead of guessing. Do not include internal or system XML tags in your response.

Le istruzioni che citano i tag di ragionamento per nome sono meno efficaci della forma generale, quindi evita di nominarli specificamente.

Ragionamento nella risposta

Prompt, skill e descrizioni degli strumenti che chiedono a Claude Opus 5 di scrivere il proprio ragionamento, alla lettera o in un formato fisso, potrebbero essere rifiutati con la categoria di rifiuto reasoning_extraction. Chiedi invece una breve spiegazione della risposta o un riepilogo delle azioni intraprese e, se hai bisogno del ragionamento, mantieni il ragionamento attivo e leggi i blocchi di ragionamento riassunto (display: "summarized"). Consulta Mantenere il ragionamento nei blocchi di ragionamento.