SpyBara
Go Premium

workflows.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 156 additions and 58 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Fri 18 23:58 Tue 22 23:59 Fri 25 23:58

Orchestrare subagenti su larga scala con flussi di lavoro dinamici

I flussi di lavoro dinamici orchestrano molti subagenti da uno script che Claude scrive e che puoi rieseguire. Usali per audit di codebase, migrazioni su larga scala e ricerche con verifica incrociata.

Un flusso di lavoro dinamico è uno script JavaScript che orchestra molti subagenti contemporaneamente. Claude scrive lo script per il compito che descrivi, e un runtime lo esegue in background mentre la tua sessione rimane reattiva.

Ricorri a un flusso di lavoro quando un compito richiede più agenti di quanti una conversazione possa coordinare, o quando vuoi che l'orchestrazione sia codificata come uno script che puoi leggere e rieseguire. Gli esempi includono una ricerca di bug a livello di codebase, una migrazione di 500 file, una domanda di ricerca che richiede fonti verificate l'una rispetto all'altra, e un piano difficile che vale la pena di elaborare da diversi angoli indipendenti prima di impegnarsi in uno.

Quando usare un flusso di lavoro

Subagenti, skills, team di agenti e flussi di lavoro possono tutti eseguire un compito multi-step. La differenza è chi tiene il piano:

Subagenti Skills Team di agenti Flussi di lavoro
Che cosa è Un worker Claude che genera Istruzioni che Claude segue Un agente lead che supervisiona sessioni peer Uno script che il runtime esegue
Chi decide cosa viene eseguito dopo Claude, turno per turno Claude, seguendo il prompt L'agente lead, turno per turno Lo script
Dove vivono i risultati intermedi Finestra di contesto di Claude Finestra di contesto di Claude Un elenco di compiti condiviso Variabili dello script
Che cosa è ripetibile La definizione del worker Le istruzioni La definizione del team L'orchestrazione stessa
Scala Alcuni compiti delegati per turno Uguale ai subagenti Una manciata di peer a lunga esecuzione Decine a centinaia di agenti per esecuzione
Interruzione Riavvia il turno Riavvia il turno I compagni di team continuano a funzionare Riprendibile nella stessa sessione

Un flusso di lavoro sposta il piano nel codice. Con subagenti, skills e team di agenti, Claude è l'orchestratore: decide turno per turno cosa generare o assegnare dopo, e ogni risultato finisce nella finestra di contesto. Uno script di flusso di lavoro tiene il ciclo, la ramificazione e i risultati intermedi stessi, quindi il contesto di Claude contiene solo la risposta finale.

Spostare il piano nel codice consente anche a un flusso di lavoro di applicare un modello di qualità ripetibile, non solo eseguire più agenti: può avere agenti indipendenti che si rivedono avversarialmente i risultati l'uno dell'altro prima che vengano segnalati, o elaborare un piano da diversi angoli e pesarli l'uno rispetto all'altro, così ottieni un risultato più affidabile di un singolo passaggio.

Eseguire un flusso di lavoro in bundle

Il modo più veloce per vedere un flusso di lavoro in azione è eseguire /deep-research, il flusso di lavoro integrato che Claude Code include per investigare una domanda su molte fonti. Vedrai gli agenti lavorare attraverso una serie di fasi in background mentre la tua sessione rimane libera, e otterrai un rapporto alla fine invece di una trascrizione turno per turno.

1

Eseguire il flusso di lavoro

Esegui /deep-research con una domanda che vuoi investigare. Distribuisce ricerche web su diversi angoli, recupera e verifica in modo incrociato le fonti che trova, e sintetizza un rapporto citato.

/deep-research What changed in the Node.js permission model between v20 and v22?
2

Consentire i flussi di lavoro

Claude Code chiede se consentire il flusso di lavoro. Seleziona Sì per continuare. Il prompt esatto dipende dalla tua modalità di autorizzazione. Vedi Approvare il piano prima che venga eseguito per le opzioni per modalità.

3

Guardare il progresso

L'esecuzione inizia in background. Esegui /workflows, usa i tasti freccia per selezionare l'esecuzione e premi Invio per aprire la sua vista di progresso:

/workflows

La vista mostra ogni fase con il suo conteggio di agenti, totale di token e tempo trascorso. Approfondisci qualsiasi fase per vedere i suoi agenti e cosa ha trovato ognuno. Vedi Guardare l'esecuzione per l'insieme completo di controlli.

