La specifica è il codice 📐
TL;DR: Il greenfield non parte dal codice ma dalla specifica. La specifica è la fonte di verità che sopravvive al codice, alle mutate esigenze, al turnover del team. Un agente che parte da una specifica chiara produce codice coerente; un agente che parte da un’idea vaga produce codice vago.
Il paradosso del greenfield 🌱
Tutti vogliono fare il progetto nuovo. È la tentative più grande dello sviluppatore: zero debito tecnico, zero compromessi, zero “perché è fatto così?”. Ecco perché il greenfield è il caso d’uso dove gli agenti di coding vengono usati peggio.
Il scenario classico: apri il terminale, chiedi all’agente di “creare un’API REST per gestione ordini”, e aspetti. L’agente produce 500 righe di codice funzionante. Funzionante nel senso che compila, che i test passano, che il server parte. Ma dentro c’è un disarchitetturale latente: dipendenze circolari, pattern incoerenti, una struttura che nessuno vuole mantenere.
Il problema non è il codice che l’agente scrive. È il codice che l’agente non sa di dover scrivere perché nessuno gli ha detto cosa vuoi davvero.
La specifica come contratto 📜
La specifica non è un documento preliminare da scrivere e dimenticare. È il contratto vivente del progetto. Definisce cosa il sistema deve fare (non come), chi lo usa, quali scenari deve supportare, e quali sono i criteri che determinano il successo.
Quando la specifica è chiara, l’agente ha un bersaglio preciso. Quando è vaga, l’agente tira a indovinare. E gli agenti sono molto bravi a indovinare — il problema è che indovinano in modo plausibile, non in modo corretto.
La differenza tra “crea un’API per ordini” e “crea un’API REST con endpoint GET/POST/PUT per gestione ordini, autenticazione JWT, rate limiting a 100 req/min, persistenza PostgreSQL, e test di integrazione per tutti gli endpoint” non è la lunghezza del prompt. È la quantità di decisioni architetturali che hai preso prima di delegare.
Specificare → Chiarire → Pianificare → Implementare 🔁
Il flusso che funziona con gli agenti non è “chiedi e ricevi”. È un ciclo:
- Specificare: scrivi cosa vuoi che il sistema faccia. Obiettivi, utenti, scenari, criteri di accettazione.
- Chiarire: l’agente fa domande sulle ambiguità. Non scansare le domande: rispondi. Ogni domanda non risposta è un assunto architetturale che l’agente prenderà per te.
- Pianificare: l’agente propone architettura, moduli, interfacce. Revisiona prima di approvare.
- Implementare: solo dopo l’approvazione, l’agente scrive codice. Per incrementi, con test, con validazione.
Questo è esattamente ciò che spiegavo in Pianificare prima di generare: la pianificazione non è un passaggio opzionale. È il momento in cui previeni il 90% degli errori.
La specifica sopravvive al codice 💡
C’è un aspetto che molti sottovalutano: la specifica ha una vita più lunga del codice. Il codice viene riscritto, refactorto, sostituito. La specifica resta come documentazione di cosa il sistema doveva fare. E quando un nuovo membro del team si chiede “perché è stato fatto così?”, la specifica risponde.
In Greenfield da specifica approfondiamo il workflow completo: dalla scrittura della specifica all’AGENTS.md iniziale, dal piano architetturale al TDD come pilastro dell’implementazione.
La specifica non è un vincolo: è una liberazione. Ti libera dal dover ricordare ogni decisione architetturale. Ti libera dal dover riscrivere il codice quando cambiano i requisiti. Ti libera dal dover spiegare a ogni nuovo membro del team perché le cose sono fatte così.
In pratica 🔧
Alcune regole concrete per specifiche che funzionano con gli agenti:
- Scrivi la specifica in modo formale — non un messaggio su Slack, un documento che un collega potrebbe leggere e capire.
- Definisci i criteri di accettazione — cosa significa “funziona”? Test verdi? Performance? Usabilità?
- Indica i vincoli — cosa NON deve cambiare? API esistenti, formati di dato, dipendenze.
- Aggiorna la specifica quando cambiano i requisiti — una specifica obsoleta è peggio di nessuna specifica.
La prossima volta che inizi un progetto nuovo, prima di aprire il terminale, apri un documento. Scrivi cosa vuoi. Poi chiedi all’agente di leggerlo e di dirti cosa non ha capito. Quelle domande sono il tuo primo lavoro di specificazione.
E forse la lezione più importante: la specifica non è il contrario della velocità. È la sua premessa. Più specifichi bene, meno riscrivi. E meno riscrivi, più sei veloce — nonostante tutto quel tempo “speso” a specificare.