Claude Code per l'iterazione UI Flutter: un workflow pratico

Il problema: iterare l'interfaccia velocemente senza trasformarsi in caos

Il lavoro rapido sull'interfaccia Flutter spesso parte bene. Modifichi un layout, aggiungi un pulsante, sposti un campo e lo schermo migliora in fretta. Il problema emerge dopo qualche giro, quando la velocità si tramuta in una pila di cambiamenti che nessuno vuole rivedere.

I team generalmente incontrano gli stessi fallimenti:

• L'albero dei widget cresce senza piano, così una modifica “piccola” costringe a editare molti file.
• Lo stato viene attaccato al codice UI, rendendo i rebuild imprevedibili e i bug più difficili da tracciare.
• La logica di navigazione si disperde (un push qui, una pop là) finché i flussi non corrispondono più a come gli utenti si muovono nell'app.
• I nomi si degradano, i componenti si duplicano e nessuno è sicuro di quale widget sia il “reale”.
• I diff diventano enormi, così i reviewer scorrono in fretta, i problemi passano e le regressioni emergono dopo.

Una grande causa è l'approccio della “one big prompt”: descrivi l'intera feature, chiedi l'insieme completo di schermate e accetti un output vasto. L'assistente cerca di aiutare, ma tocca troppe parti del codice in una volta. Questo rende i cambiamenti disordinati, difficili da rivedere e rischiosi da mergiare.

Un loop ripetibile risolve questo forzando chiarezza e limitando il raggio d'azione. Invece di “costruire la feature”, procedi ripetutamente così: prendi una user story, genera la fetta di UI più piccola che la dimostri, aggiungi solo lo stato necessario per quella fetta, poi collega la navigazione per un solo percorso. Ogni passaggio resta sufficientemente piccolo da poter essere rivisto e gli errori sono facili da annullare.

L'obiettivo qui è un workflow pratico per trasformare le user story in schermate concrete, gestione dello stato e flussi di navigazione senza perdere il controllo. Fatto bene, ottieni pezzi di UI modulari, diff più piccoli e meno sorprese quando i requisiti cambiano.

Trasforma le user story in una specifica UI chiara che puoi costruire

Le user story sono scritte per esseri umani, non per alberi di widget. Prima di generare nulla, converti la story in una piccola specifica UI che descriva il comportamento visibile. “Done” dovrebbe essere testabile: ciò che l'utente può vedere, tappare e confermare, non se il design “sembra moderno”.

Un modo semplice per mantenere lo scope concreto è dividere la story in quattro bucket:

• Schermate: cosa cambia, cosa resta invariato.
• Componenti: quali nuovi pezzi UI appaiono e dove risiedono.
• Stati: loading, success, error, empty e cosa mostra ciascuno.
• Eventi: tap, swipe, pull-to-refresh, back, retry.

Se la story sembra ancora vaga, rispondi a queste domande in linguaggio semplice:

• Quali schermate cambiano e quali restano uguali?
• Quali nuovi componenti appaiono e dove appartengono?
• Quali stati esistono e cosa mostra ciascuno?
• Quali eventi guidano i cambi di stato?
• Qual è il controllo di accettazione che puoi fare in 30 secondi dopo aver avviato l'app?

Aggiungi vincoli presto perché guidano ogni scelta di layout: basi del tema (colori, spaziatura, tipografia), reattività (prima telefono in portrait, poi larghezze tablet) e minimi di accessibilità come dimensione dei target di tap, scala del testo leggibile e etichette significative per le icone.

Infine, decidi cosa è stabile rispetto a cosa è flessibile così non fai churn nel codebase. Gli elementi stabili sono quelli da cui dipendono altre feature, come nomi di route, modelli di dati e API esistenti. Gli elementi flessibili sono più sicuri da iterare, come la struttura del layout, la microcopy e la composizione esatta dei widget.

Esempio: “Come utente, posso salvare un elemento tra i Preferiti dalla schermata di dettaglio.” Una specifica UI buildable potrebbe essere:

• La schermata di dettaglio mostra un'icona di segnalibro.
• Il tap alterna lo stato salvato.
• Durante il salvataggio, mostra un piccolo indicatore di progresso.
• In caso di fallimento, mostra un errore inline con azione Retry.
• La navigazione rimane la stessa (nessuna nuova rotta).

Questo è sufficiente per costruire, rivedere e iterare senza indovinare.

Imposta il loop di iterazione così i diff restino piccoli

I diff piccoli non significano lavorare più lentamente. Rendono ogni cambiamento UI facile da rivedere, da annullare e difficile da rompere. La regola più semplice: una schermata o una interazione per iterazione.