Puoi anche guardare dal pannello attività sotto la casella di input: un riepilogo di progresso su una riga appare lì mentre l'esecuzione è in corso. Premi la freccia giù per focalizzarlo, quindi Invio per espandere.

4

Leggere il rapporto

Quando l'esecuzione finisce, il rapporto arriva nella tua sessione. Cita le fonti da cui proviene ogni affermazione, con affermazioni che non hanno superato la verifica incrociata già filtrate.

Quando gli agenti verificatori non riescono a controllare un'affermazione, ad esempio dopo un limite di velocità o un errore API, il rapporto elenca tale affermazione come non verificata invece di contarla come confutata.

Per eseguire un flusso di lavoro per il tuo compito, fai scrivere uno a Claude, e una volta che un'esecuzione fa quello che volevi puoi salvarlo come comando tuo.

Flussi di lavoro in bundle

Claude Code include /deep-research come flusso di lavoro integrato:

Comando Che cosa fa
/deep-research <question> Distribuisce ricerche web su una domanda su diversi angoli, recupera e verifica in modo incrociato le fonti che trova, vota su ogni affermazione e restituisce un rapporto citato con affermazioni che non hanno superato la verifica incrociata filtrate. Richiede che lo strumento WebSearch sia disponibile

/deep-research viene eseguito solo quando lo richiami.

I flussi di lavoro che salvi tu stesso diventano comandi allo stesso modo e appaiono nell'autocompletamento / insieme a quelli in bundle.

Guardare l'esecuzione

I flussi di lavoro vengono eseguiti in background, quindi la sessione rimane reattiva mentre gli agenti lavorano. Esegui /workflows in qualsiasi momento per elencare i flussi di lavoro in esecuzione e completati, quindi selezionane uno per aprire la sua vista di progresso.

La vista di progresso mostra ogni fase con i suoi conteggi di agenti, totali di token e tempo trascorso. Il piè di pagina elenca il tasto per ogni azione:

Tasto Azione
↑ / ↓ Selezionare una fase o un agente
Invio o → Approfondire la fase selezionata, quindi in un agente per leggere il suo prompt, le recenti chiamate di strumenti e il risultato
Esc o ← Tornare indietro di un livello. Nelle versioni da v2.1.203 a v2.1.205, ← non è tornato indietro da una fase o un agente; usa Esc su quelle versioni
j / k Scorrere all'interno del dettaglio dell'agente quando trabocca
f Filtrare l'elenco degli agenti nella fase selezionata per stato. Premi di nuovo per ciclare
p Mettere in pausa o riprendere l'esecuzione
x Fermare l'agente selezionato, o fermare l'intero flusso di lavoro quando il focus è sull'esecuzione
r Riavviare l'agente in esecuzione selezionato
s Salvare lo script dell'esecuzione come comando

Far scrivere a Claude un flusso di lavoro

Puoi far scrivere a Claude un flusso di lavoro per il tuo compito in due modi:

Puoi anche eseguire un comando di flusso di lavoro che già esiste: un flusso di lavoro in bundle come /deep-research, o uno che hai salvato.

Chiedere un flusso di lavoro nel tuo prompt

Per eseguire un singolo compito come flusso di lavoro senza cambiare il livello di sforzo della sessione, includi la parola chiave ultracode nel tuo prompt. Chiedere con le tue stesse parole, ad esempio "usa un flusso di lavoro" o "esegui un flusso di lavoro", funziona anche: Claude tratta una richiesta diretta come lo stesso opt-in.

ultracode: audit every API endpoint under src/routes/ for missing auth checks

Claude Code evidenzia la parola chiave nel tuo input e Claude scrive uno script di flusso di lavoro per il compito invece di lavorarci turno per turno. La parola chiave sceglie solo come Claude struttura il lavoro: le chiamate agli strumenti degli agenti ricevono gli stessi controlli di autorizzazione e sandboxing di qualsiasi altra chiamata agli strumenti nella sessione.

Se l'esecuzione fa quello che volevi, puoi salvarlo come comando dopo. Se hai già un orchestrator costruito in un altro modo, come una cartella di prompt di subagent o una skill che distribuisce il lavoro, puoi indicare a Claude dove si trova e chiedere un flusso di lavoro che faccia la stessa cosa.

Ignorare o disattivare la parola chiave

Se non intendevi avviare un flusso di lavoro, premi Option+W su macOS o Alt+W su Windows e Linux per ignorare l'evidenziazione per questo prompt, oppure premi backspace mentre il cursore è subito dopo la parola chiave evidenziata. Per impedire che la parola chiave attivi un flusso di lavoro del tutto, disattiva il trigger della parola chiave Ultracode in /config.

