Oltre il vibe coding per il web

1. Introduzione

Man mano che gli agenti di codifica diventano parte integrante dello sviluppo software quotidiano, che tu sia un ingegnere esperto o un nuovo sviluppatore che vuole lanciare la sua prima app, il modo in cui crei e ciò che crei sta cambiando radicalmente. Quando inizi a utilizzare gli agenti di codifica, in genere inizi con prompt "zero-shot", ovvero una singola istruzione che indica in breve, in linguaggio umano, ciò che vuoi. Questo approccio presenta rapidamente dei problemi:

• Bias di compiacenza: i modelli spesso accettano vincoli o premesse imperfetti, cercando di completare la richiesta il più rapidamente possibile e non verificano che ciò che stanno creando faccia effettivamente ciò che intendevi.
• Lacuna di verifica: gli agenti, anche quando scrivono test, in genere non controllano il proprio lavoro per assicurarsi che funzioni. Se provi a utilizzare i siti web in un browser live, vengono visualizzati bug nascosti, layout danneggiati e controlli inaccessibili.
• Debito tecnico: a causa del modo in cui i modelli vengono addestrati e funzionano, il codice che scrivono tende a seguire pattern vecchi e obsoleti, aumentando il debito tecnico che costa più token e più tempo e impegno per la gestione da parte di persone e macchine. Il debito tecnico può persino influire negativamente sull'esperienza utente.

Il piano strategico in 4 passaggi

Per aiutare gli agenti di programmazione a produrre codice migliore e più in linea con i tuoi requisiti, ti consigliamo di seguire un ciclo di vita di sviluppo del prodotto in quattro fasi:

1. Pianificazione e progettazione: scrivi in collaborazione con l'agente i documenti dei requisiti di prodotto (PRD) e chiedigli di creare prototipi e progettare i PRD nel browser prima di iniziare l'implementazione della produzione, quindi crea bozze di documenti di progettazione (specifiche) dell'architettura a partire dai PRD e dai progetti prima di iniziare la programmazione.
2. Codifica e creazione: chiedi agli agenti di creare in base a PRD, progetti e specifiche anziché a un prompt zero-shot e di eseguire un altro agente per controllare il proprio lavoro.
3. Ripeti: esegui di nuovo i passaggi 1 e 2 per ogni nuova funzionalità che vuoi aggiungere.
4. Esegui il deployment: invia in produzione.

Questo documento ti guida nell'utilizzo degli agenti AI come partner di collaborazione attivi con pratiche pensate per aiutarti a ridurre il debito tecnico e migliorare la qualità del codice di output. Utilizzi Antigravity in combinazione con Modern Web Guidance e DevTools for Agents per creare un gioco di parole informale e migliorarlo con funzionalità di AI. Poi lo esegui il deployment su Google Cloud utilizzando Firebase per condividerlo con amici e familiari.

Obiettivi didattici

• Come trattare le attività di programmazione dell'AI come mini cicli di sviluppo del prodotto.
• Perché dovresti separare i requisiti del prodotto dalle specifiche dell'architettura.
• Come orchestrare i workflow multi-agente per creare prototipi direttamente nel browser ed esaminare il codice.
• Come sfruttare competenze e strumenti di terze parti per migliorare sia lo sviluppo che l'esperienza utente.
• Come eseguire il deployment di applicazioni web direttamente in produzione utilizzando Firebase MCP.

Prerequisiti

• Un Account Google personale e un progetto Google Cloud o Firebase (istruzioni nella configurazione del progetto)
• Una certa familiarità con HTML, CSS e JavaScript.
• Un browser web come Chrome.
• Node.js installato (è consigliata la versione LTS).

2. Configurazione del progetto

Account Google

Se non hai ancora un Account Google personale, puoi crearne uno.

accedi alla console Google Cloud

Accedi alla console Google Cloud utilizzando un Account Google personale.

Abilita fatturazione

Suggerimento:se configuri la fatturazione utilizzando i crediti Google Cloud, puoi passare a "Crea un progetto Firebase".

Per configurare un account di fatturazione personale, vai ad abilitare la fatturazione nella console Cloud.

Crea un progetto Firebase

