Mettere un agente di coding in CI è un problema di progettazione dei permessi travestito da problema di produttività. La meccanica è il lavoro di un pomeriggio: la modalità headless è disponibile da Claude Code 2.0, uscito a settembre 2025, e anthropics/claude-code-action@v1 incapsula tutto in una GitHub Action. Puoi avere un agente che commenta le pull request prima di pranzo. Se debba anche pushare commit è una domanda diversa, ed è l'unica che conta davvero.

La regola che mantiene tutto questo sicuro è semplice: un agente in CI propone, non fa merge. Ogni pattern qui sotto è una variazione su dove tracci quella linea.

Modalità headless, in breve

Il flag -p (o --print) fa uscire Claude Code dal REPL interattivo e lo porta a una singola invocazione batch, il che è ciò che lo rende scriptabile. I flag che lo trasformano da demo in qualcosa che puoi far girare senza supervisione sono quelli che impongono vincoli:

claude -p "Fix the failing unit tests. Do not change public APIs." \
  --output-format json \
  --max-turns 8 \
  --allowedTools "Read,Edit,Bash(npm test)" \
  --model claude-haiku-4-5

Ognuno di questi fa un lavoro reale. --output-format json restituisce un oggetto con result, model, usage, e stop_reason, così la tua pipeline può ramificare in base all'esito invece di fare grep sulla prosa. --max-turns è il tuo circuit breaker. --allowedTools è l'allowlist, ed è il flag singolarmente più importante della riga.

I tre pattern, in ordine crescente di audacia

I team finiscono in uno di tre posti. Non sono equivalenti, e la maggior parte dei team dovrebbe fermarsi al secondo.

  • Consultivo. L'agente legge il diff e commenta. Non ha accesso in scrittura a nulla. Ogni segnalazione costa a un umano trenta secondi per accettarla o scartarla. È qui che si comincia, e per molti team è anche qui che ci si ferma.
  • Proponente. L'agente sistema qualcosa e apre una pull request sul branch. Scrive codice, ma il pulsante di merge resta umano. Il gate di review di cui già ti fidi fa il lavoro per cui è stato costruito. È il punto di equilibrio.
  • Autonomo. L'agente committa su un branch che va in deploy. È il pattern che si vede nelle demo ed è quello che genera incidenti, perché la CI è l'unico posto nel tuo stack dove un attore malevolo diventa un artefatto deployato senza un umano nel loop.

Nota cosa cambia tra questi tre livelli: non la capacità dell'agente, solo il raggio d'esplosione di un errore. La probabilità che l'agente sbagli è la stessa in tutti e tre i casi. La differenza è cosa succede dopo.

Il modo di fallire che nessuno pianifica

La preoccupazione ovvia è che l'agente scriva codice cattivo. Quella è già gestita: i tuoi test e i tuoi reviewer intercettano il codice cattivo, ed è esattamente per questo che esistono.

Il fallimento reale è più sottile. Un agente a cui viene detto di far diventare verde la build ha esattamente un obiettivo, e c'è più di un modo per raggiungerlo. Cancellare l'assertion che fallisce fa diventare verde la build. Aggiungere skip al test fa diventare verde la build. Allargare un tipo ad any fa sparire l'errore di tipo. Nessuno di questi casi è un malfunzionamento dell'agente. È l'agente che fa esattamente ciò che gli hai chiesto, in un modo che non intendevi, perché la tua istruzione descriveva il sintomo e non l'obiettivo.

Due cose aiutano. Scrivi l'obiettivo come vincolo, non come traguardo: "sistema l'implementazione affinché i test esistenti passino, senza modificare i file di test" è un'istruzione diversa da "sistema la build". E imponilo a livello strutturale invece di fidarti della prosa, perché la prosa è una richiesta e un'allowlist di tool è una regola.

Guardrail che sono davvero portanti

  • Limita l'allowlist dei tool al compito. Un agente che sistema i test deve leggere file, modificare il sorgente ed eseguire il comando di test. Non ha bisogno di accesso alla rete, non ha bisogno di toccare la configurazione della CI, e non ha bisogno delle credenziali di deploy che magari si trovano nell'ambiente del runner.
  • Proteggi i file che definiscono la correttezza. Test, lockfile, workflow di CI e policy IAM appartengono a una denylist di path. Se l'agente non può modificare il test, non può cancellare il test per farlo passare.
  • Metti un tetto ai turni e ai token. Un loop che non può convergere dovrebbe fermarsi e dirlo. Un agente senza tetto che si arrabatta su un compito impossibile è una bolletta e una coda di job bloccati.
  • Dai al runner un'identità propria. Non un ruolo admin ampio che si trova lì per caso. Il job dell'agente gira con un ruolo delimitato, con i permessi che servono a quel solo compito, così un agente confuso non può allungare la mano su qualcosa che non avrebbe mai dovuto avere.
  • Tratta i commit dell'agente come input non fidato. Stessi check obbligatori, stessa review, stessa branch protection di qualsiasi contributor. L'agente non ha corsie preferenziali, perché la corsia preferenziale è la vulnerabilità.
  • Logga l'intera sessione. Quando una modifica scritta da un agente causa un incidente alle tre di notte, "cosa gli è stato detto e cosa ha fatto" ha bisogno di una risposta che non sia un'alzata di spalle. L'output JSON più il transcript della sessione è la tua audit trail. Conservala.

L'economia è davvero buona

Vale la pena essere onesti con l'idea: i numeri sono favorevoli. Un passaggio di review automatizzato su un diff di medie dimensioni costa pochi centesimi e finisce in meno di un minuto. Contro il costo del cambio di contesto di un reviewer umano, quell'aritmetica torna a quasi qualsiasi volume di pull request, ed è esattamente per questo che il pattern si sta diffondendo.

Ma è anche la trappola. Abbastanza economico da girare su ogni PR è abbastanza economico da girare senza pensarci, e il costo marginale di aggiungere un altro permesso all'allowlist è sempre zero nel momento in cui lo aggiungi. Il costo arriva dopo, tutto insieme. Decidi il confine mentre è ancora teorico.

Il punto

Un agente nella tua pipeline è un contributor senza giudizio, con pazienza infinita e qualunque credenziale tu abbia dato al runner. Dagli gli strumenti stretti per un solo compito, proteggi i file che codificano cosa significa "corretto", metti un tetto al loop, e fallo aprire una pull request come chiunque altro. La produttività è reale. Viene dall'agente che fa il primo passaggio tedioso, non dall'eliminare l'umano che dice sì.

Leggi questo dopo

Per il lato pipeline di tutto questo, perché i test automatizzati sono essenziali nella tua pipeline CI/CD copre i check che l'output di un agente deve superare, su ercan.cloud. L'hub è su ercanermis.com.