Dove funziona la parola chiave

La parola chiave è un opt-in solo in un prompt che digiti tu stesso: al prompt interattivo, in un pannello dell'estensione IDE, in un client Remote Control, o in un'applicazione Agent SDK che contrassegna l'origin del tuo input da tastiera come { kind: "human" }. Non avvia un flusso di lavoro quando raggiunge la sessione in un altro modo:

  • un prompt passato con -p
  • un prompt che un'applicazione Agent SDK invia senza contrassegnarlo come input umano
  • un prompt di compito programmato
  • un payload webhook o un commento di pull request inoltrato nella conversazione

Lasciare che Claude decida con ultracode

Ultracode è un'impostazione di Claude Code che combina xhigh sforzo di ragionamento con orchestrazione automatica del flusso di lavoro. Con essa attiva, Claude pianifica un flusso di lavoro per ogni compito sostanziale invece di aspettare che tu lo chieda.

/effort ultracode

Per avviare una sessione con ultracode già attivo, avvia con claude --effort ultracode. Richiede Claude Code v2.1.203 o successivo.

Per attivarlo mentre scegli un modello, sposta il cursore dello sforzo del selettore /model su ultracode con i tasti freccia. Regola il livello di sforzo elenca i percorsi che attivano ultracode.

Con ultracode attivo, Claude decide quando un compito merita un flusso di lavoro. Una singola richiesta può trasformarsi in diversi flussi di lavoro di fila: uno per comprendere il codice, uno per fare il cambiamento e uno per verificarlo. Questo si applica a ogni compito nella sessione, quindi ogni richiesta usa più token e richiede più tempo rispetto ai livelli di sforzo inferiori.

/effort ultracode dura per la sessione corrente; per avere ogni sessione che inizi con esso, imposta l'impostazione ultracode. Torna indietro con /effort high quando ritorni al lavoro di routine. È disponibile su modelli che supportano xhigh sforzo; su altri modelli il menu /effort non lo offre.

Approvare il piano prima che venga eseguito

Nel CLI, il prompt per esecuzione mostra le fasi pianificate e queste opzioni:

  • Sì, eseguilo: avvia l'esecuzione
  • Sì, e non chiedere di nuovo per <name> in <path>: avvia e salta questo prompt per questo flusso di lavoro in questo progetto da ora in poi. Claude Code offre questa opzione quando esegui un flusso di lavoro in bundle, salvato o plugin per nome, non per uno script che Claude ha scritto per il compito corrente.
  • Visualizza script grezzo: leggi lo script prima di decidere
  • No: annulla

Ctrl+G apre lo script nel tuo editor. Tab ti consente di regolare il prompt prima che l'esecuzione inizi.

Se vedi questo prompt dipende dalla tua modalità di autorizzazione:

Modalità di autorizzazione Quando sei richiesto
Auto Solo al primo avvio. Qualsiasi Sì registra il consenso nelle tue impostazioni utente, e i successivi avvii iniziano senza richiedere. Saltato completamente quando ultracode è attivo
Manuale, accetta modifiche Ogni esecuzione, a meno che tu non abbia selezionato Sì, e non chiedere di nuovo per quel flusso di lavoro in questo progetto
Bypass permissions Claude Code non ti richiede. L'esecuzione inizia immediatamente
claude -p, Agent SDK Claude Code non ti richiede

In claude -p e nell'Agent SDK, Claude Code non mostra mai questo prompt. Esegue la chiamata dello strumento Workflow attraverso la stessa valutazione delle autorizzazioni del resto della sessione, quindi le regole di negazione, le regole di richiesta e la modalità dontAsk si applicano al lancio come si applicano a ogni chiamata agli strumenti. Per consentire al flusso di lavoro di iniziare in queste esecuzioni, usa uno di questi:

  • Regola di autorizzazione: Workflow nelle tue regole di autorizzazione approva ogni flusso di lavoro, e Workflow(<name>) approva un flusso di lavoro salvato per nome.
  • Modalità di autorizzazione automatica: il classificatore esamina la chiamata e può approvarla.
  • Modalità bypass permissions: Claude Code approva la chiamata.
  • Un hook PreToolUse: un hook che restituisce allow per la chiamata la approva.
  • Il tuo host: un --permission-prompt-tool la approva, o, con l'Agent SDK, un callback canUseTool o un hook PermissionRequest la approva.

