Modalità non interattiva

Claude Code utilizza per impostazione predefinita una sessione di terminale interattiva: vi pone domande, attende il vostro input e trasmette una conversazione. Questo modello è perfetto alla vostra scrivania, ma inutilizzabile all'interno di una pipeline.

Un runner CI/CD non ha nessun essere umano che possa confermare un piano, approvare una modifica o rispondere a una domanda successiva. Ha bisogno di un singolo comando che venga eseguito, produca un output e termini con un codice di stato.

È esattamente ciò che offre -p / --print: un'esecuzione non interattiva (headless). È il flag fondamentale per eseguire Claude Code in CI.

Si attiva la modalità headless passando il prompt a -p, la forma breve di --print. Claude esegue il ciclo agentico fino al completamento e stampa il risultato finale su stdout, quindi il processo termina.

Non ci sono REPL, attese di input o richieste di conferma. Un comando in ingresso, un risultato in uscita: è il contratto di cui ha bisogno un passaggio della pipeline.

In pratica, -p diventa un passaggio all'interno di un job. Il runner effettua il checkout del codice, quindi chiama Claude con un'istruzione precisa. Poiché il processo termina quando il ciclo raggiunge end_turn, la pipeline passa naturalmente al passaggio successivo.

Mantenete il prompt circoscritto ed esplicito: non c'è nessun essere umano che possa chiarire un'ambiguità durante l'esecuzione, quindi l'istruzione deve essere autosufficiente.

Il testo semplice va bene per una persona che legge i log, ma una pipeline di solito deve agire sul risultato: pubblicare un commento, impostare lo stato di un controllo o bloccare un merge.

Aggiungete --output-format json affinché Claude produca un risultato strutturato e leggibile dalle macchine, anziché testo libero. Il passaggio successivo potrà quindi analizzare i campi in modo deterministico con jq o con uno script.

Il solo JSON lascia comunque al modello la possibilità di scegliere la propria struttura. Per un'automazione affidabile, abbinate --output-format json a uno schema, così ogni esecuzione restituisce gli stessi campi. Questo elimina le sorprese sintattiche e consente di richiedere esattamente le chiavi utilizzate dalla pipeline.

Applicate la stessa disciplina dell'output strutturato usata nell'API: contrassegnate un campo come obbligatorio solo se è sempre presente. Non imponete mai un campo che potrebbe legittimamente essere assente, altrimenti il modello lo inventerà.

Un punto sottile, ma fondamentale per l'esame: quando Claude genera il codice e poi lo revisiona nella stessa sessione, la revisione è soggetta a distorsioni: l'autore conserva il proprio ragionamento e non tende a metterlo in discussione.

In CI, eseguite la revisione in una sessione nuova e isolata, separata da qualsiasi contesto di generazione. Un'istanza indipendente ha molte più probabilità di individuare difetti reali. Questo riflette la regola generale: una revisione indipendente è migliore dell'auto-verifica nella stessa sessione.

Un revisore CI che segnala continuamente problemi inesistenti finisce per essere ignorato. L'obiettivo è la precisione: portare alla luce i veri blocchi e restare silenziosi negli altri casi.

La leva è il prompt, non una richiesta vaga. I criteri espliciti sono migliori delle richieste generiche: "segnalare un commento solo quando contraddice il codice" è più efficace di "essere più precisi". Alcuni esempi few-shot mirati (2-4) di veri positivi e falsi positivi calibrano ulteriormente il modello sui vostri casi limite.

Un'esecuzione headless procede senza approvazione umana, quindi l'accesso illimitato agli strumenti è rischioso. Concedete solo ciò che serve al job.

Per una revisione in sola lettura, in genere sono sufficienti Read, Grep e Glob, non Write, Edit o Bash arbitrario. È lo stesso principio del privilegio minimo che applicate ai set di strumenti degli agenti: limitate gli strumenti in base al ruolo e mantenete ridotto il set per una selezione affidabile.

Anche in modalità headless, il ciclo agentico non cambia: richiesta -> esaminare stop_reason -> se tool_use, eseguire gli strumenti e continuare -> ripetere fino a end_turn. Il processo termina quando il modello raggiunge end_turn.

Non racchiudete Claude in uno script che cerchi nell'output parole come "done" o "finished" per decidere se l'esecuzione è completata. La terminazione è determinata dal motivo di arresto. Qualsiasi limite al numero di iterazioni impostato è una rete di sicurezza, mai il meccanismo principale di arresto.

La CI viene eseguita nuovamente di continuo: ogni push riattiva il job. Se il revisore segnala ogni volta gli stessi cinque problemi, il segnale viene sommerso dal rumore.

In una nuova esecuzione, passate a Claude i risultati precedenti e chiedetegli di riportare solo i problemi nuovi o ancora irrisolti. In questo modo ogni commento resta utile e si tiene conto del fatto che gli sviluppatori hanno già visto i risultati precedenti.

Non confonda l'esecuzione CLI non interattiva con la Message Batches API. Risolvono problemi diversi.

• -p / --print: sincrono, bloccante, restituisce il risultato immediatamente — corretto per un gate pre-merge in cui la pipeline attende il verdetto.
• Batch API: costa il 50% in meno, offre una finestra fino a 24 ore, nessuno SLA sulla latenza e non supporta chiamate agli strumenti su più turni — corretta per audit notturni non bloccanti, mai per un controllo bloccante sensibile ai tempi.

Una revisione pre-merge deve bloccare la pipeline, quindi usi -p; ricorra a Batch solo per processi offline e non urgenti.

Punti chiave della modalità non interattiva:

• -p / --print è il flag richiesto per l'esecuzione CI headless: esegue il ciclo fino al completamento, stampa su stdout ed esce.
• --output-format json (idealmente con uno schema) rende i risultati analizzabili, permettendo alla pipeline di agire di conseguenza; richieda solo i campi sempre presenti.
• Esegua la revisione in una sessione isolata e nuova: una revisione indipendente è migliore di un'autorevisione distorta nella stessa sessione.
• Aumenti la precisione con criteri espliciti ed esempi few-shot per ridurre al minimo i falsi positivi.
• Applichi strumenti con privilegi minimi nelle esecuzioni non presidiate; nelle riesecuzioni segnali solo i problemi nuovi o non risolti.
• La terminazione dipende dal motivo di arresto, mai dall'analisi del testo; i limiti di iterazione sono solo una rete di sicurezza.
• Usi -p per i gate pre-merge bloccanti; riservi la Batch API ai processi non bloccanti e non urgenti.