Suggerimento:se hai configurato un progetto Google Cloud nell'ambito della configurazione dei crediti Google Cloud, utilizzalo per configurare il progetto Firebase. In questo caso, non devi collegare il tuo account di fatturazione perché è già collegato.

1. Vai alla console Firebase e accedi con il tuo Account Google personale.
2. Fai clic su Aggiungi progetto (o Crea un progetto).
3. Nella procedura guidata di creazione del progetto:
   • Inserisci un nome del progetto (ad esempio wordup-web-app) o riutilizza il progetto Google Cloud che hai configurato durante la configurazione del progetto.
4. Collega account di fatturazione
   • Nella barra laterale della console Firebase, individua il badge del piano in basso (con la dicitura "Spark"). Fai clic su Esegui upgrade.
   • Seleziona il piano Pay as you go.
   • Seleziona l'account di fatturazione che hai configurato durante il passaggio Configurazione del progetto.
   • Conferma la selezione per collegare l'account di fatturazione al progetto. (Firebase Hosting offre un generoso livello senza costi; il completamento di questo tutorial in genere non comporta costi).

Installare gli strumenti

• Antigravity 2.0: l'imbracatura di codifica agentica principale con cui lavori, abbinata all'ultimo modello Gemini Flash per una codifica rapida e all'avanguardia.
• Modern Web Guidance: skill per gli agenti di programmazione per aiutarli a scrivere CSS, HTML e JavaScript moderni. Installa tramite Antigravity Impostazioni > Personalizzazione > Build With Google Plugins > Modern Web Guidance.
• DevTools per agenti: consente agli agenti di controllare Chrome, ispezionare il DOM live, testare il layout ed eseguire il debug in fase di runtime. Installa tramite Antigravity Impostazioni > Personalizzazione > Crea con i plug-in di Google > Chrome DevTools e Antigravity Impostazioni > Personalizzazione > Aggiungi server MCP > Chrome DevTools per agenti.
• Server MCP Firebase: per una configurazione del progetto semplice e implementazioni con un solo prompt. Installa tramite Antigravity Impostazioni > Personalizzazione > Build With Google Plugins > Firebase and Antigravity Settings > Personalizzazione > Add MCP Servers > Firebase.

3. Inizia con un piano

La tentazione più comune nella programmazione con agenti è inviare un prompt zero-shot ("Crea un gioco di parole") e sperare per il meglio. Quasi sempre, ciò comporta casi limite ignorati, codebase gonfie e cicli di correzione di bug infiniti.

Considera ogni attività come un mini ciclo di vita di sviluppo del prodotto. Gli agenti di programmazione dispongono di strumenti di ricerca e ragionamento che consentono loro di fungere da partner collaborativo per aiutarti a chiarire le tue idee prima di scrivere qualsiasi codice. Il semplice fatto di parlare della tua idea spesso ti aiuta a trovare e rispondere alle domande prima che diventino problemi. Nell'ingegneria del software, questo si chiama debug della paperella di gomma. Puoi utilizzare i tuoi agenti di programmazione come rubber duck per pianificare i tuoi progetti e le tue funzionalità.

Stai creando un gioco di parole casual. Chiedi all'agente di aiutarti a progettare il gioco che desideri.

I want to make a casual word guessing game. Go do deep research on those kinds
of games, then ask me questions to help me write a PRD for the game's features.

Questa è la forma base del prompt. Modificala in base alle tue esigenze. La cosa fondamentale è che faccia ricerche approfondite e ti ponga domande basate su queste ricerche per aiutarti a pianificare il tuo lavoro.

Inizia con questo prompt perché lavorare con gli agenti di codifica comporta molte revisioni. Dividere un piano di implementazione completo in parti più piccole e mirate semplifica notevolmente la revisione, consente di individuare in anticipo i casi limite, può apportare conoscenze al di fuori dei dati di addestramento dell'agente e, soprattutto, consente di fare più pause tra una revisione e l'altra.