Nell'app Desktop, una scheda di approvazione mostra il nome del flusso di lavoro, l'elenco delle fasi e un avvertimento di utilizzo dei token, con azioni Una volta, Sempre e Nega. La vista di progresso appare nel riquadro laterale Attività in background.

I subagenti che il flusso di lavoro genera utilizzano le tue regole di autorizzazione, e Claude Code sceglie la loro modalità di autorizzazione in base alle regole in quale modalità di autorizzazione un subagente viene eseguito in. Per evitare richieste su un'esecuzione lunga, aggiungi gli strumenti di cui gli agenti hanno bisogno alle tue regole di autorizzazione prima di iniziare.

Salvare il flusso di lavoro per il riutilizzo

Quando Claude scrive un flusso di lavoro per un compito che ripeterai, puoi salvare lo script di quell'esecuzione come comando. Un processo come una revisione che esegui su ogni ramo quindi esegue la stessa orchestrazione ogni volta.

Esegui /workflows, seleziona l'esecuzione che vuoi mantenere e premi s. Nella finestra di dialogo di salvataggio, Tab attiva/disattiva tra i due percorsi di salvataggio:

  • .claude/workflows/ nel tuo progetto: condiviso con chiunque cloni il repo
  • ~/.claude/workflows/ nella tua home directory: disponibile in ogni progetto, visibile solo a te. Se imposti CLAUDE_CONFIG_DIR, questa posizione è la directory workflows/ sotto quel percorso.

La finestra di dialogo di salvataggio mostra il percorso risolto per la posizione personale.

Premi Invio per salvare. Il flusso di lavoro viene eseguito come /<name> nelle future sessioni da entrambi i percorsi.

Claude Code controlla il percorso di salvataggio per i symlink prima di scrivere e mostra un errore invece di scrivere attraverso uno. Quello che controlla dipende da dove salvi:

  • Posizione del progetto: Claude Code rifiuta se .claude, .claude/workflows, o il file di destinazione è un symlink.
  • Posizione personale: Claude Code rifiuta solo se il file di destinazione stesso è un symlink, quindi una directory ~/.claude gestita da uno strumento dotfiles funziona comunque.

Prima della v2.1.216, Claude Code seguiva il link, che potrebbe posizionare il file al di fuori della posizione che hai scelto.

In un monorepo con diverse directory .claude/, puoi mantenere i flussi di lavoro insieme al pacchetto a cui si applicano. A partire dalla v2.1.178, il salvataggio nella posizione del progetto scrive nella directory .claude/workflows/ più vicina che già esiste tra la tua directory di lavoro e la radice del repository, o nella radice del repository se non ne esiste ancora nessuna. I flussi di lavoro del progetto si caricano anche da ogni .claude/workflows/ lungo quel percorso, e quando più di uno definisce lo stesso nome Claude Code esegue quello più vicino alla directory di lavoro.

Se un flusso di lavoro di progetto e un flusso di lavoro personale condividono un nome, viene eseguito quello di progetto.

Distribuire un flusso di lavoro in un plugin

Per condividere un flusso di lavoro tra team o repository, includilo in un plugin. Posiziona lo script in una directory workflows/ alla radice del plugin, o punta a una posizione diversa con il workflows campo del manifest.

I flussi di lavoro del plugin sono nello spazio dei nomi del nome del plugin. Un plugin chiamato acme-tools che contiene uno script il cui meta.name è release-audit viene eseguito come /acme-tools:release-audit.

Passare input a un flusso di lavoro salvato

Un flusso di lavoro salvato può accettare input attraverso il parametro args. Lo script lo legge come una variabile globale denominata args. Usa questo per fornire una domanda di ricerca, un elenco di percorsi target o un oggetto di configurazione al momento dell'invocazione invece di modificare lo script per ogni esecuzione.

Il seguente prompt esegue un flusso di lavoro salvato con un elenco di numeri di issue:

Run /triage-issues on issues 1024, 1025, and 1030

Claude passa l'elenco come dati strutturati, quindi lo script può chiamare metodi di array e oggetto su args direttamente senza analizzarlo prima. Se args viene omesso, la variabile globale è undefined all'interno dello script.

Esempi di prompt di flusso di lavoro

Un flusso di lavoro si adatta meglio quando il compito è più grande di quanto un agente possa tenere in contesto, o quando lo stesso passaggio deve essere eseguito su molti elementi. I prompt seguenti mostrano forme comuni. Ognuno chiede a Claude di scrivere ed eseguire un flusso di lavoro per quel compito; non scrivi lo script tu stesso.

