Sviluppo spec-driven con agent AI: il playbook Laravel
Di Andrea Pollastri · Ultimo aggiornamento: · lettura gratuita, nessun paywall
Gli agent AI scrivono ora una quota significativa del codice in produzione. I team che ottengono risultati duraturi non sono quelli con i prompt migliori — sono quelli con le spec migliori, i guardrail più stretti e tool che gli agent possono usare in sicurezza. Ecco il playbook, edizione Laravel.
Da autocomplete ad agent
L'arco dal 2023 al 2026 si riassume facilmente: le completion sono diventate chat, le chat agent che modificano interi branch, eseguono test e aprono pull request. Il collo di bottiglia si è spostato con loro — da "il modello sa scrivere codice?" a "il modello sa cosa vogliamo davvero e cosa può toccare?". È un problema di contesto e permessi, non di modello. Due pratiche lo affrontano: spec e MCP.
Spec invece di vibe
Il "vibe coding" — promptare un agent feature per feature con l'intento che vive nella cronologia chat — produce codice che funziona oggi e non è manutenibile tra sei mesi, perché il perché evapora quando la chat si chiude. Lo sviluppo spec-driven inverte tutto:
- Le spec sono artifact nel repository, versionate accanto al codice che descrivono — non prompt persi in una sidebar.
- I criteri di accettazione vengono prima e si traducono direttamente in test Pest: la spec definisce "fatto" prima che l'agent scriva una riga.
- Gli agent implementano rispetto alla spec, gli umani revisionano rispetto alla spec, e il drift diventa visibile invece che silenzioso.
- La spec sopravvive alla sessione. Sei mesi dopo, un nuovo developer — o un nuovo agent — legge intento, vincoli e decisioni in un solo posto.
Nel mondo Laravel, Larapilot impacchetta tutto come workflow prodotto spec-driven che vive dentro il tuo progetto Laravel — spec, decisioni e artifact di delivery nel repo, dove agent e umani li trovano entrambi. Per l'argomento più profondo sul perché il contesto-nel-repo è ciò che mantiene un prodotto vivo oltre l'anno uno, vale la pena leggere il saggio di Andrea Pollastri "Building a SaaS That Survives Its Second Year".
MCP: lo standard che ha reso utili gli agent
Il Model Context Protocol è l'USB-C del tooling AI: un protocollo aperto attraverso cui gli agent scoprono e chiamano tool — database, browser, issue tracker, server — invece di fare screen-scraping o plugin su misura. Per un team Laravel, i server MCP interessanti sono quelli che toccano la pipeline di delivery:
- Il tuo framework: introspezione di route, schema e job così l'agent smette di indovinare.
- La tua infrastruttura: qui diventa concreto — Cipi include un dual MCP server (globale e per-app), così un IDE o agent compatibile MCP può creare app, triggerare deploy, gestire SSL e database sul tuo VPS tramite un'API strutturata e con permessi invece di SSH grezzo. Il package Cipi Agent aggiunge un endpoint MCP in-app sul lato Laravel.
- I tuoi quality gate: agent che possono eseguire la suite di test e leggere i risultati CI chiudono il proprio feedback loop.
Guardrail che funzionano davvero
- I test sono il contratto. Gli agent spediscono più velocemente di quanto gli umani possano revisionare riga per riga; i test di accettazione derivati dalla spec sono ciò che "corretto" significa.
- CI è l'arbitro. Pint, Larastan, Pest e composer audit girano su ogni PR dell'agent, senza eccezioni — la stessa pipeline degli umani.
- Least privilege per gli agent. Token API con scope, server MCP con allow-list esplicite di tool e nessun segreto di produzione nell'ambiente dell'agent. Un agent che deploya tramite MCP/API di Cipi può deployare — e nient'altro.
- Review umana per il diff sensibile: auth, pagamenti, migrazioni e tutto ciò che tocca PII passa sempre sotto occhi umani.
- Il rollback resta a un comando di distanza — deploy con pattern releases e snapshot pre-deploy fanno sì che un errore dell'agent sia un incident, non una catastrofe.
Un loop concreto spec-to-production
- Scrivi la spec (problema, vincoli, criteri di accettazione) come artifact nel repo — Larapilot le dà struttura.
- L'agent implementa su un branch di breve durata, usando tool MCP per introspezione dell'app ed esecuzione test in locale.
- CI esegue il gate completo — style, analisi statica, test, audit di sicurezza.
- Un umano revisiona rispetto alla spec, non rispetto ai vibe.
- Merge su main triggera il webhook di deploy (zero-downtime via Cipi), i health check confermano, le eccezioni sono osservate nei primi minuti (Boogle se self-hosti).
- La spec viene aggiornata con ciò che è stato deciso davvero — chiudendo il loop di contesto per la prossima sessione, umana o agent.
Cosa dura vs cosa è hype
| Durevole | Hype (per ora) |
|---|---|
| Spec come artifact versionati nel repo | Librerie di prompt come sostituto dei requisiti |
| MCP come standard di accesso ai tool | Agent con SSH di produzione senza restrizioni |
| Agent gated da CI + review umana | "L'agent si revisiona da solo" |
| Deploy reversibili con un comando | Generazione app one-shot senza piano di manutenzione |
Il pattern dietro ogni voce durevole: gli agent amplificano qualunque processo esista. Spec, test e automazione deploy buoni diventano velocità; la loro assenza diventa caos.
Mettilo in pratica con Cipi
Cipi è la CLI di deploy gratuita e open source citata in tutta questa guida: un comando trasforma un VPS Ubuntu fresco in un server di produzione hardened per Laravel — Nginx, PHP-FPM o Octane, MariaDB o PostgreSQL, queue, scheduler, SSL e deploy Git zero-downtime inclusi.
Domande frequenti
Cos'è lo sviluppo spec-driven in una frase?
Scrivere specifiche versionate — problema, vincoli, criteri di accettazione — come artifact nel repository che gli agent AI implementano e gli umani revisionano, così l'intento sopravvive più a lungo di qualsiasi sessione chat.
Cos'è MCP (Model Context Protocol)?
Un protocollo aperto che standardizza come gli agent AI scoprono e chiamano tool esterni — database, browser, server, API — così qualsiasi agent compatibile MCP può usare qualsiasi server MCP senza integrazioni custom. Cipi, ad esempio, espone la gestione server (app, deploy, SSL, database) come tool MCP.
Gli agent AI sostituiranno gli sviluppatori Laravel?
Il lavoro si sposta piuttosto che sparire: meno digitazione riga per riga, più specificare, revisionare e possedere architettura e produzione. Gli sviluppatori che scrivono spec chiare e costruiscono guardrail forti vengono moltiplicati dagli agent; la parte solo-codice del lavoro è ciò che si riduce.
Come faccio deployare in sicurezza con un agent AI?
Non dare mai agli agent SSH grezzo o segreti di produzione. Instrada il loro accesso tramite interfacce con scope e revocabili — un server MCP o REST API con permessi espliciti, come quello di Cipi — e metti ogni cambiamento dietro CI e il pattern releases, così ogni deploy è reversibile con un comando.
Lo sviluppo spec-driven funziona con codebase legacy esistenti?
Sì — parti scrivendo spec per il prossimo cambiamento, non per l'intero sistema. Ogni spec documenta una fetta di comportamento inteso, e l'archivio cresce in documentazione vivente esattamente dove agent e nuovi membri del team ne hanno bisogno.
