Il vibe-coding è una figata: lanci un’idea, l’AI scrive, tu testi e iteri.
Il problema è che senza una struttura portante, tutto resta in balia del caso. Ogni sessione è un nuovo inizio, ogni modifica un salto nel vuoto.
Serve un modo per tenere traccia di ciò che realmente si vuole, e darlo in pasto all’agente in modo chiaro, riproducibile e, soprattutto, mantenibile.
Per questo ho scoperto OpenSpec. E la mia vita da vibecoder è cambiata.
Il workflow che (finalmente) funziona
OpenSpec definisce un ciclo di vita per le specifiche dei progetti basato su quattro passaggi standard:
- /opsx-explore
- /opsx-propose
- /opsx-apply
- /opsx-archive
All’inizio ero scettico. Sembrava un’astrazione burocratica per tenere traccia di decisioni. Poi ho provato a usarlo per un progetto reale: FitCoach, un’app per analizzare in dettaglio i dati raccolti dal mio Fitbit Sense 2 durante gli allenamenti.
Il passo più importante: /opsx-explore
Prima di scrivere una riga di codice, ho invocato /opsx-explore con l’agente AI (DeepSeek v4, sia flash che pro, tramite il piano OpenCode Go(*) che con 10$ al mese ti dà accesso con limiti molto generosi a una discreta quantità di modelli).
L’ordine iniziale è stato qualcosa di simile a: “I’ve a FitBit device using Google Health API, I want build a modern and sleek web application that can connect Google Health API, retrieve the fitness and body data, store them in a local SQLite database and then display the data in a Dashboard. The application must be easy to deploy with a single docker compose up -d --build command and must provide a useful README.md file to explain the user the detailed steps to connect the application to Google Health API“
Il risultato? L’agente non si è limitato a scrivere codice. Ha posto domande, identificato ambiguità, suggerito architetture alternative e addirittura evidenziato potenziali limiti delle API di Google Health.
Invece di ottenere un blocco di funzioni da sistemare dopo, mi sono ritrovato con una specifica dettagliata e condivisa da cui partire.
Questo passaggio è il cuore pulsante di OpenSpec: esplorare prima di proporre evita l’80% dei refusi e delle false partenze.
BONUS: informazioni sulle API di Google Health
Siccome nessuno conosce le API di Google meglio di… Google stessa, per sapere quali dati sono presenti, come vengono fatti certi calcoli, quali sono gli scope utili per realizzare un’applicazione di questo tipo, ho chiesto a Google Gemini.
Da esplorazione a specifica viva
Con la specifica sotto mano, il resto del workflow è filato liscio:
- /opsx-propose: ho chiesto all’agente di generare la struttura dei file, i modelli dati e le viste principali. Ogni proposta era accompagnata dal perché di quella scelta, con riferimenti alla specifica iniziale.
- /opsx-apply: ho applicato le modifiche, commit per commit, con messaggi automatici che collegavano ogni cambiamento alla specifica di origine.
- /opsx-archive: quando una feature era completa e testata, archiviavo la specifica, tenendo traccia della decisione e del perché.
Il bello è che il workflow è lineare, ma non rigido. Puoi tornare indietro, ramificare, o integrare passaggi più complessi (merge di specifiche, revisioni multiple, code review asincrona). Il framework è pensato per scalare e, cosa più importante di tutte, funziona maledettamente bene e lo fa rimanendo semplice.
Perché è stato magico con DeepSeek v4 su OpenCode Go
Avere a disposizione DeepSeek v4 (ma anche altri modelli, come Qlm, Kimi, Mimo, MiniMax e Qwen) quasi senza limiti per 10€ al mese è già di per sé un affarone. Ma combinarlo con OpenSpec ha reso l’esperienza produttiva oltre che economica. Il modello “flash” è perfetto per esplorazioni rapide e proposte strutturate; il modello “pro” per le rifiniture e per ragionamenti più profondi. Ho potuto passare da un modello all’altro senza interrompere il flusso, e OpenSpec teneva traccia dello stato delle specifiche indipendentemente dal modello usato.
Il risultato? FitCoach è nato in un weekend, con meno di 10€ di API. L’app è disponibile su GitLab, ovviamente con licenza GNU GPLv3 o successive, pronta per essere testata, forkata e migliorata (è ancora pesantemente in fase di sviluppo).
Oltre il workflow base: la vera potenza di OpenSpec
Attenzione però, se pensi che il ciclo explore -> propose -> apply -> archive sia tutto qui, ti stai fermando alla copertina del libro. OpenSpec permette di:
- Comporre specifiche: puoi unire più esplorazioni in una proposta unica.
- Versionare le specifiche: ogni modifica è tracciata, e puoi tornare indietro.
- Integrare con CI/CD: le specifiche possono generare automaticamente test e documentazione.
- Collaborare: più agenti (o umani) possono lavorare sulla stessa base di specifiche, con conflitti gestiti tramite merge request.
Ma la vera forza sta nella disciplina spec-driven. Anche quando il vibe-coding prende il sopravvento, avere una specifica a cui attenersi, come unica fonte di verità, impedisce a gli agenti di deviare da gli obiettivi.
E quando il codice ti esplode tra le mani (perchè succede, eccome), non devi ricostruire a mente l’albero delle decisioni. È lì, scritta nero su bianco.
Il mio consiglio
Se fai self-hosting, sviluppi strumenti personali o semplicemente ami smanettare con l’AI generativa, prova OpenSpec. Inizia con il workflow standard, non serve altro. Fallo per un progetto piccolo, come il mio FitCoach. Usa sempre opsx-explore per davvero, approfondisci ogni dettaglio prima di far scrivere codice.
Per quanto mi riguarda, quando ho un nuovo progetto, OpenSpec è il mio compagno di banco preferito.
(*) Qui potete trovare un’ottima guida su come utilizzare i modelli OpenCode Go con Visual Studio Code e Github Copilot