Audit di molti file per lo stesso problema

Distribuisci un agente per file, quindi raccogli e verifica i risultati.

use a workflow to audit every route handler under src/routes/ for missing authentication checks, and adversarially verify each finding before reporting it

Continua a correggere finché un controllo non passa

Esegui un controllo, correggi quello che ha fallito e ripeti finché non passa o smette di fare progressi.

use a workflow to run npx tsc --noEmit and keep fixing the reported errors until the type check passes or two rounds in a row make no progress

Migrare molti file in parallelo

Scopri i file da migrare, trasforma ognuno in una copia isolata in modo che le modifiche non entrino in conflitto e verifica ogni risultato.

use a workflow to migrate every component under src/components/ from JavaScript to TypeScript, working on each file in its own isolated copy

Rivedere ogni file modificato e scrivere un riepilogo

Esegui un revisore per file, quindi passa tutti i risultati a un agente che li classifica e deduplica.

use a workflow to review every file changed in this PR for correctness issues, then merge the per-file findings into one ranked summary

Ricercare un argomento su molte fonti

Distribuisci lettori su changelog, issue e documenti, quindi sintetizza. Il flusso di lavoro /deep-research in bundle fa questo; puoi anche descrivere una versione più ristretta.

use a workflow to research how our three competitors handle rate limiting: read their public docs and recent changelog entries in parallel, then compare the approaches

Trovare problemi finché l'elenco non smette di crescere

Continua a cercare in round e fermati quando i nuovi round non trovano nulla di nuovo.

use a workflow to find flaky tests in this repo: run the suite repeatedly, record which tests fail intermittently, and stop once two rounds in a row find nothing new

Come appare lo script salvato

Quando salvi un flusso di lavoro, il file in .claude/workflows/ contiene un blocco meta seguito da un corpo di script che orchestra subagenti. Di solito non hai bisogno di modificarlo, ma ecco la forma di uno piccolo in modo che tu possa riconoscere quello che Claude ha generato:

export const meta = {
  name: 'audit-routes',
  description: 'Audit every route handler for missing auth checks',
}

const found = await agent('List every .ts file under src/routes/.', {
  schema: { type: 'object', required: ['files'], properties: { files: { type: 'array', items: { type: 'string' } } } },
})

const audits = await pipeline(found.files, file =>
  agent(`Audit ${file} for missing authentication checks.`, { label: file }),
)

return audits.filter(Boolean)

Il corpo è JavaScript semplice con await di livello superiore. agent() genera un subagente, pipeline() ne esegue uno per elemento in un elenco, e parallel() esegue un insieme di attività di agente contemporaneamente e attende che tutte si completino.

Una chiamata agent() si risolve in null se la interrompi a metà esecuzione o se raggiunge un errore API irrecuperabile. pipeline() mantiene quel null nell'array dei risultati, motivo per cui l'esempio termina con .filter(Boolean) per eliminare quelle voci.

Se passi uno schema su una chiamata agent(), quel subagente restituisce JSON corrispondente alla forma invece di prosa. Claude Code verifica lo schema prima di avviare il subagente: quando può provare che lo schema contraddice se stesso, la chiamata fallisce con un errore che nomina la contraddizione, e il subagente non viene mai avviato. Una contraddizione che può provare è una chiave required che additionalProperties: false esclude.

Se l'output del subagente non supera ancora la convalida dopo cinque tentativi, la chiamata fallisce con un errore che include l'ultimo errore di convalida. Per modificare il numero di tentativi, imposta MAX_STRUCTURED_OUTPUT_RETRIES.

Modifica uno script salvato

Per modificare un flusso di lavoro che hai salvato, modifica il suo file .js o chiedi a Claude di apportare la modifica. Prima di modificare o chiedere, esegui la skill in bundle /workflow-authoring per caricare il riferimento di scrittura di script da cui Claude lavora. La skill richiede Claude Code v2.1.248 o successivo.

Per eseguire la versione modificata nella sessione corrente, esegui /reload-skills per rileggere le directory dei flussi di lavoro, quindi esegui di nuovo /<name>.