• Separa il "cosa" dal "come": definire l'esperienza utente e l'ambito del prodotto in un documento sui requisiti del prodotto (PRD) formale separa cosa vuoi che accada da come viene implementato, consentendoti di concentrarti su un aspetto dello sviluppo del prodotto alla volta anziché su tutto contemporaneamente.
• Identifica i casi limite in anticipo: una sessione interattiva di domande e risposte ti costringe a chiarire i tuoi requisiti prima dell'inizio della progettazione o dell'implementazione.
• Ricerca di agenti attivi: poiché l'addestramento degli agenti viene interrotto a una determinata data e le informazioni in esso contenute vengono riassunte, l'estrazione di informazioni dalla ricerca in tempo reale può fornire nuove informazioni che altrimenti non sarebbero disponibili.

Suggerimento:se vedi il tuo agente di codifica fare qualcosa che ti piace o che non ti piace, puoi aggiungere istruzioni a un file AGENTS.md nella cartella del progetto per correggere o rafforzare il suo comportamento. Prova ad aggiungere quanto segue per assicurarti che Antigravity utilizzi lo strumento per le domande integrato quando ti pone delle domande:

When I ask you to ask me questions, you are **REQUIRED** to use your `ask_question` tool to do so.

Esercizio 1

Ora tocca a te. Configura il progetto e crea il PRD.

1. Aggiungi un'istruzione al file AGENTS.md per indicare di salvare l'output in docs/plans/{{YYYY-MM-DD}}-{{description}}.md.
2. Esegui il prompt di ricerca precedente, con le modifiche che preferisci, per creare il PRD.
3. [Obiettivo ambizioso] Aggiorna il file AGENTS.md con le azioni dell'agente che non ti piacciono ed esegui di nuovo il prompt.

Suggerimento: Antigravity 2.0 ha un comando /grill-me che puoi eseguire specificamente per questo tipo di esplorazione.

Best practice:Antigravity 2.0 ha uno strumento "Artefatto" che ti consente di commentare riga per riga o evidenziare un testo specifico e lasciare commenti, proprio come in Documenti Google. Devi lasciare i commenti in linea anziché aggiungerli al prompt. Salva il prompt per i commenti a livello di documento. L'invio del prompt, anche se vuoto, invia i tuoi commenti e indica ad Antigravity di rigenerare il documento tenendo conto dei tuoi commenti.

Attenzione:a volte, anche quando gli chiedi di scrivere solo un PRD, include la progettazione e l'architettura del software nel PRD. In questo caso, lascia un commento o chiedi di rimuovere questi elementi e di concentrarsi solo sull'esperienza utente.

4. Progettare nel browser

Il design dell'interfaccia utente statica si basa su mockup spesso straordinari, ma che non tengono conto di casi limite, vincoli e interazioni effettive degli utenti. Proprio come il codice, chiedere a un agente di "progettare" l'applicazione del tuo sito genera progetti che convergono verso un design generico (spesso viola).

Per le app web, puoi utilizzare la capacità dell'agente di controllare un browser web tramite DevTools per gli agenti per progettare in il browser. Che tu sia un designer che lavora per migliorare la fedeltà dei tuoi progetti, un programmatore o un costruttore che cerca di migliorare l'interfaccia utente e l'esperienza utente del tuo progetto o che siate entrambi a lavorare insieme, lavorare nel mezzo effettivo per cui stai creando produce risultati migliori.

La progettazione nel browser ti offre anche l'opportunità di coordinare più agenti che lavorano insieme per produrre un unico output. Questi subagenti sono agenti con scopi e personalità specifici che possono essere coordinati per produrre risultati migliori rispetto a un singolo agente che lavora da solo. Con la progettazione, puoi richiedere a un agente di progettazione visiva, a un agente di esperienza utente e a un agente di accessibilità di collaborare per aiutarti con il tuo progetto e di mostrartelo direttamente nel browser.

Attenzione:l'utilizzo di subagenti per completare le attività utilizza più token. Sebbene possano produrre risultati di qualità molto superiore, tieni presente che il loro utilizzo può comportare costi aggiuntivi.

Avvia un gruppo di agenti di progettazione per aiutarti a scegliere un design in base al tuo PRD.

Using the PRD, start a panel of expert agents: one UX design, one web
accessibility, and one for visual design, and have them work together to design
3 different UI mockups and show them to me in-browser.

Suggerimento:puoi digitare @ nell'area dei prompt di Antigravity e iniziare a digitare il nome di un file per indicare ad Antigravity il file specifico che vuoi che esamini.