Scegli una fetta stretta prima di iniziare. “Aggiungi uno stato vuoto alla schermata Ordini” è una buona fetta. “Rifare tutto il flusso Ordini” non lo è. Punta a un diff che un collega possa capire in un minuto.

Una struttura di cartelle stabile aiuta a mantenere i cambi contenuti. Un layout semplice, feature-first, impedisce di disperdere widget e rotte nell'app:

lib/
  features/
    orders/
      screens/
      widgets/
      state/
      routes.dart

Mantieni i widget piccoli e composti. Quando un widget ha input e output chiari, puoi cambiare layout senza toccare la logica di stato, e cambiare stato senza riscrivere la UI. Prediligi widget che prendono valori semplici e callback, non stato globale.

Un loop che resta revisionabile:

• Scrivi una specifica UI di 3–6 righe per la fetta (cosa appare, cosa fanno i tap, come sono loading/error).
• Genera o modifica solo i file minimi necessari (spesso una schermata e uno o due widget).
• Esegui la schermata, poi fai un pass di pulizia (naming, spazi, rimozione di prop non usate).
• Commit con un messaggio che corrisponde alla fetta.

Imposta una regola ferma: ogni cambiamento deve essere facile da revertare o isolare. Evita refactor di passaggio mentre itera su una schermata. Se noti problemi non correlati, annotali e risolvili in un commit separato.

Se il tuo strumento supporta snapshot e rollback, usa ogni fetta come punto snapshot. Alcune piattaforme di vibe-coding come Koder.ai includono snapshot e rollback, che possono rendere l'esperimento più sicuro quando provi cambi UI audaci.

Un'altra abitudine che mantiene calme le prime iterazioni: preferisci aggiungere nuovi widget piuttosto che modificare quelli condivisi. I componenti condivisi sono dove i piccoli cambi diventano grandi diff.

Passo dopo passo: genera un albero di widget da una user story

Il lavoro UI veloce resta sicuro quando separi il pensiero dalla digitazione. Inizia ottenendo un piano chiaro dell'albero dei widget prima di generare codice.

1. Chiedi solo un outline dell'albero dei widget. Vuoi i nomi dei widget, la gerarchia e cosa mostra ciascuna parte. Niente codice ancora. Qui intercetti stati mancanti, schermate vuote e scelte di layout strane mentre tutto è ancora economico da cambiare.

2. Chiedi una ripartizione dei componenti con responsabilità. Mantieni ogni widget focalizzato: un widget renderizza l'header, un altro la lista, un altro gestisce empty/error UI. Se qualcosa avrà bisogno di stato dopo, annotalo ora ma non implementarlo ancora.

3. Genera lo scaffold della schermata e i widget stateless. Parti con un singolo file di schermata con contenuto placeholder e TODO chiari. Mantieni gli input espliciti (parametri del costruttore) così puoi collegare lo stato reale dopo senza riscrivere l'albero.

4. Fai un pass separato per styling e dettagli di layout: spaziatura, tipografia, theming e comportamento responsive. Tratta lo styling come un diff a parte così le review restano semplici.

Un pattern di prompt che funziona

Metti i vincoli in testa così l'assistente non inventa UI che non puoi spedire:

• Dispositivi target (solo telefono, anche tablet, orientamento)
• Vincoli di design (Material 3, colori del tema esistente, regole di spaziatura)
• Aspettative di navigazione (comportamento back, deep link se presenti)
• Criteri di accettazione (cosa deve essere visibile e tappabile)
• Confini del codice esistente (quali file/widget devono restare, convenzioni di naming)

Esempio concreto: la user story è “Come utente, posso rivedere i miei elementi salvati e rimuoverne uno.” Chiedi un albero di widget che includa una app bar, una lista con righe elemento e uno stato vuoto. Poi richiedi una ripartizione come SavedItemsScreen, SavedItemTile, EmptySavedItems. Solo dopo, genera lo scaffold con widget stateless e dati finti, e infine aggiungi lo styling (divider, padding e un pulsante rimuovi chiaro) in un pass separato.

Aggiungi la gestione dello stato senza ingolfare il codice UI

L'iterazione UI si sfalda quando ogni widget comincia a prendere decisioni. Mantieni l'albero dei widget “stupido”: deve leggere lo stato e renderizzare, non contenere regole di business.

Inizia nominando gli stati in parole semplici. La maggior parte delle feature necessita di più di «loading» e «done»:

• Loading (primo caricamento o refresh)
• Empty (nessun dato)
• Error (richiesta fallita, permesso negato)
• Success (dati pronti)
• Partial input (form iniziato, ma non valido)