Claude Code applica queste regole a ogni parte del file quando carica ed esegue lo script:

  • Blocco meta: mantieni export const meta come prima istruzione e mantienilo un oggetto letterale semplice con un name e una description. Se contiene qualcosa di diverso da valori letterali, come una variabile, una chiamata di funzione o uno spread, Claude Code elimina /<name> dall'autocompletamento di /.
  • Corpo: oltre a agent(), pipeline() e parallel(), puoi chiamare phase() per raggruppare gli agenti che seguono sotto un titolo nella vista di avanzamento, chiamare log() per mostrare un messaggio sopra le fasi, e leggere il global args. Se il corpo ha un errore di sintassi, Claude Code lo segnala quando esegui il flusso di lavoro.
  • phases: se le elenca in meta, dai a ogni voce esattamente il titolo che passi a phase(). Un titolo phase() senza voce ottiene il suo proprio gruppo di avanzamento.
  • Timestamp e casualità: Claude Code fa sì che Date.now(), Math.random() e un new Date() senza argomenti lancino un'eccezione all'interno dello script, in modo che un'esecuzione rilanciata ripeta le stesse chiamate agent(). Passa invece un timestamp attraverso args.

Puoi anche modificare lo script di una singola esecuzione piuttosto che la copia salvata. Riprendi dopo una pausa copre quali agenti vengono eseguiti di nuovo quando riavvii uno script modificato. Per gli input dello strumento Workflow, vedi la sua voce nel riferimento dell'Agent SDK.

Come viene eseguito un flusso di lavoro

Il runtime del flusso di lavoro esegue lo script in un ambiente isolato, separato dalla tua conversazione. I risultati intermedi rimangono nelle variabili dello script invece di finire nel contesto di Claude.

Ogni esecuzione scrive il suo script in un file nella directory della tua sessione in ~/.claude/projects/. Claude riceve il percorso quando l'esecuzione inizia, quindi puoi chiederglielo. Puoi aprire quel file per leggere l'orchestrazione che Claude ha scritto, confrontarlo con lo script di un'esecuzione precedente, o modificarlo e chiedere a Claude di riavviare dalla versione modificata.

Claude può avviare un flusso di lavoro solo da un file di script che la sessione è già autorizzata a leggere. Per eseguire uno script mantenuto al di fuori della tua directory di lavoro, aggiungi prima la sua directory con /add-dir o una regola di autorizzazione Read.

Il runtime traccia il risultato di ogni agente mentre l'esecuzione progredisce, il che è quello che rende un'esecuzione riprendibile all'interno della stessa sessione.

Prompt caching in un fan-out

Gli agenti nella stessa esecuzione possono leggere la prompt cache l'uno dell'altro. Due agenti che vengono eseguiti con lo stesso modello, livello di sforzo, tipo di agente, strumenti, schema di output e directory di lavoro costruiscono lo stesso prefisso di strumenti e prompt di sistema, quindi un agente che inizia dopo che la risposta di un fratello corrispondente ha iniziato legge la cache di quel fratello nella sua prima richiesta.

Le richieste di un agente del flusso di lavoro rientrano al di fuori del bucket cache TTL della conversazione principale, quindi la sua cache dura cinque minuti per impostazione predefinita, incluso su un abbonamento Claude. Per mantenerla per un'ora, imposta subagentPromptCacheTtl su 1h. L'API fattura le scritture della cache di 1 ora a una tariffa più elevata.

Quando un fan-out avvia diversi agenti corrispondenti contemporaneamente, Claude Code tiene tutti tranne il primo fino a quando la risposta del primo agente non inizia, quindi rilascia gli agenti trattenuti insieme in modo che le loro prime richieste leggano il prefisso condiviso invece di elaborarlo ciascuno senza cache. Claude Code limita la sospensione a CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS millisecondi, 5000 per impostazione predefinita. Impostalo su 0 per disabilitare la sospensione.

Comportamento e limiti

Il runtime applica i seguenti vincoli:

Vincolo Perché
Nessun input dell'utente durante l'esecuzione Solo i prompt di autorizzazione dell'agente possono mettere in pausa un'esecuzione. Per l'approvazione tra le fasi, esegui ogni fase come suo proprio flusso di lavoro
Nessun accesso diretto al filesystem o shell dallo script del flusso di lavoro stesso Gli agenti leggono, scrivono ed eseguono comandi. Lo script coordina gli agenti
Nessun caricamento di moduli: uno script che contiene import() non riesce prima dell'inizio dell'esecuzione Il corpo dello script è JavaScript semplice. Metti il lavoro che necessita di una libreria nel compito di un agente
Fino a 16 agenti concorrenti, meno quando Claude Code ha meno CPU disponibili, incluso all'interno di un contenitore con limitazione di CPU Limita l'uso delle risorse locali
In un fan-out, gli agenti che condividono il prefisso della prompt-cache del primo agente si avviano fino a 5 secondi dopo per impostazione predefinita Tutti tranne il primo leggono il prefisso che il primo agente ha memorizzato nella cache invece di elaborarlo ciascuno senza cache
Fino a 4.096 elementi in una singola chiamata parallel() o pipeline(): il runtime rifiuta un elenco più lungo con un errore Un limite silenzioso farebbe cadere parte del carico di lavoro senza dirlo allo script
1.000 agenti totali per esecuzione Previene cicli incontrollati