Progettare nel mezzo per cui stai creando, in questo caso il web, anziché in un mezzo statico, ti consente di individuare casi limite e vincoli difficili da gestire altrimenti e di ottenere un feedback visivo immediato fedele alla produzione.

Esercizio 2

Ora tocca a te. Progetta il tuo progetto.

1. Esegui il prompt di progettazione precedente, con le modifiche che preferisci, per sviluppare il progetto. Includi idee per le diverse direzioni di design che vorresti vedere (ad esempio moderno, giocoso, realistico e così via).
2. Scegli un design che ti piace e perfezionalo con il tuo agente.
3. Chiedi al tuo agente di aggiornare il PRD in modo che rimandi al design concordato.
4. Obiettivo ambizioso: esegui test di accessibilità e di progettazione reattiva per il design scelto e modificalo in base a questi audit.

Attenzione:a volte gli agenti diventano troppo zelanti e interpretano questa indicazione come approvazione per creare l'intera applicazione. Osserva il suo ragionamento e, se noti che sta facendo più di quanto ti aspetti, fermalo e chiedigli di cambiare rotta.

5. Scrivere una specifica

Con un PRD approvato ("cosa costruire") e un design visivo selezionato ("come appare"), ora devi allineare l'architettura a livello tecnico ("come costruirlo").

Un documento di progettazione tecnica o una specifica, in breve spec, descrive in dettaglio le strutture dei file, la gestione dello stato, le interfacce dei componenti, le pipeline di eventi e le dipendenze. La creazione di una specifica prima di scrivere il codice consente di rilevare disallineamenti e pattern di codifica indesiderati in anticipo, prima che si trasformino in codice più difficile da comprendere e refactoring.

Write a detailed technical design document on how to implement the game with
the chosen design.

Perché lo fai

• Chiarezza architetturale: la definizione della gerarchia dei componenti e del flusso di transizione di stato (ad esempio, Idle → InGame → EvaluatingGuess → GameOver) impedisce le race condition e il codice spaghetti fragile.
• Allineamento agli standard moderni: con la Guida al web moderno attivata, l'agente fa riferimento a standard moderni (ad esempio, query CSS @container, elementi
  integrati per modali o overlay di assistenza e moduli ES modulari) anziché estrarre librerie legacy pesanti.
• Revisioni in più fasi: la separazione della revisione del PRD funzionale dalla revisione del documento di progettazione tecnica consente di valutare l'architettura indipendentemente dall'esperienza utente.

Esercizio 3

1. Chiedi al tuo AGENTS.md di salvare l'output nella cartella corrente:

   PRDs should _always_ be written to the current project's root in `docs/plans/{{YYYY-MM-DD}}-{{description}}.md` format
   

2. Esegui il prompt del documento di progettazione e rivedilo, assicurandoti che copra aspetti come la struttura delle directory, la gestione degli eventi e l'archiviazione.
3. Obiettivo ambizioso: includi diagrammi di Mermaid per spiegare il flusso di stato nell'applicazione, se non sono già inclusi.

6. Infine, crea l'app

Con il PRD, il mockup della UI e il documento di progettazione stabiliti, è il momento di iniziare a creare. Questi tre elementi sono le indicazioni chiare e inequivocabili di cui gli agenti hanno bisogno per creare le risposte.

Ecco un'altra buona opportunità per utilizzare i subagenti. Puoi eseguirli dopo la creazione del codice per verificare la corrispondenza tra il codice creato e i progetti iniziali e un altro per controllare la qualità del codice creato.

Use the PRD, design doc, and mockup to implement the site, then send out 2
agents, one to check how closely you followed the requirements, and one to
review the code.

Perché lo fai

Lo sviluppo basato sulle specifiche con revisori di primo passaggio fornisce all'agente requisiti chiari e pre-verificati da cui partire, nonché un nuovo punto di vista per assicurarsi che il piano sia stato rispettato prima di arrivare a te, migliorando la qualità e la fedeltà.

