Claude Code per i fallimenti CI: prompt per piccole correzioni e test

Cosa va storto quando CI fallisce e l'IA azzarda

Un fallimento CI di solito non è misterioso. Il log ti dice dove si è fermato, quale comando è fallito e il messaggio d'errore. Una buona esecuzione include uno stack trace, un errore del compilatore con file e numero di riga, o un report dei test che mostra quale asserzione è fallita. A volte ottieni anche un indizio in stile diff come "expected X, got Y" o un passo chiaramente fallito come "lint", "build" o "migrate database".

Il vero problema è che le persone (e l'IA) spesso trattano il log come rumore di fondo. Se incolli un log lungo e chiedi "una correzione", molti modelli saltano a una spiegazione familiare invece di leggere le ultime righe significative. Le supposizioni peggiorano quando l'errore sembra comune ("module not found", "timeout", "permission denied"). Finisci con una grande riscrittura, una nuova dipendenza o un suggerimento del tipo "prova ad aggiornare tutto" che non corrisponde al fallimento reale.

L'obiettivo non è "farlo passare in qualche modo". È più semplice:

• Leggi l'output di errore.
• Identifica la modifica più piccola che fa riuscire lo step fallito.
• Mantieni tutto il resto invariato.

Nella pratica, la "correzione minima" è di solito una di queste: una modifica di poche righe in un solo punto, un import mancante o un percorso sbagliato, un valore di config chiaramente errato per l'ambiente CI, o il revert di una modifica accidentale che ha rotto tutto invece di ridisegnare il codice.

Anche un test di follow-up è importante. Far passare CI una volta non equivale a prevenire ricorrenze. Se il fallimento è nato da un caso limite (input null, fuso orario, arrotondamenti, permessi), aggiungi un test di regressione che fallisca prima della correzione e passi dopo. Questo trasforma un salvataggio occasionale in una barriera protettiva.

Cosa raccogliere prima di chiedere aiuto

La maggior parte delle cattive correzioni inizia con contesto mancante. Se incolli solo l'ultima riga rossa, il modello deve indovinare cosa è successo prima, e le congetture spesso diventano riscritture.

Cerca di fornire abbastanza dettagli perché qualcuno possa seguire il fallimento dal primo errore reale fino alla fine, poi cambiare il meno possibile.

Copia questo nel tuo messaggio (verbatim quando puoi):

• Il log completo fallito dalla prima riga di errore fino alla fine (non solo lo stack trace finale).
• Il comando esatto che CI ha eseguito (per esempio, go test ./..., npm test, flutter test, golangci-lint run).
• I percorsi file menzionati nell'errore, più eventuali config rilevanti (config test, config del linter, script di build).
• Cosa è cambiato di recente: sommario diff della PR, bump di dipendenze, modifiche di config CI.
• Se è flakiness: due o tre run fallite e una passata, se le hai.

Aggiungi vincoli in parole semplici. Se vuoi una correzione minima, dillo: niente refactor, nessun cambiamento di comportamento a meno che non sia necessario, mantieni la patch limitata all'area fallita.

Un esempio semplice: CI fallisce a uno step di lint dopo un bump di dipendenza. Incolla l'output del lint a partire dal primo warning, includi il comando che CI ha usato e menziona la singola modifica di versione del package. Questo è sufficiente per suggerire una modifica di config di una riga o una piccola correzione al codice, invece di riformattare metà del repo.

Se vuoi qualcosa pronto da incollare, questa struttura di solito basta:

CI command:

Failing output (full):

Recent changes:

Constraints (smallest fix, no refactor):

Flaky? (runs attached):

Regole di prompt che costringono a leggere l'output fallito

Quando un modello sbaglia su un break CI, è di solito perché il tuo prompt gli permette di indovinare. Il tuo compito è farlo mostrare il suo lavoro usando l'esatto output fallito, poi impegnarsi sulla modifica più piccola che potrebbe far passare il job.

Regole che mantengono il modello onesto

Richiedi evidenze e un piano minimo. Un buon prompt forza cinque cose:

• Cita le esatte righe fallite del log CI (errori, stack trace, file:linea) e dì esplicitamente "Sto usando queste righe."
• Dai una diagnosi in una frase, senza attenuanti.
• Proponi un piano di patch minimale con 1–3 modifiche, nominando i file esatti che toccherà.
• Evita cambi non correlati (niente formattazione, rinomi, refactor, bump di dipendenze) a meno che tu non li approvi.
• Elenca cosa non è sicuro e il singolo dettaglio che confermerebbe la diagnosi.

L'incertezza va bene. L'incertezza nascosta è ciò che fa perdere tempo.

Frammento di prompt pronto da incollare

Incolla questo all'inizio della tua domanda su CI:

Use ONLY the evidence in the CI output below.
1) Quote the exact failing lines you are using.
2) Give ONE sentence: the most likely cause.
3) Propose the smallest fix: 1-3 edits, with file paths.
4) Do NOT do formatting/renames/refactors or "cleanup".
5) List uncertainties + the one extra detail that would confirm the diagnosis.