Gestire le esecuzioni

Una volta che un'esecuzione inizia, la gestisci dalla vista /workflows, o espandendo la sua riga di progresso nel pannello attività sotto la casella di input.

Quando fermi un'esecuzione, rimane nel pannello attività mentre uno qualsiasi dei processi dei suoi agenti è ancora in esecuzione. Se la fermi di nuovo, Claude Code invia nuovamente segnali a quei processi.

Riprendere dopo una pausa

Riprendi un'esecuzione in pausa da /workflows selezionandola e premendo p. Per un'esecuzione che hai fermato, chiedi a Claude di riavviare il flusso di lavoro con lo stesso script. Se gli agenti dall'esecuzione fermata non sono ancora usciti, Claude Code rifiuta il riavvio finché non lo fanno, quindi una seconda copia di quegli agenti non può essere eseguita insieme a loro.

Claude Code riproduce l'esecuzione nell'ordine in cui gli agenti hanno iniziato, e ogni agente restituisce il suo risultato salvato o viene eseguito di nuovo:

  • Completato: restituisce il suo risultato salvato. Il primo agente il cui prompt differisce dall'esecuzione precedente, perché hai modificato lo script o un agente precedente ha restituito qualcosa di diverso, viene eseguito di nuovo, così come ogni agente dopo di esso, anche quelli che hanno completato.
  • Ancora in esecuzione quando hai fermato: ricomincia da capo. Fermare l'intera esecuzione non conta alcun agente come fallito.
  • Fallito: viene eseguito di nuovo, così come ogni agente che ha iniziato dopo di esso, anche quelli che hanno completato. Fermare un solo agente, selezionandolo in /workflows e premendo x, conta come fallimento.

Quest'ultimo caso significa che un fallimento nel mezzo di un fan-out riesegue il lavoro che era già terminato. Se uno script avvia A, B, C e D in quell'ordine e B fallisce, il riavvio restituisce A dalla cache ed esegue di nuovo B, C e D.

Puoi riprendere un'esecuzione all'interno della stessa sessione di Claude Code. Quello che accade a un flusso di lavoro in esecuzione quando lasci la sessione dipende da come la lasci:

  • Se metti la sessione in background, Claude Code riproduce l'esecuzione allo stesso modo nella sessione in background e la continua.
  • Se esci da Claude Code mentre un flusso di lavoro è in esecuzione e agent view è attivato, la finestra di dialogo di uscita offre Move to background and exit, che trasporta l'esecuzione allo stesso modo. Se scegli invece Exit and stop tasks, o l'opzione non è offerta, l'esecuzione si ferma con la sessione. Claude Code mantiene i risultati salvati dell'esecuzione nella directory di quella sessione in ~/.claude/projects/, quindi una sessione che riprendi con claude --resume può riprodurli quando chiedi a Claude di riavviare il flusso di lavoro, mentre una sessione che avvii da zero non ha nulla da riprodurre e avvia il flusso di lavoro da capo.

Costo

Un flusso di lavoro genera molti agenti, quindi una singola esecuzione può usare significativamente più token rispetto al lavoro attraverso lo stesso compito in conversazione. Le esecuzioni contano verso l'utilizzo del tuo piano e i limiti di velocità come qualsiasi altra sessione.

Per valutare la spesa prima di impegnarsi in un compito di grandi dimensioni, esegui il flusso di lavoro su una piccola porzione prima: una directory invece dell'intero repository, o una domanda ristretta invece di una ampia. La vista /workflows mostra l'utilizzo dei token di ogni agente mentre l'esecuzione progredisce, e puoi fermare l'esecuzione lì in qualsiasi momento, solitamente senza perdere il lavoro completato. Riprendere dopo una pausa copre quello che un'esecuzione fermata mantiene. I limiti degli agenti del runtime limitano quanti agenti una singola esecuzione può generare, il che limita il costo di uno script fuori controllo. Per mantenere le esecuzioni a meno agenti, scegli la linea guida sulla dimensione small .

