14 dic 2025·6 min
Claude Code task scoping: da richieste vaghe a commit
Impara il task scoping con Claude Code: trasforma richieste vaghe in criteri di accettazione chiari, un piano UI/API minimale e qualche piccolo commit.
Impara il task scoping con Claude Code: trasforma richieste vaghe in criteri di accettazione chiari, un piano UI/API minimale e qualche piccolo commit.
Una richiesta vaga suona innocua: “Aggiungi una ricerca migliore”, “Rendi l’onboarding più fluido”, “Gli utenti hanno bisogno di notifiche.” Nelle squadre reali arriva spesso come un messaggio in chat di una riga, uno screenshot con frecce o una chiamata cliente ricordata a metà. Tutti sono d’accordo, ma ognuno si immagina qualcosa di diverso.
Il costo si vede dopo. Quando lo scope non è chiaro, si lavora sulle ipotesi. La prima demo diventa un’altra tornata di chiarimenti: “Non è quello che intendevo.” Il lavoro viene rifatto e la modifica cresce silenziosamente. Ritocchi di design innescano cambi al codice, che richiedono altri test. Le revisioni rallentano perché una modifica sfocata è difficile da verificare. Se nessuno può definire come appare il “corretto”, i revisori finiscono a discutere il comportamento invece di controllare la qualità.
Si riconosce una task vaga presto:
Un task ben definito dà al team una linea di arrivo: criteri di accettazione chiari, un piano minimo UI e API e confini espliciti su cosa NON è incluso. Questa è la differenza tra “migliorare la ricerca” e una piccola modifica facile da costruire e rivedere.
Un’abitudine pratica: separa la “definizione di fatto” dai “nice-to-have”. “Fatto” è una lista breve di controlli che puoi eseguire (per esempio: “La ricerca restituisce risultati per titolo, mostra ‘Nessun risultato’ quando è vuota e mantiene la query nell’URL”). I “nice-to-have” sono tutto il resto che può aspettare (sinonimi, aggiustamenti di ranking, evidenziazione, analytics). Etichettare queste cose in anticipo evita l’espansione accidentale dello scope.
Le richieste vaghe spesso partono da soluzioni proposte: “Aggiungi un pulsante”, “Cambia il flusso”, “Usa un modello diverso.” Fai una pausa e traduci la proposta in outcome.
Un formato semplice aiuta: “Come [utente], voglio [fare qualcosa], così posso [raggiungere un obiettivo].” Mantienilo chiaro. Se non riesci a dirlo in una sola frase, è ancora troppo vago.
Poi descrivi cosa cambia per l’utente quando è fatto. Concentrati sul comportamento visibile, non sui dettagli di implementazione. Per esempio: “Dopo l’invio del form vedo una conferma e posso trovare il nuovo record nella lista.” Questo crea una linea di arrivo chiara e rende più difficile che si infiltri “solo un’altra modifica”.
Annota anche cosa resta uguale. I non-goals proteggono lo scope. Se la richiesta è “migliorare l’onboarding”, un non-goal può essere “nessun redesign della dashboard” o “nessuna modifica alla logica dei piani tariffari”.
Infine, scegli un percorso primario da supportare per primo: la singola fetta end-to-end che dimostra che la feature funziona.
Esempio: invece di “aggiungi snapshot ovunque”, scrivi: “Come proprietario del progetto, posso ripristinare l’ultimo snapshot della mia app, così posso annullare una modifica errata.” Non-goals: “no restore di massa, no redesign UI.”
Una richiesta vaga raramente manca di sforzo. Manca decisioni.
Inizia con i vincoli che cambiano discretamente lo scope. Le scadenze contano, ma anche le regole di accesso e i requisiti di compliance. Se stai costruendo su una piattaforma con tier e ruoli, decidi presto chi ottiene la feature e in quale piano.
Poi chiedi un esempio concreto. Uno screenshot, il comportamento di un concorrente o un ticket precedente rivelano cosa significa “meglio”. Se il richiedente non ha nulla, chiedigli di ripercorrere l’ultima volta che ha provato dolore: su quale schermo era, cosa ha cliccato e cosa si aspettava?
I casi limite sono dove lo scope esplode, quindi nomina subito i principali: dati vuoti, errori di validazione, chiamate lente o fallite e cosa significa davvero “undo”.
Infine, decidi come verificherai il successo. Senza un risultato testabile, il task diventa opinioni.
Queste cinque domande solitamente rimuovono la maggior parte dell’ambiguità:
Esempio: “Aggiungi domini personalizzati per i clienti” diventa più chiaro una volta deciso a quale tier appartiene, chi può configurarli, se la sede di hosting importa per la compliance, quale errore mostrare per DNS non valido e cosa significa “done” (dominio verificato, HTTPS attivo e piano di rollback sicuro).
Le richieste confuse mescolano obiettivi, ipotesi e casi limite ricordati a metà. Il lavoro è trasformarle in affermazioni che chiunque può testare senza leggere nella tua mente. Gli stessi criteri dovrebbero guidare design, sviluppo, review e QA.
Un pattern semplice mantiene chiarezza. Puoi usare Given/When/Then o bullet brevi che hanno lo stesso significato.
Scrivi ogni criterio come un singolo test che qualcuno può eseguire:
Applichiamolo. Supponiamo che la nota dica: “Rendi gli snapshot più semplici. Voglio poter ripristinare se l’ultima modifica rompe le cose.” Trasformalo in affermazioni testabili:
Se QA può eseguire questi controlli e i revisori possono verificarli in UI e log, sei pronto per pianificare UI e API e dividerli in piccoli commit.
Un piano UI minimale è una promessa: la più piccola modifica visibile che dimostra che la feature funziona.
Inizia nominando quali schermate cambieranno e cosa una persona noterà in 10 secondi. Se la richiesta dice “rendilo più facile” o “sistemalo”, traduco questo in una modifica concreta che puoi indicare.
Scrivilo come una piccola mappa, non come un redesign. Per esempio: “Pagina Orders: aggiungi una barra di filtri sopra la tabella” o “Impostazioni: aggiungi un toggle sotto Notifiche.” Se non riesci a nominare la schermata e l’elemento esatto che cambia, lo scope è ancora incerto.
La maggior parte dei cambi UI richiede pochi stati prevedibili. Specifica solo quelli che si applicano:
La copy UI fa parte dello scope. Cattura etichette e messaggi che devono essere approvati: testo dei pulsanti, etichette dei campi, testo di aiuto e messaggi di errore. Se la formulazione è ancora aperta, segnala che è placeholder e chi la confermerà.
Mantieni una piccola nota “non ora” per tutto ciò che non è necessario per usare la feature (polish responsive, sorting avanzati, animazioni, nuove icone).
Un task definito ha bisogno di un piccolo contratto chiaro tra UI, backend e dati. Lo scopo non è progettare l’intero sistema, ma definire il set minimo di richieste e campi che dimostrano che la feature funziona.
Inizia elencando i dati di cui hai bisogno e da dove vengono: campi esistenti che puoi leggere, nuovi campi da salvare e valori che puoi calcolare. Se non riesci a indicare la fonte di ogni campo, non hai ancora un piano.
Mantieni l’API ridotta. Per molte feature, una lettura e una scrittura bastano:
GET /items/{id} restituisce lo stato necessario per rendere la schermataPOST /items/{id}/update accetta solo ciò che l’utente può cambiare e ritorna lo stato aggiornatoScrivi input e output come oggetti chiari, non come paragrafi. Includi campi obbligatori vs opzionali e cosa succede sugli errori comuni (not found, validation failed).
Fai una rapida verifica di auth prima di toccare il DB. Decidi chi può leggere e chi può scrivere e descrivi la regola in una frase (per esempio: “qualsiasi utente loggato può leggere, solo gli admin possono scrivere”). Saltare questo spesso porta a rework.
Infine, decidi cosa va memorizzato e cosa può essere calcolato. Una regola semplice: salva i fatti, calcola le viste.
Claude Code funziona meglio quando gli dai un obiettivo chiaro e un confine stretto. Inizia incollando la richiesta confusa e qualsiasi vincolo (scadenza, utenti coinvolti, regole sui dati). Poi chiedi un output definito che includa:
Dopo la risposta, leggila come un revisore. Se vedi frasi come “migliorare le performance” o “pulire”, chiedi una formulazione misurabile.
Richiesta: “Aggiungi un modo per mettere in pausa un abbonamento.”
Una versione definita potrebbe dire: “L’utente può mettere in pausa da 1 a 3 mesi; la prossima data di fatturazione si aggiorna; l’admin può vedere lo stato di pausa,” e out-of-scope: “Nessuna modifica alla proratizzazione.”
Da lì, il piano di commit diventa pratico: un commit per DB e shape API, uno per i controlli UI, uno per validazione e stati di errore, uno per test end-to-end.
Le grandi modifiche nascondono bug. I commit piccoli rendono le revisioni più veloci, i rollback più sicuri e ti aiutano a notare quando ti allontani dai criteri di accettazione.
Una regola utile: ogni commit dovrebbe sbloccare un nuovo comportamento e includere un modo rapido per dimostrarlo.
Una sequenza comune assomiglia a questa:
Mantieni ogni commit focalizzato. Evita refactor “tanto approfitto” durante la modifica. Mantieni l’app funzionante end-to-end, anche se l’UI è basilare. Non unire migration, comportamento e UI in un solo commit a meno che non ci sia una forte ragione.
Uno stakeholder dice: “Possiamo aggiungere Esporta report?” Nasconde molte scelte: quale report, quale formato, chi può esportare e come avviene la consegna.
Chiedi solo le domande che cambiano il design:
Immagina le risposte: “Sales Summary, solo CSV, ruolo manager, download diretto, massimo ultimi 90 giorni.” Ora i criteri di accettazione per la v1 diventano concreti: i manager possono cliccare Export sulla pagina Sales Summary; il CSV corrisponde alle colonne della tabella a schermo; l’export rispetta i filtri correnti; l’export su più di 90 giorni mostra un errore chiaro; il download si completa entro 30 secondi per fino a 50k righe.
Piano UI minimale: un pulsante Export vicino alle azioni della tabella, stato di caricamento durante la generazione e un messaggio di errore che spiega come risolvere (es. “Scegli 90 giorni o meno”).
Piano API minimale: un endpoint che prende filtri e ritorna un CSV generato come file response, riusando la stessa query della tabella e applicando server-side la regola dei 90 giorni.
Poi spediscilo in pochi commit stretti: prima l’endpoint per il percorso felice fisso, poi wiring UI, poi validazione e messaggi per l’utente, poi test e documentazione.
Richieste come “aggiungi ruoli di team” spesso nascondono regole su inviti, modifica e cosa succede agli utenti esistenti. Se ti sorprendi a indovinare, scrivi l’assunzione e trasformala in domanda o regola esplicita.
I team perdono giorni quando un task include sia “farlo funzionare” sia “renderlo bello”. Mantieni il primo task focalizzato su comportamento e dati. Metti styling, animazioni e spaziatura in un task successivo a meno che non siano necessari per usare la feature.
I casi limite contano, ma non tutti vanno risolti subito. Gestisci quelli che possono rompere la fiducia (double submit, conflitti di editing) e rimanda il resto con note chiare.
Se non li scrivi, li dimentichi. Includi almeno un percorso negativo e almeno una regola di permesso nei criteri di accettazione.
Evita “veloce” o “intuitivo” a meno che non ci sia un numero o un controllo concreto. Sostituiscili con qualcosa che si può provare in review.
Blocca il task così un collega può revisionare e testare senza leggere nella tua mente:
Esempio: “Aggiungi saved searches” diventa “Gli utenti possono salvare un filtro e riapplicarlo”, con non-goals come “nessuna condivisione” e “nessuna modifica al sorting”.
Una volta che hai un task definito, proteggilo. Prima di codare, fai una rapida review di sanity con chi ha chiesto la modifica:
Poi conserva i criteri dove il lavoro avviene: nel ticket, nella descrizione della PR e ovunque il team guarda veramente.
Se stai costruendo in Koder.ai (koder.ai), aiuta bloccare prima il piano e poi generare codice da esso. La Planning Mode è adatta a quel flusso, e snapshot e rollback possono tenere le esperienze al sicuro quando provi un approccio e devi tornare indietro.
Quando emergono nuove idee durante lo sviluppo, mantieni stabile lo scope: annotale in una lista di follow-up, metti in pausa per ri-scopare se cambiano i criteri di accettazione e mantieni i commit legati a un solo criterio alla volta.
Inizia scrivendo l’outcome in una sola frase (cosa potrà fare l’utente quando è finito), poi aggiungi 3–7 criteri di accettazione che un tester può verificare.
Se non riesci a descrivere il comportamento “corretto” senza discutere, il task è ancora vago.
Usa questo formato rapido:
Poi aggiungi un esempio concreto del comportamento atteso. Se non puoi fornire un esempio, ripercorri l’ultima volta che il problema si è manifestato e scrivi cosa l’utente ha cliccato e cosa si aspettava di vedere.
Scrivi prima una breve Definizione di fatto (i controlli che devono passare), poi una lista separata Nice-to-have.
Regola di default: se non è necessario per dimostrare che la funzionalità funziona end-to-end, va nei nice-to-have.
Fai le poche domande che cambiano scope:
Queste costringono le decisioni mancanti a venire fuori.
Tratta i casi limite come elementi di scope, non come sorprese. Per la v1, copri quelli che compromettono la fiducia:
Tutto il resto può essere rimandato con note esplicite di out-of-scope.
Usa affermazioni testabili che chiunque può eseguire senza indovinare:
Includi almeno un caso di errore e una regola di permessi. Se un criterio non è testabile, riscrivilo finché non lo diventa.
Nomina gli schermi esatti e la singola modifica visibile per ogni schermo.
Elenca anche gli stati UI richiesti:
Includi le diciture (testo dei pulsanti, errori) anche se come placeholder.
Mantieni il contratto piccolo: di solito una lettura e una scrittura bastano per la v1.
Definisci:
Memorizza fatti; calcola viste quando possibile.
Chiedi un deliverable con vincoli:
Poi chiedi di rendere misurabile ogni vaghezza tipo “migliora performance”.
Sequenza predefinita:
Regola pratica: un commit = un comportamento utente visibile + un modo rapido per dimostrarlo. Evita di infilare refactor “tanto per” nei commit della funzionalità.