Nuovo progetto greenfield da specifica 🌱

Un progetto greenfield è la tentazione più grande e il rischio più alto. L’agente può generare centinaia di righe di codice in pochi secondi — ma se non hai una specifica chiave, otterrai centinaia di righe di codice sbagliato in pochi secondi. La differenza tra un greenfield riuscito e un disastro architetturale non è il tool: è la qualità della specifica che gli metti davanti.

La specifica non è un passaggio preliminare: è il contratto che sopravvive al codice.

Quando usare l’agente per questo caso 🎯

• Progetto completamente nuovo — nessun codice esistente, stack da definire.
• Prototipo rapido da specifica — hai un documento di requisiti e vuoi un MVP funzionante.
• Scaffolding iniziale — struttura del progetto, README, CI, test base.
• Migrazione da zero — riscrittura completa di un sistema legacy come nuovo progetto.

Quando NON usare l’agente ⛔

• Non hai una specifica — se l’idea è vaga, non delegare la definizione all’agente. Prima scrivi cosa vuoi, poi chiedi come farlo.
• Lo stack è critico e non l’hai definito — l’agente sceglierà la soluzione più comune, non la migliore per il tuo caso.
• Il progetto richiede integrazione hardware o fisica — l’agente non può testare ciò che non esiste nel suo ambiente.

Prompt di apertura 📝

“Partendo da questa specifica [link/blocco], costruisci [progetto]. Stack: [x]. Vincoli: [y]. Processo: prima piano, poi task, poi TDD. Non generare tutto in un passaggio.”

Esempio concreto:

“Partendo da questa specifica: ‘API REST per gestione ordini con autenticazione JWT, rate limiting, e integrazione PostgreSQL’, costruisci il progetto nella cartella corrente. Stack: Go + Chi + sqlx. Vincoli: test coverage >= 80%, nessuna dipendenza non approvata. Processo: prima piano architetturale, poi task incrementali con TDD.”

Setup del contesto 🔧

1. Crea subito AGENTS.md — definisci stack, versioni, librerie approvate e comandi di test. Questo è il contratto che guiderà l’agente per tutta la durata del progetto.
2. Scrivi la specifica in modo formale — obiettivi, utenti, scenari, criteri di accettazione. Non un’idea vaga: un documento che un collega potrebbe leggere e capire.
3. Definisci la “costituzione” — stack, standard di codifica, vincoli non negoziabili (es. “nessuna dipendenza GPL”, “test per ogni funzione pubblica”).

Ciclo di lavoro 💡

Il flusso spec-driven è il seguente:

1. Specificare: scrivi cosa vuoi che il sistema faccia (non come).
2. Chiarire: l’agente fa domande sulle ambiguità. Rispondi prima di procedere.
3. Pianificare: l’agente propone l’architettura dei moduli, le interfacce, lo schema dati.
4. Approvare: revisiona il piano. Questo è il momento di fermare derive architetturali.
5. Implementare per incrementi: MVP prima, espansione poi. Ogni incremento con test verdi.

Non generare l’intera architettura in un solo passaggio. Ogni riga non validata è un debito architetturale potenziale.

Usa modelli leggeri per le fasi iniziali (architettura, interfacce, schema dati) e riserva il modello più potente per la logica complessa.

Scelta dell’architettura greenfield 🏗️

La scelta dell’architettura è la decisione più impattante che prendi prima di delegare. Gli agenti funzionano meglio con certe strutture rispetto ad altre.

Il monolito modulare torna di moda nell’era degli agenti. I microservizi richiedono coordination overhead che gli agenti non gestiscono bene.

Regola pratica: parti da un monolito modulare. Seleziona i moduli lungo confini di dominio chiari. Delega ai moduli indipendenti la possibilità di essere estratti in servizi separati in futuro — ma non farlo ora.

La fase clarify: 5 archetipi di domande 💬

La fase di chiarimento è dove l’agente analizza la specifica e formula domande sulle ambiguità. Ci sono 5 archetipi ricorrenti:

Se l’agente non fa domande durante la fase clarify, è un segnale allarmante: significa che la specifica è troppo vaga o che l’agente sta saltando un passaggio critico.

Template: ADR Agent-Optimized 📋

Gli Architecture Decision Record (ADR) documentano le decisioni architetturali. Questo template è ottimizzato per l’uso con agenti, con “Agent Execution Rules” eseguibili:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

## ADR-NNN: [Titolo]

**Status:** [Proposed | Accepted | Deprecated]

### Context
[Descrizione del problema e dei vincoli]

### Decision
[La decisione espressa come regola eseguibile, non prosa]
> "Usiamo [scelta] perché [ragione]. NON usiamo [alternativa] perché [ragione]."

### Alternatives rejected
[Elenco delle alternative considerate e perché scartate — SEZIONE OBBLIGATORIA]

### Agent Execution Rules
- [ ] Verifica che il codice usi [scelta]
- [ ] Segnala come errore l'uso di [alternativa]

### Consequences
[Cosa cambia, cosa diventa più difficile]

La sezione “Alternatives rejected” è la più saltata e la più preziosa: documenta non solo cosa hai scelto, ma perché hai scartato le alternative. Senza di essa, un futuro sviluppatore (o un agente) potrebbe riesumare una soluzione già valutata e scartata.

Tabella anti-pattern 🚫

Criteri di accettazione ✅

• Piano architetturale approvato prima di scrivere codice.
• AGENTS.md presente con stack, versioni e comandi definiti.
• Test verdi per ogni incremento.
• Nessuna deriva architetturale rispetto al piano approvato.
• README, .gitignore e scaffolding CI presenti dalla prima release.

Approfondimenti 📚

• Scrivere prompt che funzionano — come strutturare la specifica nel prompt.
• Configurare il repository — AGENTS.md come contratto di progetto.
• Blog: Question-driven specification — il metodo per trasformare domande in specifiche eseguibili.
• Blog: Unknowns-driven development — come gestire l’incertezza nello sviluppo.