Claude Code inoltre segnala un'esecuzione che cresce insolitamente. Quando un flusso di lavoro pianifica più di 25 agenti, o il suo totale di token previsto supera 1,5 milioni, la sua riga di progresso nel pannello attività sotto la casella di input mostra un avviso Large workflow. L'avviso ti indirizza a /workflows, dove puoi fermare l'esecuzione.

L'avviso è consultivo: non mette in pausa o limita l'esecuzione. Due impostazioni cambiano quando lo vedi:

  • Se scegli una linea guida sulla dimensione tu stesso, il numero di agenti della linea guida sostituisce la soglia di 25 agenti. La linea guida predefinita incorporata lascia la soglia a 25.
  • Le sessioni con ultracode attivato non mostrano l'avviso, perché attivare ultracode già ti consente di optare per esecuzioni di grandi dimensioni.

Claude Code sceglie il modello di ogni agente del flusso di lavoro nello stesso ordine che usa per i subagenti. Un modello che lo script nomina per una fase conta come il modello per invocazione in quell'ordine. Quando nient'altro ne assegna uno, l'agente viene eseguito sul modello della tua sessione.

Per controllare il costo del modello:

  • Controlla /model prima di un'esecuzione grande se di solito passi a un modello più piccolo per il lavoro di routine
  • Chiedi a Claude di usare un modello più piccolo per le fasi che non hanno bisogno di quello più forte quando descrivi il compito

Quando l'allowlist availableModels della tua organizzazione blocca un modello che lo script richiede per un agente, quell'agente viene eseguito su un modello sostituito invece, seguendo le stesse regole di sostituzione dei subagenti. La vista di progresso dell'esecuzione in /workflows mostra un avviso che nomina sia i modelli richiesti che quelli sostituiti.

Imposta una linea guida sulla dimensione

Una linea guida sulla dimensione dice a Claude quanti agenti mirare quando scrive un flusso di lavoro dinamico. Claude Code invia la linea guida a Claude come consiglio, non come limite, quindi un prompt che richiede una scala diversa la sovrascrive comunque. Richiede Claude Code v2.1.202 o successivo.

Ogni valore corrisponde a un numero di agenti:

Valore Numero di agenti a cui Claude mira
unrestricted Nessuna linea guida: Claude dimensiona il flusso di lavoro al compito
small Meno di 5 agenti
medium Meno di 15 agenti
large Meno di 50 agenti

Il valore predefinito è medium. Finché non scegli un valore, la riga /config mostra medium (default) e la riga Running in background del flusso di lavoro mostra medium size (/config). Richiede Claude Code v2.1.219 o successivo; le versioni precedenti hanno come valore predefinito unrestricted.

Per cambiare la linea guida, scegli un valore per l'impostazione Dynamic workflow size in /config, o esegui /config workflowSizeGuideline=small. Su v2.1.219 e successivo, puoi anche impostare la chiave workflowSizeGuideline in qualsiasi file di impostazioni; quel valore ha la precedenza su /config, e Claude Code nasconde la riga /config mentre un file di impostazioni ne fornisce uno.

Le modifiche hanno effetto al prompt successivo. I limiti degli agenti del runtime si applicano comunque indipendentemente dall'impostazione.

Disattivare i flussi di lavoro

I flussi di lavoro sono disponibili nel CLI, nell'app Desktop, nelle estensioni IDE, modalità non interattiva con claude -p, e nell'Agent SDK. Le stesse impostazioni di disabilitazione si applicano su ogni superficie.

Per disattivare i flussi di lavoro per te:

  • Attiva/disattiva Dynamic workflows in /config. Persiste tra le sessioni.
  • Imposta "disableWorkflows": true in ~/.claude/settings.json. Persiste tra le sessioni.
  • Imposta CLAUDE_CODE_DISABLE_WORKFLOWS=1. Letto all'avvio, quindi si applica ovunque lo imposti.

Per disattivare i flussi di lavoro per tutta la tua organizzazione, imposta "disableWorkflows": true in impostazioni gestite, o usa l'interruttore sulla pagina impostazioni amministratore di Claude Code.

Quando i flussi di lavoro sono disabilitati, i comandi di flusso di lavoro in bundle e la skill /workflow-authoring non sono disponibili, la parola chiave ultracode non attiva più un'esecuzione, e ultracode viene rimosso dal menu /effort.