1. Introduzione e configurazione
Ti diamo il benvenuto
Ciao! Ti diamo il benvenuto in Coding Jam. Nei prossimi 75 minuti, creerai una vera e propria app web AI funzionante.
Consulta il sito web qui: sito web di Coding Jam
Cosa creerai
Un'app web basata sull'AI e sul brief del progetto di questa settimana. Viene eseguito nel browser. Utilizza l'AI Gemini di Google. Sarà completamente tuo alla fine della sessione.
Installare Antigravity
Antigravity è l'assistente AI che useremo per tutto. È un'app che viene installata sul computer.
Passaggio 1: scarica
👉 Vai alla pagina https://antigravity.google/download nel browser.
👉 Fai clic sul pulsante di download per il tuo sistema operativo (Mac, Windows o Linux).
👉 Esegui il programma di installazione scaricato. Le impostazioni predefinite vanno bene: fai clic per visualizzarle.
Passaggio 2: avvia e accedi
👉 Avvia Antigravity dalla cartella Applicazioni (Mac) o dal menu Start (Windows).
👉 Fai clic su "Accedi" quando richiesto.
👉 Utilizza il tuo Account Google.
Passaggio 3: verifica la schermata di benvenuto
Dovresti vedere la schermata di benvenuto di Antigravity con tre pulsanti grandi:
- Apri cartella: apre una cartella esistente come spazio di lavoro
- Apri Agent Manager: si apre la dashboard dell'agente (qui si svolgerà la maggior parte del nostro lavoro)
- Clona repository: scarica un progetto da GitHub (lo utilizzeremo nella sezione 3A)
Se vuoi approfondire l'argomento, consulta altri documenti all'indirizzo https://antigravity.google/.
✅ Checkpoint: Antigravity è installato, hai eseguito l'accesso e vedi la schermata di benvenuto con tre pulsanti.
2. Installare gli strumenti richiesti (tramite Antigravity)
Antigravity ha bisogno di due strumenti di assistenza sul computer:
Strumento | Che cos'è (in parole semplici) |
uv | Gestisce Python, il linguaggio alla base del backend dell'app |
git | Scarica i file di progetto da internet (Antigravity lo utilizza per la clonazione) |
Non dovrai digitare manualmente i comandi di installazione. Tu chiedi ad Antigravity in inglese, al resto ci pensa lui.
Passaggio 1: apri uno spazio di lavoro temporaneo
Antigravity ha bisogno di una cartella aperta per chattare. (Nessuna cartella = nessuna chat.)
👉 Nella schermata di benvenuto, fai clic su "Apri cartella".
👉 Crea o scegli una cartella vuota. Consigliato: una nuova cartella chiamata coding-jam-setup in una posizione comoda (il desktop va bene).
👉 Fai clic su Apri (o Seleziona cartella).
Si apre la visualizzazione di Agent Manager con il nuovo workspace (vuoto) selezionato.
Passaggio 2: chiedi ad Antigravity di controllare e installare gli strumenti
👉 Premi Cmd+L (Mac) o Ctrl+L (Win/Linux) per mettere a fuoco l'input della chat.
👉 Verifica che il menu dei modelli in basso mostri Gemini 3 Flash (impostazione predefinita, adatta a questo scopo).
📝 Prompt più semplice: incollalo nella chat:
Install uv and git on my computer if they're not already there.
Don't install Node.js. Ask permission before each install command.
📝 Versione più dettagliata (se vuoi):
Check whether uv and git are installed by running their --version commands.
For any tool that's missing, install it using the best method for my OS:
- Mac: prefer `brew install` (install Homebrew first if missing)
- Windows: prefer `winget install`
- Linux: prefer `apt install` or `dnf install`
Ask permission before each install command.
Do NOT install Node.js — we'll install it later only if needed.
When done, give me a summary of what's installed.
👉 Premi Invio per inviare.
🤖 Guarda l'agente lavorare, fai clic su Consenti nei popup
Passaggio 3: leggi il riepilogo
Al termine dell'operazione, vedrai un messaggio simile a questo:
✅ Setup complete:
- uv 0.4.18 ✅ (installed)
- git 2.42.0 ✅ (already had it)
- Node.js: skipped (will install later if needed)
In caso di problemi
✅ Checkpoint: l'agente conferma che uv e git sono entrambi installati. Tempo totale: circa 3-5 minuti (o circa 7 minuti se Homebrew deve essere installato prima su Mac).
Clonare il progetto
1. Scegli il progetto della settimana
Coding Jam è un programma di 8 settimane con un mini-progetto diverso ogni settimana. Il tuo facilitatore ti dirà in quale settimana ci troviamo oggi. Trova la riga e copia l'URL.
Settimana | Progetto | URL del repository |
1 | Prova di acconciature con l'AI |
|
2 | Generatore di avatar AI |
|
3 | Il mio calendario dell'anno speciale |
|
4 | Dal frigo alla ricetta |
|
5 | Barattolo dell'umore AI |
|
6 | Portfolio di una pagina |
|
7 | Resume Tailor |
|
8 | Chat con personaggi AI |
|
2. Torna alla schermata di benvenuto
Dobbiamo tornare alla schermata di avvio per utilizzare il pulsante "Clona repository".
👉 In Antigravity, clona il progetto che preferisci. Esempio di clonazione della settimana 1, ma devi inserire il repository corretto.
📝 Prompt di riferimento
Git clone ⚠️ PASTE_YOUR_PROJECT and save to my local folder: ⚠️ PASTE_YOUR_PROJECT
3. Visita il progetto
Guarda l'elenco dei file. Dovresti vedere:
File / cartella | Descrizione |
BRIEF.md | L'idea del prodotto: cosa stiamo realizzando, in un linguaggio semplice |
reference/ | Una cartella con un'app di esempio funzionante. L'AI leggerà questo elemento quando scriverà il codice, in modo che la tua app corrisponda ai pattern. |
.gitignore | Un elenco di file che Git deve ignorare (tecnico, ignoralo) |
👉 Fai clic su
BRIEF.md per aprirlo. Ecco l'idea del progetto.
✅ Checkpoint: hai clonato il progetto, lo hai aperto come spazio di lavoro e hai letto BRIEF.md.
3. Installare le skill di Workshop
Una "skill" è un insieme di istruzioni archiviate su GitHub che puoi fornire alla tua AI.
Passaggio 1: chiedi ad Antigravity di installare le skill
📝 Incolla questo prompt nella chat:
Please install the workshop skills into this workspace's .agent/skills/
folder. Run these two git clones from the project root:
1. git clone https://github.com/cuppibla/skills-garden .agent/skills/skills-garden
2. git clone https://github.com/google-gemini/gemini-skills .agent/skills/gemini-skills
When Antigravity asks permission to run each command, I'll click Allow.
When done, list the skills that are now available in this workspace.
Passaggio 2: fai clic su Consenti nei due popup
🤖 Dovresti vedere qualcosa di simile a
I'll create the .agent/skills/ folder and clone both repos into it.
Running: git clone https://github.com/cuppibla/skills-garden .agent/skills/skills-garden
Consenti qualsiasi azione se l'agente lo richiede.
👉 Controlla l'elenco dei file. Ora dovresti vedere una nuova cartella .agent/. Fai clic per espanderla e assicurati che in questa cartella siano presenti più competenze, ad esempio skills-garden e gemini-skills.
A cosa serve ogni skill (per riferimento, non è necessaria alcuna azione)
Skill | Descrizione |
| Scrive il documento di progettazione del prodotto |
| Scrive il documento di progettazione dell'esperienza utente |
| Scrive il documento di progettazione tecnica (con la sezione Strategia di test) |
| Scrive test, li esegue e corregge automaticamente gli errori (massimo 3 tentativi) |
| Skill ufficiale di Google: come utilizzare correttamente l'API Gemini |
| Un backup più semplice se la skill ufficiale non è disponibile |
| Riferimenti allo stile visivo |
✅ Checkpoint: l'elenco dei file mostra una nuova cartella .agent/skills/ con skills-garden/ e gemini-skills/ al suo interno.
4. The Spec Talk
Spec Talk è una conversazione di due minuti in cui dici all'AI cosa vuoi creare. Nessun codice, nessun documento, ancora nulla è stato creato. Stiamo solo ragionando insieme.
L'unica domanda obbligatoria
La cosa più importante che l'AI deve sapere:
"Cosa entra, cosa esce?"
🎯 MODELLO: Gemini 3 Flash (predefinito): domande e risposte semplici.
📝 Incolla questo testo:
Here's what's in @BRIEF.md. Before we lock the spec, ask me 3 short
questions to refine it:
1. What's the one input I want the user to provide?
2. What's the magical moment for the user?
3. What are we deliberately NOT building (to keep scope tight)?
DO NOT generate any plans, docs, or code yet. Just ask me the questions
and wait for my answers.
🤖 Parla con l'AI e perfeziona il tuo piano
Non generare ancora documenti
Al termine della Spec Talk, l'agente NON deve aver generato alcun file. Se vedi product.md o altri nuovi file, puoi dire all'agente: "Interrompi: elimina tutti i documenti che hai appena creato. Siamo ancora nella fase di Spec Talk".
Suggerimenti
✅ Checkpoint: hai avuto una breve conversazione con Antigravity sulla tua idea di prodotto e ha compreso gli input e gli output. Non sono ancora stati generati file.
5. Genera 3 documenti di progettazione
Ora l'AI scrive tre piani, su carta, prima di qualsiasi codice. Eseguiamo tutte e tre le operazioni in un unico prompt utilizzando le tre competenze di design-doc in sequenza.
I tre documenti
File | Cosa contiene | Competenza utilizzata |
product.md | Chi è l'utente, qual è il problema da risolvere, quali funzionalità |
|
ui.md | Aspetto delle schermate, colori, caratteri, layout |
|
engineering.md | Stack tecnologico, struttura dei file, + sezione Strategia di test |
|
Passaggio 1: genera tutti e tre i documenti contemporaneamente
🤖 Passa a Gemini 3.1 Pro con Low Thinking (consigliato)
📝 Incolla questo prompt, che esegue tutte e tre le operazioni:
Apply all three design-doc skills in this order:
1. pm-design-doc from .agent/skills/skills-garden/design-doc-skills/pm-design-doc/
→ Generates product.md
2. ux-design-doc from .agent/skills/skills-garden/design-doc-skills/ux-design-doc/
→ Generates ui.md (based on the product.md you just created)
3. eng-design-doc from .agent/skills/skills-garden/design-doc-skills/eng-design-doc/
→ Generates engineering.md (based on product.md, ui.md, and @BRIEF.md)
→ MUST include a "Testing strategy" section with real content
(specific functions to unit-test, one integration test per major flow,
and what's deliberately NOT being tested)
Use the patterns in @reference/ as guidance for the engineering doc
(but vary if the brief justifies it).
Save all three files in the project root. After each one is saved,
briefly confirm what you saved before moving to the next.
When all three are done, give me a final summary listing the section
titles in each file.
Passaggio 2: verifica i file salvati
👉 Controlla l'elenco dei file. Ora dovresti vedere (oltre a ciò che era presente in precedenza):
codingjam-week-1/
├── product.md ← NEW
├── ui.md ← NEW
├── engineering.md ← NEW
├── BRIEF.md
├── reference/
└── .agent/
Passaggio 3: rivedi e itera
Sei tu a decidere. L'AI ha scritto il piano. Ora leggilo e richiedi le modifiche.
L'abitudine più importante
Quando vuoi apportare una modifica, modifica il DOC, non il codice. Il documento è la fonte attendibile.
🤖 Leggi e rivedi tutti e tre i documenti
👉 Apri ciascuno dei file (fai clic nell'elenco dei file), dall'alto verso il basso:
product.md: descrive quello che voglio?ui.md: le schermate e l'aspetto sono corretti?engineering.md: la strategia di test è sensata? Non devi capire la tecnologia, ma solo verificare che esista un piano.
🤖 Ora che i documenti sono pronti, passa ai passaggi successivi.
6. Implementa + Testa
La sezione più grande del codelab. L'AI prende i tre documenti e crea l'app: codice E test insieme, in una sola volta.Al termine di questa sezione, avrai un codebase funzionante che supera i propri test.
Perché codice e test insieme?
Il tuo engineering.md specifica già quali test devono esistere (la sezione Strategia di test). L'implementazione non è completa finché i test non vengono superati. Quindi, facciamo entrambe le cose in un'unica fase.
🤖 Passa a Gemini 3.1 Pro con High Thinking (consigliato)
Passaggio 1: chiedi all'AI di creare il codice E i test
📝 Incolla questo testo:
You're going to do two things in one shot.
PART 1 — IMPLEMENT THE APP CODE
- Build it according to @engineering.md (stack, file structure)
- Match the UI described in @ui.md
- Use the patterns in @reference/ as guidance for code style
- Backend: use Python with `uv` for dependency management
- If your chosen stack requires Node.js and it isn't installed on my
system, install it via Antigravity (use brew/winget/apt) — ask
permission first
- DO NOT start any dev servers — that's a later section
PART 2 — APPLY THE TEST-GATE SKILL
After the code is written, apply the test-driven-dev skill from
.agent/skills/skills-garden/eng-skills/test-driven-dev.md.
Use the "Testing strategy" section in @engineering.md as the test plan.
IMPORTANT: Mock the Gemini API calls in tests — use a stub that returns
fake response data. The real API key isn't set up yet, and tests should
be deterministic and free anyway (best practice).
The skill should:
1. Write the tests described in the Testing strategy
2. Run them (use pytest for Python, Vitest or Jest for JS)
3. If any fail, fix the CODE (not the tests) and re-run
4. Up to 3 retry attempts max
5. If still failing after 3 tries, STOP and tell me what's broken
When Antigravity asks permission to run commands (uv sync, uv pip
install, pytest, etc.), click Allow.
Report results when both parts are done.
🤖 Fai clic su Consenti nei popup (più volte)
Passaggio 2: leggi il report finale
Al termine, verifica:
- ✅ Esiste una cartella
backend/con codice - ✅ Esiste una cartella
frontend/con codice - ✅ Esiste una cartella
tests/con file di test - ✅ Il riepilogo indica "tutti i test superati" (non "non riuscito dopo 3 tentativi")
- ✅ L'agente NON ha avviato alcun server
Cosa succede se tutti e tre i tentativi di test non vanno a buon fine?
Raro ma possibile. In genere, significa che la strategia di test del documento tecnico non è realistica per ciò che è stato creato.
📝 Incolla questo testo:
The auto-fix loop hit the 3-try cap. Pull up @engineering.md and look
at the Testing strategy section. Is the strategy realistic for what
got built? Suggest updates to the doc so the tests align with reality.
Don't change the code yet — update the doc, then re-apply the
test-driven-dev skill.
Cosa succede se qualcosa non va?
👉 Se l'AI ha creato qualcosa che non corrisponde ai documenti, torna al documento e non chiedere all'AI di "correggere il codice" in modo isolato.
Esempio:
I see you built the chat as a popup, but @ui.md says it should be a
full page. Either update ui.md if a popup is actually better, OR
rebuild the chat as a full page to match the current ui.md.
Sempre: il documento è la fonte di riferimento.
✅ Checkpoint: il codice esiste, i test esistono, i test vengono superati. Pronto per configurare la chiave API.
7. Configurazione di Google Cloud + chiave API
Passaggio 1: ottieni la chiave API Gemini da AI Studio (1 minuto)
- Apri https://aistudio.google.com/app/apikey in una nuova scheda del browser.
- Accedi con lo stesso Account Google.
- Fai clic su "Crea chiave API" (in alto a destra).
- Si apre una finestra di dialogo con un menu a discesa dei progetti:
- Se hai già creato un progetto Google, puoi selezionarlo e fare clic su "Crea chiave API nel progetto esistente".
- Se NON è presente nell'elenco: fai clic su "Crea progetto".
- Copia la chiave API visualizzata. Inizia con
AIza..., circa 40 caratteri.
✏️ Incollalo in un posto sicuro: lo darai ad Antigravity in un secondo momento.
Passaggio 2: chiedi ad Antigravity di configurare .env (30 secondi)
Torna in Antigravity e apri la chat.
⚠️ STOP. LEGGI QUESTO PRIMA DI INCOLLARE.
Il prompt riportato di seguito contiene i segnaposto PASTE_YOUR_API_KEY_HERE e PASTE_YOUR_PROJECT_ID_HERE.
DEVI sostituirli con i valori reali del passaggio 1, altrimenti il file .env conterrà il testo letterale ⚠️ PASTE_... e la tua app non funzionerà.
Prima di fare clic su Invia, esamina il prompt e verifica di visualizzare:
GEMINI_API_KEY=AIzaSy...(inizia conAIzaSy, circa 40 caratteri)
Se continui a visualizzare
⚠️ PASTE_...
in qualsiasi punto del prompt, NON inviarlo ancora: sostituiscili prima.
📝 Prompt per incollare (sostituisci il
⚠️ PASTE_...
markers first!):
Apply the gemini-api-dev skill from .agent/skills/gemini-skills/skills/gemini-api-dev/.
(If that skill isn't found, fall back to .agent/skills/skills-garden/eng-skills/gemini-api.md)
Create a .env file in the backend folder with these settings:
- GEMINI_API_KEY= ⚠️ PASTE_YOUR_API_KEY_HERE
- Any other env vars the app needs based on @engineering.md
Also verify:
- .env is in .gitignore so the key never gets committed
- The backend code reads GEMINI_API_KEY at startup
- The Gemini SDK is initialized correctly (use google-genai for Python)
When Antigravity asks permission to install Python packages, click Allow.
When done, show me the .env contents with the KEY redacted (just first 6 chars + ...).
🤖 Previsto:l'agente crea .env, installa google-genai (fai clic su Consenti), conferma con la chiave oscurata:
✅ .env created at backend/.env
GEMINI_API_KEY=AIzaSy... (40 chars, redacted)
.env is already in .gitignore ✓
Backend reads GEMINI_API_KEY via os.getenv() ✓
Gemini client initialized ✓
8. Visualizza l'anteprima e verifica
Il codice viene compilato. I test vengono superati. Chiave API configurata. Ora apri l'app e fai clic.
Cosa rilevano gli esseri umani (che i test non rilevano)
Test Catch | Humans Catch |
Valori restituiti errati | Colori brutti |
Chiamate di funzione interrotte | Testo poco chiaro |
Importazioni mancanti | Pulsanti in posizioni strane |
Errori di conteggio | L'animazione è instabile |
Bug logici | Il genere non è quello giusto |
Passaggio 1: Chiedi ad Antigravity di avviare il server di sviluppo
🎯 MODELLO: il valore predefinito (Flash) va bene.
📝 Incolla questo testo:
Please start the dev server(s) so I can preview the app in my browser.
Tell me the URL when it's ready. When Antigravity asks permission to
run the server command, I'll click Allow.
🔔 Popup: uv run uvicorn main:app --reload (o simile) → Fai clic su Consenti
Passaggio 2: apri l'URL di anteprima
🤖 L'agente segnala:
Backend running at: http://localhost:8000
Frontend served at: http://localhost:8000 (backend serves it)
L'URL è in genere http://localhost:8000 o http://localhost:5173.
👉 Fai clic sull'URL nella chat o copialo e incollalo in una nuova scheda del browser.
Passaggio 3: esplora
Utilizzalo come farebbe un utente reale:
- Fai clic su ogni pulsante
- Digita le cose
- Passare il mouse sopra gli elementi
- Prova il flusso principale dall'inizio alla fine
Se tutto sembra a posto, vai al passaggio 9.7 (scrivi il file README). I passaggi 9.4-9.6 sono necessari solo se riscontri problemi.
Passaggio 4: scrivi un file README
Una volta che l'app funziona, bloccala:
📝 Incolla questo testo:
The app works! Please create a README.md in the project root that explains:
- What this app does (in plain English)
- How to install it on a new machine (uv sync, etc.)
- How to run the dev server(s)
- The 3 design docs (@product.md, @ui.md, @engineering.md) are the
source of truth — anyone can read them to understand the system
Save it as README.md.
🤖 Risultato previsto: README.md viene visualizzato nell'elenco dei file.
Perché il file README è importante
✅ Checkpoint: hai esplorato l'app, risolto eventuali problemi e salvato un file README.
9. 🎉 Hai rilasciato un MVP.
Ce l'hai fatta!
Cosa hai creato
- ✅ Un'app web basata sull'AI
- ✅ Tre documenti di progettazione (
product.md,ui.md,engineering.md) - ✅ Una suite di test reale che viene eseguita ogni volta che modifichi il codice
- ✅ Un
README.mdper poter tornare a questa attività in qualsiasi momento - ✅ Una connessione all'AI Gemini di Google
Sei passato dall'idea all'app funzionante senza scrivere una sola riga di codice. Incredibile.
Che cosa hai imparato
Skill | Perché è importante |
Specifica → Codice+Test → Verifica | Pianifica prima. Crea codice e test insieme. Fai clic su Ultimo. Sempre in questo ordine. |
Correggere il documento, non il codice | Quando qualcosa non funziona, modifica il piano e ricompila. Non applicare patch. |
Test come misura di sicurezza | Integrata nell'implementazione: l'AI rileva gli errori prima che tu debba farlo. |
Regola di regressione | Ogni bug trovato da un essere umano diventa un test. Il bug non può più ripresentarsi. |
Pivot basati sui documenti | Quando la direzione cambia, modifica il documento. L'AI si occupa del resto. |
Antigravity 3-layer flow | Inglese nella chat → l'agente sceglie il comando → tu approvi. |
Torni la prossima settimana?
- Scegli una riga diversa dalla tabella di 8 settimane
- Clona il repository della settimana tramite il pulsante "Clona repository" di Antigravity.
- Le skill vengono installate ex novo per ogni workspace (ambito del workspace = nessun stato residuo)
- Puoi riutilizzare lo stesso progetto Google Cloud
- Tutto il resto è lo stesso flusso di lavoro che hai appena imparato.
Passaggi successivi
- Pubblica il tuo progetto:pubblica il tuo progetto sul sito Coding Jam.
- Crea a casa: i tre documenti sono portatili. Aprili in qualsiasi strumento di AI e continua a creare
- Porta un amico:esegui l'accoppiamento con una persona nuova tramite questo codelab. Insegnare è il modo più veloce per imparare
Risorse
- Documentazione di Antigravity
- Documentazione sulle skill di Antigravity
- Visualizzazione conversazione Antigravity
- Skill ufficiali di Gemini (Google)
- Coding Jam Starter (tutte le 8 settimane)
- Skills Garden (le competenze che abbiamo utilizzato)
- Documentazione dell'API Gemini
- Documentazione di FastAPI