• Requisiti verificati: l'agente non deve tirare a indovinare cosa vuoi, perché hai già esaminato tutto tranne l'implementazione prima che venga scritto qualsiasi codice.
• Nuovo punto di vista: un agente di revisione generato in un nuovo contesto non ha alcun bias di conferma derivante dalla creazione del codebase, il che lo rende efficace nell'individuare casi limite non gestiti, requisiti di implementazione mancanti e altri dettagli del codice o del prodotto che sono stati trascurati.

Esercizio 4

1. Esegui il prompt di build, indicando i file esatti che vuoi che esamini.
2. Guarda l'output mentre viene eseguito. Vedrai il ragionamento in base ai tuoi requisiti mentre cerca di sviluppare la richiesta. Se qualcosa sembra andare fuori controllo, puoi fermarlo e correggerlo.
3. Fai eseguire il server di sviluppo per visualizzare il sito finale e controllarne il funzionamento.
4. Obiettivo ambizioso: ripeti questa procedura per aggiungere test automatizzati.
5. Obiettivo ambizioso: scegli un framework o uno stack tecnologico specifico in cui vuoi che venga creato il sito. Con il PRD, il mockup e il documento di progettazione separati, dovrebbe essere semplice adattarli a framework o stack tecnologici diversi.

7. Distribuzione in produzione

Hai pianificato, progettato e codificato. Cosa rimane? Esegui il deployment in produzione.

Deploy this site to my Firebase project [YOUR_PROJECT_ID] using Firebase
Hosting.

Attenzione:se non funziona, assicurati di aver installato Firebase MCP. Potresti anche dover accedere la prima volta che lo esegui.

Esercizio 5

1. Esegui la richiesta di deployment sostituendo l'ID progetto.
2. Copia l'URL dell'hosting live fornito dall'agente.
3. Apri l'URL pubblicato per verificare che sia stato implementato e che funzioni.
4. Obiettivo ambizioso: utilizza DevTools per gli agenti per eseguire un controllo Lighthouse del tuo sito di produzione, apportare modifiche per migliorare il punteggio Lighthouse e pubblicare gli aggiornamenti.

8. [Facoltativo] Miglioramenti dell'AI

Il tuo gioco di parole ora è completamente funzionale e utilizza un dizionario statico. Per trasformare il dizionario statico in una parola dinamica, puoi invece richiedere una parola ogni volta utilizzando un modello linguistico locale di piccole dimensioni dall'API Prompt.

Attenzione:se non l'hai ancora fatto, assicurati di aver installato Modern Web Guidance per ricevere assistenza.

Poiché questa funzionalità non è disponibile su tutti i dispositivi, utilizza il potenziamento progressivo per verificare se l'API e il modello sono disponibili. Se lo sono, li utilizzi; in caso contrario, utilizzi l'elenco statico.

Esercizio 6

Metti in pratica tutto ciò che hai imparato.

1. Collabora con il tuo agente per scrivere un PRD per utilizzare l'API Prompt per generare una parola nascosta valida.
2. Progetta la barra di avanzamento del download e l'UI di integrazione dell'AI nel browser.
3. Scrivi una specifica per l'implementazione. Suggerimento: esegui un agente per assicurarti che qui sia stata utilizzata la sintassi API corretta.
4. Sviluppa la nuova funzionalità.
5. Esegui il deployment in produzione.

9. Conclusione

Complimenti. Hai creato, perfezionato, migliorato ed eseguito il deployment di un'applicazione web moderna, accessibile e basata sull'AI utilizzando le best practice di programmazione agentica.

Che cosa hai imparato

• Workflow degli agenti basati sui prodotti: in che modo il trattamento delle attività come mini cicli di vita dei prodotti (PRD → Progettazione → Specifica → Sviluppo) riduce il debito, il sovraccarico di revisione e l'attrito avanti e indietro.
• Pannelli di specialisti multi-agente: in che modo l'esecuzione di più subagenti AI può contribuire a migliorare la qualità e la fedeltà del tuo lavoro.
• PRD e documentazione di progettazione: perché separare l'ambito funzionale (piano) dall'architettura tecnica (specifiche) è un processo più scalabile e accurato rispetto al prompt delle funzionalità zero-shot.
• Deployment senza problemi: come utilizzare i server MCP (come Firebase MCP) per semplificare l'accesso a sistemi di terze parti, ad esempio il deployment del tuo sito.