Usa un flusso Prompt-to-PR con Claude Code in locale: scrivi prompt piccoli, consegna diff ridotte, esegui controlli, re-prompta sui fallimenti e raggiungi PR pronte per il merge.
I grandi prompt one-shot spesso portano a cambiamenti estesi e disordinati: dozzine di file modificati, refactor non correlati e codice che non hai avuto il tempo di capire. Anche se il risultato è tecnicamente corretto, la review sembra rischiosa perché è difficile capire cosa è cambiato e perché.
Le piccole modifiche risolvono questo problema. Quando ogni cambiamento è limitato e mirato, puoi leggerlo in pochi minuti, individuare errori presto e evitare di rompere parti non volute. I revisori si fidano di più delle piccole PR, quindi i merge avvengono più velocemente e con meno commenti in loop.
Prompt-to-PR è un ciclo semplice:
Questa cadenza trasforma i fallimenti in feedback rapidi invece che in sorprese alla fine. Se chiedi a Claude Code di aggiustare una regola di validazione, limitati a quella regola. Se un test fallisce, incolla l'output che fallisce e chiedi la minima correzione che fa passare il test, non la riscrittura dell'intero modulo.
Una cosa non cambia: sei comunque responsabile del codice finale. Tratta il modello come un pair programmer locale che digita veloce, non come un pilota automatico. Sei tu a decidere cosa entra, cosa resta fuori e quando è sicuro aprire la PR.
Parti da una baseline pulita. Se il tuo branch è indietro o i test già falliscono, ogni suggerimento diventa congettura. Pulla gli ultimi cambiamenti, rebase o merge come preferisce il team e assicurati che lo stato corrente sia sano prima di chiedere qualsiasi cosa.
Un setup di “pair programmer locale” significa che Claude Code modifica i file nel tuo repo mentre tu mantieni il controllo dell'obiettivo, delle regole e di ogni diff. Il modello non conosce il tuo codebase a meno che tu non lo mostri, quindi sii esplicito su file, vincoli e comportamento atteso.
Prima del primo prompt, decidi dove verranno eseguiti i controlli. Se puoi eseguire i test localmente, otterrai feedback in pochi minuti, il che mantiene le iterazioni piccole. Se alcuni controlli girano solo in CI (alcune regole di lint, suite lunghe, step di build), decidi quando farai affidamento sulla CI così non rimani in attesa dopo ogni piccola modifica.
Un semplice pre-flight:
Tieni un piccolo blocco note aperto mentre lavori. Annota vincoli come “niente modifiche all'API”, “comportamento retrocompatibile”, “toccare solo il modulo X”, oltre alle decisioni che prendi. Quando un test fallisce, incolla lì l'errore esatto. Quel foglio diventa il miglior input per il prossimo prompt e impedisce alla sessione di deragliare.
Le piccole diff iniziano con un prompt volutamente stretto. La via più veloce verso codice mergeabile è una modifica che puoi revisionare in un minuto, non un refactor che devi capire per un'ora.
Un buon prompt nomina un obiettivo, un'area del codebase e un risultato atteso. Se non sai indicare dove dovrebbe andare la modifica (file, cartella o modulo), il modello indovinerà e la diff si allargherà.
Una forma di prompt che mantiene le modifiche contenute:
I confini sono l'arma segreta. Invece di “fix the login bug”, specifica cosa deve rimanere invariato: “Non cambiare la shape dell'API”, “Non rinominare funzioni pubbliche”, “Niente modifiche solo di formattazione”, “Evita nuove dipendenze.” Così dici al tuo pair programmer dove non essere creativo.
Quando il cambiamento è ancora poco chiaro, chiedi prima un piano. Un breve piano forza il lavoro in passi e ti dà la possibilità di approvare una prima piccola mossa.
Goal: Fix the null crash when rendering the profile header.
Location: src/components/ProfileHeader.tsx only.
Constraints: Do not change styling, props, or any exported types.
Expected outcome: If user.name is missing, show "Anonymous" and no crash.
Diff constraint: Minimal diff. No refactors. No unrelated formatting.
If unclear: First reply with a 3-step plan, then wait for approval.
Se lavori in un team, aggiungi anche vincoli di review: “Mantienilo sotto ~30 righe cambiate” o “Un solo file a meno che non sia assolutamente necessario.” Questo rende la diff più facile da scansionare e rende i prompt successivi più netti quando qualcosa fallisce.
Mantieni ogni loop concentrato su una singola piccola modifica testabile. Se riesci a descrivere l'obiettivo in una frase e prevedere quali file cambieranno, la dimensione è corretta.
Buone unità di lavoro includono: correggere un bug in un percorso specifico (con repro e guardia), aggiustare un singolo test per un comportamento, fare un refactor che preservi il comportamento (rinomina, estrai funzione, elimina duplicazioni) o migliorare un messaggio di errore o una regola di validazione.
Limita nel tempo ogni loop. Dieci-venti minuti di solito bastano per scrivere un prompt chiaro, applicare la diff ed eseguire un controllo rapido. Se dopo 20 minuti stai ancora esplorando, riduci l'unità o passa solo alla fase di investigazione (appunti, log, test che falliscono) e fermati lì.
Definisci “fatto” prima di iniziare:
Quando lo scope comincia a crescere, fermati presto. Se ti sorprendi a dire “tanto vale”, allora hai appena trovato la prossima iterazione. Catturala come follow-up, committa la diff piccola corrente e vai avanti.
Prima di eseguire test o build, leggi la diff come farebbe un revisore. Qui il workflow resta pulito o deraglia silenziosamente in “perché ha toccato quel file?”.
Inizia chiedendo a Claude Code di riassumere cosa ha cambiato in linguaggio semplice: file toccati, cambiamento di comportamento e cosa non ha cambiato. Se non riesce a spiegare chiaramente la modifica, probabilmente sta facendo troppo.
Poi rileggila tu. Scorri per lo scope, poi leggi per intento. Cerchi drift: formattazione non correlata, refactor extra, simboli rinominati o modifiche non richieste.
Un rapido pre-check:
Se la diff è più grande del previsto, non cercare di testare per uscirne. Torna indietro e re-prompta per un passo più piccolo. Per esempio: “Aggiungi solo un test che riproduce il bug. Niente refactor.” Le piccole diff rendono i fallimenti più semplici da interpretare e rendono il prossimo prompt più preciso.
Le piccole diff pagano solo se le verifichi subito. L'obiettivo è un loop serrato: cambia poco, verifica poco, intercetta errori mentre il contesto è fresco.
Inizia con il controllo più veloce che può dirti “è rotto”. Se hai cambiato formattazione o import, esegui lint o format prima. Se hai toccato la logica business, esegui i test unitari mirati al file o pacchetto. Se hai editato tipi o config di build, esegui una rapida compilazione.
Un ordine pratico:
Quando qualcosa fallisce, registra due cose prima di correggere: il comando esatto eseguito e l'output completo dell'errore (copialo così com'è). Quel registro mantiene il prossimo prompt specifico e previene loop “ancora fallisce”.
Mantieni lo scope stretto. Se lint fallisce e i test falliscono, sistema prima il lint, riesegui, quindi affronta i test. Non mescolare “pulizie rapide” con la correzione di un crash nello stesso passaggio.
Quando i controlli falliscono, tratta l'output di errore come il tuo prossimo prompt. Il loop più veloce è: incolla l'errore, ottieni una diagnosi, applica la correzione minima, riesegui.
Incolla i fallimenti parola per parola, includendo comando e stack trace completi. Chiedi prima la causa più probabile, non un menù di opzioni. Claude Code lavora meglio quando può ancorarsi a numeri di riga e messaggi esatti invece di indovinare.
Aggiungi una frase su ciò che hai già provato così non ti rimanda in loop. Ripeti i vincoli che contano (“Non cambiare API pubbliche”, “Mantieni il comportamento attuale, correggi solo il crash”). Poi chiedi la patch più piccola che faccia passare il controllo.
Un buon prompt di fallimento include:
Se la correzione proposta cambia il comportamento, chiedi un test che provi il nuovo comportamento. Se un handler ora restituisce 400 invece di 500, richiedi un test mirato che fallisca sul codice vecchio e passi con la correzione. Questo mantiene il lavoro onesto e rende la PR più affidabile.
Fermati una volta che i controlli sono verdi e la diff rimane su un'unica idea. Se il modello inizia a migliorare codice non correlato, re-prompta con: “Indirizza solo il test che fallisce. Niente pulizie.”
Una PR si mergea più in fretta se è ovvio cosa è cambiato, perché è cambiato e come provarlo. Con questo workflow, la PR dovrebbe leggere come una piccola storia: passi chiari, ragioni concise.
Allinea i commit con le tue iterazioni. Se hai chiesto un cambio di comportamento, fallo in un commit. Se poi hai risolto un test, fallo nel commit successivo. I revisori seguono il percorso e si fidano che non hai inserito cambiamenti nascosti.
Scrivi messaggi di commit per intento, non per nomi di file. “Fix login redirect when session expires” è meglio di “Update auth middleware.” Quando il messaggio nomina l'outcome visibile all'utente, i revisori impiegano meno tempo a indovinare.
Evita di mescolare refactor con cambiamenti di comportamento nello stesso commit. Se vuoi rinominare variabili o spostare helper, falla separatamente (o rimandala). Il rumore rallenta la review.
Nella descrizione della PR, mantieni tutto breve e concreto:
Esempio: una pagina di fatturazione andava in crash per un record cliente nullo. Commit 1 aggiunge una guardia e uno stato d'errore chiaro. Commit 2 aggiunge un test per il caso null. La descrizione della PR dice: “Apri Billing, carica un cliente senza profilo, conferma che la pagina mostra il nuovo stato vuoto.” Questo è il tipo di PR che i revisori approvano velocemente.
Questa cadenza si rompe quando lo scope si espande silenziosamente. Un prompt che inizia come “fix this failing test” diventa “migliora l'error handling in tutto il modulo” e all'improvviso stai revisionando un diff grande con intento poco chiaro. Mantienilo stretto: un obiettivo, un set di cambiamenti, un set di controlli.
Un altro rallentamento è accettare refactor più belli solo perché sembrano tali. Rinomine, spostamenti di file e cambi di stile creano rumore nella review e rendono più difficile individuare la vera modifica di comportamento.
Trappole comuni:
Un esempio concreto: un test fallisce con “expected 400, got 500.” Se incolli solo la coda dello stack trace, spesso ottieni suggerimenti generici su try/catch. Se incolli l'output completo, potresti vedere il vero problema: una branch di validazione mancante. Questo porta a una diff piccola e mirata.
Prima di committare, leggi la diff come un revisore. Chiediti: ogni riga serve alla richiesta e la so spiegare in una frase? Se no, reverti le modifiche extra e re-prompta con una richiesta più precisa.
Un utente segnala: “La pagina impostazioni a volte si resetta ai valori di default dopo il salvataggio.” Pulli main, esegui i test e vedi un fallimento. Oppure non ci sono test, ma hai un repro chiaro.
Trattalo come un loop: una piccola richiesta, una piccola diff, poi controlli.
Prima, dai a Claude Code il contesto minimo utile: output del test che fallisce (o passi per riprodurre), il percorso del file sospetto e l'obiettivo (“mantieni il comportamento invariato eccetto correggere il reset”). Chiedi una diagnosi e una patch minima, non un refactor.
Poi lavora in loop brevi:
Esegui i controlli dopo aver revisionato la diff.
Se i controlli passano ma temi regressioni, aggiungi copertura.
Concludi con una descrizione PR piccola: qual era il bug, perché è successo e cosa è cambiato. Aggiungi una nota per il revisore tipo “tocca solo il file X” o “aggiunto un test per il caso reset” così la review risulta sicura.
Subito prima di aprire la pull request, fai un ultimo controllo per essere sicuro che il lavoro sia facile da revisionare e sicuro da mergiare.
Un esempio veloce: se hai corretto un bug di login ma hai riformattato 20 file, annulla il commit di formattazione. Il revisore dovrebbe concentrarsi sulla correzione del login, non chiedersi cos'altro è cambiato.
Se qualcosa fallisce, fai un altro piccolo loop: applica una diff piccola, riesegui i controlli e aggiorna le note della PR. Quell'ultimo loop spesso risparmia ore di back-and-forth.
La costanza trasforma una buona sessione in un workflow affidabile. Scegli un loop di default ed eseguilo nello stesso modo ogni volta. Dopo una settimana, vedrai i tuoi prompt accorciarsi e le diff diventare più facili da revisionare.
Una routine semplice:
Un template personale di prompt ti aiuta a restare disciplinato: “Cambia solo il necessario. Tocca al massimo 2 file. Mantieni il comportamento pubblico a meno che io non dica il contrario. Dimmi il comando da eseguire e cosa significa successo.”
Se stai sviluppando dentro Koder.ai, puoi usare lo stesso loop nell'interfaccia chat. La modalità planning è utile per definire il piccolo slice mergeabile (input, output e controlli d'accettazione), mentre snapshot e rollback aiutano a recuperare rapidamente quando un esperimento deraglia.
Una volta che la modifica è stabile, esporta il codice sorgente per eseguire i tuoi tool locali, la CI e la revisione dei colleghi nel tuo repo normale. Effettua il deploy quando ti serve una validazione reale del flusso end-to-end.
Fai di questo loop il tuo default. Prompt piccoli, diff piccoli, controlli frequenti e correzioni rapide si sommano in PR che risultano, nel migliore dei casi, noiose — e questa è una buona cosa.
Default: punta a una singola modifica piccola e facilmente revisionabile che puoi spiegare in una frase.
Una buona regola è: riesci a prevedere quali file cambieranno e puoi verificarlo con un controllo veloce (un test mirato, lint o un rapido avvio). Se non ci riesci, il compito è ancora troppo grande: dividilo in “aggiungi test che riproduce il problema” e “correggi il bug” come loop separati.
Sì — inizia chiedendo un piano breve quando l'obiettivo è vago.
Usa un semplice filtro:
Questo impedisce al modello di indovinare e toccare file extra prima che tu abbia concordato l'approccio.
Includi queste basi nel prompt:
Interrompi e restringi subito lo scope.
Azioni pratiche:
X. Niente refactor. Niente formattazione non correlata.”Cercare di “testare via” una diff troppo ampia di solito costa più tempo che rifarla in piccolo.
Leggi prima la diff, poi esegui i controlli.
Un ordine semplice:
Incolla l'errore letterale e chiedi la correzione minima.
Includi:
Evita “ancora fallisce” senza dettagli — l'output specifico è ciò che permette una patch precisa.
Tratta il modello come un dattilografo velocissimo, non come un pilota automatico.
Tu sei responsabile di:
Una buona abitudine è richiedere un sommario in linguaggio naturale: cosa è cambiato, cosa non è cambiato e perché.
Per default, tienili separati.
Mescolare refactor e cambiamenti di comportamento aggiunge rumore e rende i revisori sospettosi perché l'intento diventa più difficile da verificare.
Mantienilo breve e concreto:
Se la tua PR legge come “una idea, provata da un controllo”, tende a essere approvata più in fretta.
Koder.ai supporta la stessa disciplina con alcune funzionalità utili:
Questa struttura limita naturalmente lo scope e accelera la revisione.
Questo mantiene il loop serrato e rende i fallimenti più facili da interpretare.
Usalo per mantenere le iterazioni piccole e reversibili, poi procedi alla recensione e al merge come di consueto.