Se il log dice "expected 200, got 500" più uno stack trace in user_service.go:142, questa struttura spinge la risposta verso quella funzione e una piccola clausola di guardia o gestione dell'errore, non verso un ridisegno dell'endpoint.

Un template di prompt pronto per i fallimenti CI

I guadagni più rapidi arrivano da un prompt che forza la citazione dei log, resta nei vincoli e si ferma quando manca qualcosa.

You are helping me fix a CI failure.

Repo context (short):
- Language/framework:
- Test/build command that failed: <PASTE THE EXACT COMMAND>
- CI environment (OS, Node/Go/Python versions, etc.):

Failing output (verbatim, include the first error and 20 lines above it):
<PASTE LOG>

Constraints:
- Propose the smallest possible code change that makes CI pass.
- Do NOT rewrite/refactor unrelated code.
- Do NOT touch files you do not need for the fix.
- If behavior changes, make it explicit and justify why it is correct.

Stop rule (no guessing):
- If the log is incomplete or you need more info (missing stack trace, config, versions, failing test name), STOP and ask only the minimum questions needed.

Your response format (follow exactly):
1) Evidence: Quote the exact log lines that matter.
2) Hypothesis: Explain the most likely cause in 2-4 sentences.
3) Smallest fix: Describe the minimal change and why it addresses the evidence.
4) Patch: Provide a unified diff.
5) Follow-up: Tell me the exact command(s) to rerun locally to confirm.

Then, write ONE regression test (or tweak an existing one) that would fail before this fix and pass after it, to prevent the same failure class.
- Keep the test focused. No broad test suites.
- If a test is not feasible, explain why and propose the next-best guardrail (lint rule, type check, assertion).

Due dettagli riducono i giri di andata e ritorno:

• Includi il comando esatto fallito e il primo errore (non solo il riepilogo finale).
• Se ci sono più fallimenti, dì quale risolvere per primo (di solito il primo errore reale nel log).

Come spingere per la correzione minima, non per una riscrittura

Il modo più rapido per perdere tempo è accettare una modifica di "pulizia" che modifica cinque cose insieme. Definisci "minimale" fin da subito: la diff più piccola che fa passare il job fallito, con il minor rischio e il modo più veloce per verificarla.

Una regola semplice funziona: risolvi il sintomo prima, poi valuta se un refactor più ampio vale la pena. Se il log punta a un file, una funzione, un import mancante o un caso limite, mira lì. Evita le modifiche del tipo "tanto ne approfitto".

Se hai davvero bisogno di alternative, chiedi due e solo due: "correzione minimale più sicura" vs "correzione minimale più veloce." Vuoi compromessi, non un menu.

Richiedi anche la verifica locale che corrisponda a CI. Chiedi lo stesso comando che la pipeline esegue (o l'equivalente più vicino), così puoi confermare in pochi minuti:

# run the same unit test target CI runs
make test
# or the exact script used in CI
npm test

Se la risposta suggerisce una grande modifica, contrasta con: "Mostrami la patch più piccola che corregge l'asserzione fallita, senza formattazioni o rinomi non correlati."

Prompt per un test di follow-up che prevenga ricorrenze

Una correzione senza test è una scommessa che il problema non si ripresenterà. Chiedi sempre un test di regressione che fallisca prima della correzione e passi dopo.

Sii specifico su cosa significhi "buono":

• Se il fallimento era un crash di unit test, probabilmente vuoi un test nuovo o un'asserzione più forte.
• Se il fallimento era build, lint o una regola di formattazione, vuoi un controllo che imponga la regola in modo che lo stesso tipo di errore non possa rientrare.

Uno schema utile richiede quattro cose: dove mettere il test, come chiamarlo, quale comportamento deve coprire e una breve nota che spiega perché previene regressioni future.

Frammento pronto da aggiungere:

• Scrivi un test di regressione che fallisce sul branch main attuale e passa dopo la tua correzione.
• Fai in modo che il test copra la stessa classe di fallimento, non solo la riga esatta che ha rotto.
• Metti il test in: <path or folder>. Segui la convenzione di naming: <your convention>.
• Se si tratta di una regola lint/build, aggiungi o regola un controllo che imponga la regola.
• Aggiungi 2-3 frasi: perché questo test catturerebbe un bug simile in futuro.

Esempio: CI mostra un panic quando un handler API riceve un ID vuoto. Non chiedere "un test per questa riga." Chiedi un test che copra ID non validi (vuoto, spazi bianchi, formato sbagliato). La correzione minima potrebbe essere una clausola di guardia che restituisce 400. Il test di follow-up deve assertare il comportamento per più input non validi, così la prossima volta che qualcuno rifattorizza il parsing, CI fallisce subito.