Prompting di Claude Opus 5

Questa guida copre i pattern di prompting specifici di Claude Opus 5. Per le capacità del modello e le modifiche all'API, consulta Novità di Claude Opus 5. Per le tecniche che si applicano a 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 task di coding difficili: funzionalità multi-file, refactoring più ampi e sviluppo di funzionalità end-to-end. Completa i task per intero invece di lasciare stub o placeholder, e rende al meglio quando riceve la specifica completa del task fin dall'inizio e viene lasciato lavorare. Funziona bene anche su task più semplici come le modifiche a turno singolo, dove la differenza rispetto ai modelli precedenti è minore.
• Code review e ricerca di bug: Claude Opus 5 revisiona il codice con alta precisione e recall: trova bug reali a un tasso elevato per passaggio, e le sue segnalazioni aggiuntive sono per lo più problemi reali piuttosto che falsi positivi. L'accuratezza si mantiene anche con impostazioni di effort più basse, il che consente un passaggio rapido al momento della review e un passaggio più approfondito in seguito. Se il tuo prompt di review dice "segnala solo i problemi ad alta gravità" o "sii conservativo", il modello potrebbe seguire l'istruzione alla lettera e segnalare meno; chiedigli invece di segnalare tutto e filtra in un passaggio separato.
• Efficienza a effort più basso: gli effort low e medium producono una qualità elevata con una frazione dei token e della "latency" (latenza) delle impostazioni più alte. Inizia con il valore predefinito (high) e regola in base alle tue eval: usa low e medium liberamente come controllo principale del costo in token e del tempo di risposta ovunque la qualità regga, e sali a xhigh per il lavoro di coding e agentico più impegnativo. Se hai mantenuto i valori predefiniti di effort da un modello precedente, riesegui uno sweep dell'effort sulle tue eval. Consulta Effort per le raccomandazioni complete.
• Visione: Claude Opus 5 è forte nella comprensione di grafici, documenti e diagrammi, e nella replica visiva di UI e frontend. Rivalida eventuali workaround lato prompt per la visione che avevi messo a punto per i modelli precedenti; potrebbero non essere più necessari. 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 il "tool use" (uso degli strumenti) è una leva più conveniente in termini di costi rispetto al solo pensiero.
• 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.
• Task di ufficio e documentali: Claude Opus 5 genera e lavora con fogli di calcolo complessi e multi-foglio con formule non banali, e produce presentazioni ben strutturate. Indica nel prompt eventuali stili o template specifici che deve seguire.
• Coordinamento multi-agente: Claude Opus 5 coordina bene team di subagenti, con pattern scrittore-verificatore efficaci e pochi casi di agenti che sovrascrivono il lavoro altrui. Per i carichi di lavoro sensibili ai costi, limita la delega; consulta Controllare la creazione di subagenti.

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 pensiero 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 subagenti più facilmente dei modelli precedenti. La delega ripaga su filoni di lavoro realmente indipendenti e consistenti, ma moltiplica costi e tempi quando applicata a task piccoli. Se il tuo harness supporta i subagenti, 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. Richiedono Claude Code 2.1.217 o successivo, quindi aggiorna un SDK con versione fissata prima di puntarlo a 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 Limitare profondità, concorrenza e spesa dei subagenti 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 pensiero disabilitato

Claude Opus 5 funziona con il pensiero attivo per impostazione predefinita, e il pensiero può essere disabilitato solo con effort high o inferiore; consulta la guida alla migrazione. Con il pensiero disabilitato, due artefatti possono occasionalmente comparire nell'output visibile del modello. La mitigazione principale per entrambi è mantenere il pensiero abilitato e controllare il costo in token con livelli di effort più bassi invece di disabilitare il pensiero: per la maggior parte dei task, il pensiero abilitato con effort low rende meglio del pensiero disabilitato a costo simile.

Chiamate agli strumenti come testo. Con il pensiero 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 pensiero 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 pensiero 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 pensiero per nome sono meno efficaci della forma generale, quindi evita di nominarli specificamente.