Poi elenca gli eventi che possono cambiare lo stato: tap, submit del form, pull-to-refresh, back, retry e “utente ha modificato un campo”. Farlo in anticipo evita congetture più tardi.

Mantieni lo stato separato dai widget

Scegli un approccio di stato per la feature e mantienilo. L'obiettivo non è “il pattern migliore”, ma diff coerenti.

Per una schermata piccola, un semplice controller (come ChangeNotifier o ValueNotifier) è spesso sufficiente. Metti la logica in un unico posto:

• Input: eventi dalla UI (submit, refresh, edit)
• Output: un singolo oggetto stato che la UI può renderizzare
• Effetti collaterali: chiamate API e richieste di navigazione

Prima di aggiungere codice, scrivi le transizioni di stato in inglese semplice. Esempio per una schermata di login:

"Quando l'utente preme Sign in: imposta Loading. Se l'email è invalida: resta in Partial input e mostra un messaggio inline. Se la password è sbagliata: imposta Error con messaggio e abilita Retry. Se successo: imposta Success e naviga a Home."

Poi genera il codice Dart minimale che corrisponde a quelle frasi. Le review restano semplici perché puoi confrontare il diff con le regole.

Aggiungi regole testabili per input invalidi

Rendi la validazione esplicita. Decidi cosa succede quando gli input sono invalidi:

• Blocchi il submit o lo permetti e mostri errori?
• Quali campi mostrano errori e quando?
• Il back scarta l'input parziale o lo mantiene?

Quando queste risposte sono scritte, la UI resta pulita e il codice di stato rimane piccolo.

Progetta i flussi di navigazione che rispecchiano il comportamento reale degli utenti

Una buona navigazione inizia come una mappa piccola, non come un cumulo di rotte. Per ogni user story, scrivi quattro momenti: dove entra l'utente, il passo successivo più probabile, come annulla e cosa significa “back” (ritorno alla schermata precedente o a uno stato home sicuro).

Inizia con una mappa delle rotte, poi blocca cosa viaggia tra le schermate

Una semplice mappa delle rotte dovrebbe rispondere alle domande che solitamente causano rifacimenti:

• Entry: quale schermata si apre per prima e da dove (tab, notifica, deep link)
• Next: il percorso in avanti principale dopo l'azione primaria
• Cancel: dove atterra l'utente se abbandona il flusso
• Back: se il back è permesso e cosa preserva
• Fallback: dove andare se mancano dati richiesti

Poi definisci i parametri passati tra le schermate. Sii esplicito: ID (productId, orderId), filtri (intervallo date, stato) e dati bozza (un form parzialmente compilato). Se salti questo, finirai per infilare stato in singleton globali o ricostruire schermate per “trovare” il contesto.

Pianifica deep link e pattern di “ritorna un risultato”

I deep link contano anche se non li spedisci il primo giorno. Decidi cosa succede quando un utente atterra a metà flusso: puoi caricare i dati mancanti o dovresti reindirizzare a una schermata di ingresso sicura?

Decidi anche quali schermate devono ritornare risultati. Esempio: una schermata "Select Address" restituisce un addressId e la schermata checkout si aggiorna senza un refresh completo. Mantieni la forma del risultato piccola e tipata così i cambi restano facili da rivedere.

Prima di codare, indica i casi limite: modifiche non salvate (mostra dialog di conferma), auth richiesta (pausa e riprendi dopo il login) e dati mancanti o cancellati (mostra errore e una via d'uscita chiara).

Rendi le modifiche UI revisionabili e modulari

Quando iteri velocemente, il vero rischio non è "UI sbagliata." È UI non revisionabile. Se un collega non capisce cosa è cambiato, perché è cambiato e cosa è rimasto stabile, ogni iterazione successiva rallenta.

Una regola che aiuta: blocca prima le interfacce, poi lascia muovere gli internals. Stabilizza le props pubbliche dei widget (input), i piccoli modelli UI e gli argomenti di rotta. Una volta nominati e tipati, puoi rimodellare l'albero dei widget senza rompere il resto dell'app.

Preferisci cuciture piccole e stabili

Chiedi un piano diff-friendly prima di generare codice. Vuoi un piano che dica quali file cambieranno e quali devono restare intatti. Questo mantiene le review focalizzate e previene refactor accidentali che cambiano il comportamento.

Pattern che mantengono i diff piccoli:

• Mantieni i widget pubblici sottili: accettano solo i dati e i callback di cui hanno bisogno, evitando di tuffarsi nei singleton.
• Sposta le regole di business fuori dai widget presto: metti le decisioni in un controller o view model e lascia che la UI renderizzi lo stato.
• Quando un pezzo UI smette di cambiare ogni ora, estrailo in un widget riutilizzabile con API chiara e tipata.
• Mantieni gli argomenti di rotta espliciti (un singolo oggetto arg è spesso più pulito di molti campi opzionali).
• Aggiungi un breve changelog nella descrizione della PR: cosa è cambiato, perché e cosa testare.

Un esempio concreto che i reviewer apprezzano

Se la user story è “Come acquirente, posso modificare il mio indirizzo di spedizione dal checkout.” Blocca prima gli argomenti di rotta: CheckoutArgs(cartId, shippingAddressId) resta stabile. Poi itera dentro la schermata. Quando il layout si stabilizza, dividilo in AddressForm, AddressSummary e SaveBar.

Se la gestione dello stato cambia (per esempio la validazione si sposta dal widget in un CheckoutController), la review resta leggibile: i file UI cambiano principalmente nel rendering, mentre il controller mostra la logica cambiata in un unico posto.

Errori comuni e trappole quando si itera con un assistente AI

Il modo più rapido per rallentare è chiedere all'assistente di cambiare tutto in una volta. Se un commit tocca layout, stato e navigazione, i reviewer non sapranno cosa ha rotto e il rollback diventa complicato.

Un'abitudine più sicura è un intento per iterazione: definisci l'albero widget, poi collega lo stato, poi la navigazione.

Errori che creano codice disordinato

Un problema comune è lasciare che il codice generato inventi un pattern nuovo per ogni schermata. Se una pagina usa Provider, la successiva usa setState e la terza introduce una classe controller custom, l'app diventa incoerente rapidamente. Scegli un piccolo set di pattern e applicali.

Un altro errore è mettere lavoro async direttamente dentro build(). Può sembrare OK in una demo veloce, ma scatena chiamate ripetute ai rebuild, flicker e bug difficili da tracciare. Sposta la chiamata in initState(), in un view model o in un controller dedicato e tieni build() concentrato sul rendering.

Il naming è una trappola silenziosa. Codice che compila ma si legge come Widget1, data2 o temp rende i refactor futuri dolorosi. Nomi chiari aiutano anche l'assistente a produrre cambi successivi migliori perché l'intento è ovvio.

Guardrail che prevengono i peggiori esiti:

• Cambia solo uno di: layout, stato o navigazione per iterazione
• Riusa lo stesso pattern di stato nella feature
• Niente chiamate di rete o DB dentro build()
• Rinomina i placeholder prima di aggiungere più funzionalità
• Preferisci estrarre widget piuttosto che aumentare l'annidamento

La trappola dell'annidamento

Una classica correzione visiva è aggiungere un altro Container, Padding, Align e SizedBox finché non sembra giusto. Dopo qualche passaggio, l'albero diventa illeggibile.

Se un pulsante è disallineato, prova prima a rimuovere wrapper, usare un singolo widget layout genitore o estrarre un piccolo widget con i propri vincoli.

Esempio: una schermata checkout dove il prezzo totale salta durante il loading. Un assistente potrebbe avvolgere la riga del prezzo in più widget per “stabilizzarla”. Una correzione più pulita è riservare spazio con un placeholder di loading mantenendo la struttura della riga invariata.

Checklist rapida prima di fare commit della prossima iterazione UI

Prima di fare commit, fai un pass di due minuti che verifica il valore per l'utente e ti protegge da regressioni inattese. L'obiettivo non è la perfezione. È fare in modo che questa iterazione sia facile da rivedere, testare e annullare.

Checklist per il commit

Leggi la user story una volta, poi verifica questi elementi contro l'app in esecuzione (o almeno contro un semplice widget test):

• L'albero dei widget corrisponde alla story: gli elementi chiave dei criteri di accettazione esistono ed sono visibili. Testo, pulsanti e spaziatura appaiono intenzionali.
• Tutti gli stati sono raggiungibili: loading, error e empty non sono solo abbozzati nel codice. Puoi attivare ciascuno (anche con un flag debug temporaneo) e appare accettabile.
• La navigazione e il comportamento del back hanno senso: back ritorna alla schermata prevista, i dialog si chiudono correttamente e i deep link (se usati) atterrano in un posto sensato.
• I diff restano piccoli e owned: i cambi sono limitati a un piccolo set di file con responsabilità chiare. Niente refactor di passaggio.
• Il rollback è pulito: se reverti questo commit, le altre schermate compilano e girano ancora. Rimuovi flag temporanei o asset placeholder che potrebbero rompersi dopo.

Un check di realtà rapido: se hai aggiunto una nuova schermata Dettagli Ordine, dovresti poter (1) aprirla dalla lista, (2) vedere uno spinner di loading, (3) simulare un errore, (4) vedere un ordine vuoto e (5) premere back per tornare alla lista senza salti strani.

Se il tuo workflow supporta snapshot e rollback, scatta uno snapshot prima di cambi UI più grandi. Alcune piattaforme come Koder.ai lo supportano e possono aiutarti a iterare più veloce senza mettere a rischio il ramo principale.

Un esempio realistico: da user story a schermate in tre iterazioni

User story: "Come acquirente, posso sfogliare articoli, aprire una pagina dettagli, salvare un articolo tra i preferiti e poi vedere i miei preferiti." L'obiettivo è passare dalle parole alle schermate in tre piccoli passi revisionabili.

Iterazione 1: concentrati solo sulla schermata di browse. Crea un albero widget abbastanza completo da renderizzare ma non collegato a dati reali: uno Scaffold con una AppBar, una ListView di righe placeholder e UI chiare per loading e empty. Mantieni lo stato semplice: loading (mostra CircularProgressIndicator), empty (mostra un breve messaggio e magari un pulsante Try again) e ready (mostra la lista).

Iterazione 2: aggiungi la schermata dettagli e la navigazione. Mantieni esplicito: onTap fa push di una rotta e passa un piccolo oggetto param (ad esempio: item id, title). Inizia la pagina dettaglio in sola lettura con un titolo, una descrizione placeholder e un pulsante Favorite. L'obiettivo è soddisfare la story: lista -> dettaglio -> back, senza flussi extra.

Iterazione 3: introduci aggiornamenti dello stato dei preferiti e feedback UI. Aggiungi una singola fonte di verità per i preferiti (anche in memoria è ok) e collegala a entrambe le schermate. Il tap su Favorite aggiorna immediatamente l'icona e mostra una piccola conferma (es. SnackBar). Poi aggiungi una schermata Favorites che legge lo stesso stato e gestisce lo stato vuoto.

Un diff revisionabile tipicamente assomiglia a:

• browse_list_screen.dart: albero widget più UI loading/empty/ready
• item_details_screen.dart: layout UI e accetta param di navigazione
• favorites_store.dart: contenitore stato minimale e metodi di update
• app_routes.dart: rotte e helper di navigazione tipati
• favorites_screen.dart: legge lo stato e mostra UI empty/list

Se un file diventa “il posto dove succede tutto”, dividilo prima di procedere. File piccoli con nomi chiari mantengono l'iterazione successiva veloce e sicura.

Prossimi passi: rendi il loop ripetibile tra le feature

Se il workflow funziona solo quando sei “in the zone”, si romperà nel momento in cui cambi schermata o un collega tocca la feature. Rendi il loop un'abitudine scrivendolo e mettendo guardrail intorno alla dimensione dei cambi.

Crea un template di prompt riutilizzabile

Usa un template di team in modo che ogni iterazione parta con gli stessi input e produca lo stesso tipo di output. Mantienilo breve ma specifico:

• User story + criteri di accettazione (cosa significa “done”)
• Vincoli UI (design system, spaziatura, componenti da riusare)
• Regole di stato (dove vive lo stato, cosa è locale vs condiviso)
• Regole di navigazione (rotte, deep link, comportamento back)
• Regole di output (file da toccare, test da aggiornare, cosa spiegare nel diff)

Questo riduce la probabilità che l'assistente inventi pattern nuovi a metà feature.

Definisci “piccolo” così i diff restano prevedibili

Scegli una definizione di piccolo facile da far rispettare in code review. Per esempio, limita ogni iterazione a un numero ridotto di file e separa i refactor UI dai cambi di comportamento.

Un set semplice di regole:

• Non più di 3–5 file cambiati per iterazione
• Una nuova widget o un passo di navigazione per iterazione
• Nessun nuovo approccio di state management introdotto a metà loop
• Ogni cambiamento deve compilare ed eseguire prima della prossima iterazione

Aggiungi checkpoint così puoi annullare rapidamente un passo sbagliato. Al minimo, tagga commit o tieni checkpoint locali prima di refactor importanti. Se il workflow supporta snapshot e rollback, usali aggressivamente.

Se vuoi un workflow basato su chat che possa generare e rifinire app Flutter end-to-end, Koder.ai include una modalità di pianificazione che aiuta a rivedere un piano e i file previsti prima di applicarli.