- Trasforma il feedback degli utenti in un piano concreto per testare e risolvere i bug usando un sistema ben organizzato.
- Usa il debug assistito dall'intelligenza artificiale e prova il modello "insegnami" per capire le correzioni.
- Scrivi dei test semplici per controllare che le correzioni funzionino e individuare eventuali problemi di regressione.
- Usa gli strumenti di sviluppo del browser per capire e risolvere i problemi.
- Frontend: un'app React con tutte le schermate, la navigazione e le funzioni AI
- Backend sicuro: chiave API protetta con GitHub Secrets, non visibile nel codice
- Gli studenti hanno finito la parte MVP, i wireframe e hanno i commenti dei test degli utenti.
Nelle lezioni precedenti hai usato GitHub Codespaces e Copilot per programmare il tuo Founder's Toolkit. Hai detto cosa volevi, Copilot ha creato il codice e hai continuato a provare finché non ha funzionato. Forse hai anche usato Copilot per aiutarti con un po' di debug assistito dall'intelligenza artificiale. Questo approccio ti ha insegnato le basi. In Tech Foundations hai provato a usare Google AI Studio Build Mode come approccio alternativo.
Il Founder's Toolkit ti ha aiutato a imparare e a conservare le tue ricerche. Ora stai creando il tuo MVP per gli utenti reali. La tua ricerca va avanti, ma il codice del toolkit rimane indietro.
Costruire il tuo front-end
In MVP e prototipi, hai creato un prototipo che può avere diversi livelli di fedeltà. Potrebbe essere uno schizzo su carta, dei post-it o dei wireframe di base in strumenti come Figma o Miro. L'hai testato con utenti reali e hai raccolto feedback sul flusso principale e sulla proposta di valore.
Ora sei pronto per trasformarlo in codice funzionante, così potrai verificare se l'esperienza reale mantiene quella promessa.
Dato che il tuo prototipo è una rappresentazione visiva, devi trasformare gli elementi visivi in descrizioni che gli strumenti di intelligenza artificiale possano capire (come hai già imparato).
Scegliere uno strumento prototipo
Da quando il termine "vibe-coding" è diventato famoso l'anno scorso (2025), sono spuntate un sacco di nuove piattaforme. Questi strumenti permettono a chiunque di passare dalla descrizione di un'idea all'app pronta in pochi minuti.
Ha superato i 100 milioni di dollari di entrate annuali in soli otto mesi, diventando l'azienda di software che ci è arrivata più in fretta.
Le entrate di Replit sono aumentate di 10 volte quando hanno lanciato il loro agente di codifica AI (simile al Copilot di GitHub).
è un altro editor di codice assistito dall'intelligenza artificiale molto usato che puoi usare sul tuo computer.
ha più di 7 milioni di sviluppatori che lo usano per creare app
Tutte queste piattaforme sono specializzate in diversi settori e sono ottime opzioni. Continueremo a usare Github codespaces e Copilot per questi motivi:
- Lo sai già.
- È gratis. A differenza di Lovable (20-100 dollari al mese) o Cursor (20 dollari al mese), Codespaces è (quasi) gratis con un sacco di crediti.
- Pubblicare le modifiche su Github è semplicissimo
- Hai il controllo sul codice e sull'architettura della tua app
Puoi tranquillamente usare un'altra piattaforma. Se stai seguendo le attività di questa lezione, potresti dover fare qualche modifica per adattarle alla piattaforma che stai usando.
L'approccio iterativo con la codifica Vibe
Quando si fa il vibe-coding, bisogna resistere alla tentazione di descrivere tutto in una volta. Anche se piattaforme come Google AI Studio hanno modelli potenti come Gemini 3 Pro, che possono ragionare e suddividere lunghe istruzioni in passaggi strutturati, c'è una grande possibilità che l'IA decida comunque di andare in una direzione diversa. Inoltre, se chiedi all'LLM di creare l'intera app in un unico passaggio, è probabile che qualcosa non funzioni esattamente come desideri. Può essere difficile individuare dove si trova il problema quando si deve eseguire il debug dell'intera app. I programmatori generalmente lavorano sulle app in blocchi: aggiungono una funzionalità, la testano e poi passano alla funzionalità successiva. Lavorare con l'assistenza dell'IA non dovrebbe essere diverso.
Ti consigliamo di procedere passo dopo passo, ad esempio:
- Prima crea la struttura dell'interfaccia utente, poi lavora schermata per schermata e infine passa alla navigazione.
- Prova le schermate e il flusso prima di aggiungere funzioni più avanzate. Riesci a navigare nell'app? Se no, allora fai un po' di debug.
- Aggiungi la tua funzione principale, che probabilmente sarà l'integrazione dell'intelligenza artificiale.
- Provalo. La funzione funziona? Se no, dai un'occhiata al debug.
- Ripeti, aggiungendo altre funzioni una alla volta.
Questo modo di fare ti aiuta a vedere i problemi appena arrivano e rende più facile risolvere i bug. Se qualcosa va storto, sai subito quale modifica l'ha causato. Con i prompt lunghi, è difficile capire dove si è verificato il bug.
Oltre ad aggiungere funzionalità e testarle una alla volta, pubblicheremo spesso le nostre modifiche sul nostro repository Github. Non solo questo archivio conserva gli aggiornamenti in modo sicuro, ma mostra anche l'avanzamento del progetto. Questo può essere utile per i membri del team e i collaboratori, ma anche per gli assistenti AI.
Il vantaggio del "contesto AI"
Una cosa che molti dimenticano: quando usi strumenti di intelligenza artificiale (come Gemini in AI Studio o Copilot), spesso l'IA "guarda" la cronologia Git per capire come si è evoluto il progetto.
- Se hai tre push distinti, l'IA può capire: "Oh, siamo passati dall'HTML di base a una struttura di componenti basata su React nel secondo commit".
- Se fai un unico grande push, l'IA vede solo un muro di codice e tende a suggerire modifiche che potrebbero non andare d'accordo con quello che volevi fare all'inizio.
Per questo motivo, pubblicheremo le nostre modifiche su Github man mano che completiamo ogni fase o parte del lavoro, invece di sviluppare l'intera app e pubblicare le modifiche solo alla fine.
ATTIVITÀ 1
Crea il tuo frontend in Github Codespaces
Tempo stimato: 30 minuti
In questa attività, inizierai a trasformare il tuo prototipo in un'applicazione funzionante usando Github Codespace e Copilot.
1. Pensa a cosa ti serve davvero (le cose che non puoi fare a meno di avere)
- Apri il tuo documento MVP dalla lezione MVP e prototipi.
- Dai un'occhiata ai tuoi COLONNE INDISPENSABILI colonna
- Scegli UNO funzionalità da sviluppare per prima. Chiediti:
- Quale caratteristica rappresenta il valore principale?
- A quali caratteristiche i miei utenti hanno reagito meglio?
2. Prepara le immagini del tuo prototipo per il caricamento
Trova la schermata nel tuo prototipo (di quella lezione) che mostra questa funzione. Caricherai questa immagine su AI Studio E descriverai quello che vuoi. Questa combinazione di mostrare e raccontare dà all'IA la possibilità migliore di generare quello che ti serve.
- Prepara i tuoi modelli (wireframe digitali o immagini):
- Se il tuo prototipo è su carta, fai una foto chiara di quello schermo.
- Se il tuo prototipo è digitale (Figma, Canva, ecc.), esporta o fai uno screenshot di quella schermata.
- Metti l'immagine in un posto dove puoi trovarla facilmente.
- Prepara la descrizione della tua funzione.
Anche se l'IA può vedere il tuo prototipo, è meglio spiegare prima cosa vuoi. Guarda il tuo prototipo e prendi nota:- Qual è il flusso degli utenti?
- Cosa fa prima l'utente?
- Cosa succede quando fanno qualcosa?
- Cosa non si vede nel tuo prototipo ma è importante?
- Preferenze per i colori o il marchio
- Requisiti per la compatibilità con i dispositivi mobili
- Qualsiasi cosa che succede "dietro le quinte"
- Qual è il flusso degli utenti?
- Scrivi qualche frase per spiegare questi due punti. Userai sia le simulazioni che questa descrizione scritta nei prossimi passaggi.
Ecco come appare la nostra immagine simulata:
3. Dai un'occhiata ai commenti dei tuoi utenti
Prima di iniziare a costruire, dai un'occhiata ai commenti che hai ricevuto dai test sul prototipo. Questo dovrebbe darti un'idea di cosa devi aggiornare rispetto ai tuoi modelli originali.
Il tuo prototipo codificato dovrebbe tenere conto dei commenti critici che hai ricevuto dagli utenti. Non dovrebbe limitarsi a ricostruire quello che hai mostrato loro e che non ha funzionato.
4. Crea il tuo repository su GitHub e apri Codespace.
- Accedi a github.com.
- Clicca sul Nuovo pulsante per creare un nuovo repository.
- Dagli un nome che vada bene per la tua app.
- Imposta la visibilità su privato.
- Nessun modello.
- Aggiungi il file Readme.
- Aggiungi .gitignore, scegli Node.
- Aggiungi licenza, scegli la licenza MIT.
- Una volta creato, puoi aggiungere una descrizione al tuo file Readme, se vuoi. Puoi anche aspettare e compilarlo più tardi.
- Crea un nuovo ramo cliccando su principale, scegli Visualizza tutti i rami, poi clicca su Nuovo ramo. Dagli un nome appropriato.
- Clicca sul nome del ramo per assicurarti di essere in quel ramo, poi clicca su Codice e poi su Crea spazio codice sul tuo nuovo ramo.
- Aspetta che il codespace si carichi.
5. Chiedi a Copilot di iniziare a creare la tua shell dell'interfaccia utente.
Invece di chiedere tutto in una volta, inizia SOLO con la struttura visiva.
- Per aggiungere un'immagine del tuo wireframe o uno schizzo delle tue schermate:
- Trascina l'immagine nel file manager di codespaces per aggiungerla come file al tuo progetto.
- Nella chat, clicca sulla graffetta per aggiungere un allegato.
- Dovresti vedere un pulsante Incolla. Cliccaci sopra.
- A questo punto dovresti poter scegliere i file dal tuo file manager. Clicca sull'immagine che vuoi allegare.
- Inserisci un prompt nella stessa finestra di chat e sostituiscilo con i tuoi valori MVP. Tieni presente che Copilot può creare l'interfaccia utente solo con l'immagine, ma più dettagli fornisci, migliore sarà il risultato.
Ecco un modello di prompt qui a sinistra, seguito da un esempio che utilizza la nostra app TutorMatch.
Il tuo obiettivo è aiutarmi a creare un'app web React per dispositivi mobili chiamata [nome della tua app] basata sull'immagine che ho allegato.
Per ora crea SOLO la shell dell'interfaccia utente, quindi pensa solo alla struttura visiva senza aggiungere ancora nessuna funzionalità.
– [Dai un'occhiata all'intestazione/titolo]
– [Spiega i campi da compilare o gli elementi del modulo]
– [Spiega i pulsanti]
– [Dici dove si vedranno i risultati (per ora è solo un segnaposto)]
Combinazione di colori: [descrivere: blu professionali, arancioni caldi, ecc.]
Layout: [colonna singola, due colonne, ecc.]
Per ora, quando l'utente clicca sul pulsante, basta mostrare un testo provvisorio tipo "I risultati appariranno qui". Aggiungeremo la vera funzionalità nel prossimo passaggio.
NON AGGIUNGERE ALCUNA FUNZIONALITÀ DI INTELLIGENZA ARTIFICIALE IN QUESTO MOMENTO!
Aggiungeremo funzionalità reali nel prossimo passaggio.
Il tuo obiettivo è aiutarmi a creare un'app web React per dispositivi mobili chiamata TutorMatch, basata sull'immagine che ho allegato.
Per ora crea SOLO la shell dell'interfaccia utente, quindi pensa solo alla struttura visiva senza aggiungere ancora nessuna funzionalità.
– Un'intestazione che dice "TutorMatch – Ottieni consigli personalizzati dai tutor"
– Uno spazio dove gli studenti possono scrivere su quale materia stanno avendo difficoltà
– Un pulsante con scritto "Ottieni consigli"
– Una sezione dei risultati sotto il pulsante (per ora è solo un segnaposto)
Combinazione di colori: blu e verdi rilassanti
Layout: colonna singola, centrata
Per ora, quando l'utente clicca sul pulsante, basta mostrare un testo provvisorio che dice "I consigli dell'IA appariranno qui".
NON AGGIUNGERE ALCUNA FUNZIONALITÀ DI INTELLIGENZA ARTIFICIALE IN QUESTO MOMENTO!
Aggiungeremo funzionalità reali nel prossimo passaggio.
L'intelligenza artificiale vede sia il tuo prototipo visivo che la tua descrizione scritta, così capisce perfettamente cosa vuoi creare.
6. Prova e migliora il codice come serve
Una volta che Copilot ha creato il codice, puoi eseguirlo. Copilot dovrebbe chiederti di farlo, ma nella finestra del terminale in codespaces dovrai digitare:
- npm install ( per mettere tutte le dipendenze in package.json)
- npm run dev (per far girare l'app in una finestra del browser)
Se qualcosa non va, puoi dire all'IA quali modifiche o correzioni servono, tipo:
- Ingrandisci il testo dell'intestazione
- Cambia il colore del pulsante in verde
- Aumenta lo spazio tra questi campi
Ricorda che ogni messaggio dirà a Copilot di sistemare il codice, e c'è la possibilità che l'IA cambi anche altre cose che non hai specificato con precisione. Quindi è importante essere sempre precisi. Questa è la parte conversazionale del vibe-coding.
Nel nostro caso, abbiamo chiesto all'IA di aggiungere dei segnaposto. Come puoi vedere, dopo aver inserito "Algebra", nei risultati è stato aggiunto "Raccomandazioni IA" come segnaposto, perché glielo abbiamo chiesto noi.
Hai qualche idea su come migliorare le istruzioni da dare al modello LLM per fare le correzioni di cui sopra?
7. Preparare e confermare le modifiche nel repository
Usando il controllo del codice sorgente Codespace o git nel terminale, prepara, conferma e invia le tue modifiche al ramo del tuo repository GitHub.
Il controllo del codice sorgente rende automatiche le operazioni per il tuo Se vuoi digitare tu stesso i comandi git, ecco cosa fare.
git status
git add .
git commit -m "Cosa ho cambiato"
git push -u origin nome-del-tuo-ramo
Questo salverà i tuoi file iniziali in modo sicuro su Github e li segnerà come primo commit. È utile per vedere le modifiche fatte nel progetto.
8. Aggiungi interattività di base (ancora senza IA)
Una volta che la tua interfaccia utente sembra a posto, aggiungi la parte successiva: interazione di base con l'utente SENZA ancora AI o API. Prova con dati provvisori per assicurarti che il flusso di interazione funzioni prima di aggiungere l'AI.
Se qualcosa va storto dopo, sai che è un problema dell'IA, non dell'interfaccia utente.
Nella chat, spiega il livello successivo
Per esempio, se stai creando un'app per trovare tutor con wireframe caricati:
Ora aggiungi un po' di interattività di base:
Quando l'utente digita nel campo di immissione e clicca sul pulsante:
- Cancella tutti i risultati precedenti
- Mostra un messaggio di caricamento: "Analizzo le tue esigenze..."
- Dopo 1 secondo, mostra dei dati fittizi tipo:
– Cerca un tutor che sappia bene la materia
– Trova qualcuno che usi metodi di insegnamento visivi
– Cerca un tutor che abbia esperienza con il tuo modo di studiare
Questo serve solo per testare il flusso di interazione.
NON AGGIUNGERE ALCUNA CHIAMATA API O ALCUNA INTEGRAZIONE AI EFFETTIVA.
9. Salva i tuoi progressi su Github
Una volta che sei contento dell'interfaccia utente e dell'interazione per quella prima schermata/funzionalità, prepara, conferma e invia di nuovo le modifiche al tuo ramo Github.
Come uscire dalla situazione di stallo:
- Se Copilot non capisce cosa vuoi, prova a essere più chiaro su cosa ti serve e su come dovrebbe essere il layout, tipo:
- Se i colori non vanno bene, specifica quelli giusti: "Usa #4A90A4 per l'intestazione".
- Se l'anteprima è vuota, prova ad aggiornare la pagina o ad aprire una nuova sessione.
- Se trovi degli errori, dì all'IA: "Ho trovato un errore. Per favore, spiegami cosa c'è che non va e sistemalo".
Spiegazione del codice React
Dai un'occhiata ai file creati e alla struttura del codice in Codespace. Abbiamo dato un'occhiata veloce ai file React quando abbiamo parlato degli stack tecnologici. Ora vediamo un po' più da vicino.
Copilot dovrebbe aver creato il codice React, che usa una struttura a componenti dove la tua app è divisa in parti che puoi riutilizzare.
Ecco il trucco: non devi capire ogni riga di React per creare il tuo MVP.
Pensaci come se fosse guidare una macchina: non devi capire come funziona il motore per arrivare dove vuoi. Concentrati su cosa vuoi che faccia l'IA e lascia che sia lei a occuparsi dei dettagli di React. Quando devi fare delle modifiche, usa un linguaggio semplice per dire all'IA cosa cambiare ("ingrandisci questo pulsante", "cambia il colore in blu") invece di modificare direttamente il codice. Se sei curioso e vuoi imparare React come si deve, va benissimo, ma aspetta che il tuo MVP sia pronto e che tu abbia verificato la tua idea con utenti reali. Per ora, il tuo obiettivo è creare qualcosa di testabile velocemente, non diventare un esperto di React.
Probabilmente Copilot ha creato una struttura di base per un MVP. Nel nostro esempio, ha creato questi file:
src/ – Cartella con i file principali di React
App.jsx– Componente principale dell'app (la maggior parte dell'interfaccia utente)
main.jsx – Punto di accesso React . Vedrai che index.html carica questo script.
index.css – Stili globali
index.html – La pagina unica su cui gira la tua app
vite.config.js – file di configurazione del server build/dev
package.json – Pensa a questo come alla lista delle cose che ti servono. Elenca tutte le librerie che la tua app deve avere per funzionare (come react, express o lucide-react). Se questo file manca, l'app non saprà come partire.
.gitignore – Questa è la schermata della privacy. Dice a GitHub quali file "ignorare" (come il tuo file .env che contiene le tue chiavi API). Questo è fondamentale per la sicurezza.
node_modules/ – Questa cartella ha il codice vero e proprio per tutte le librerie che hai messo nel tuo package.json. Di solito è enorme, quindi non caricarla mai su GitHub.
Al momento è una struttura semplice e lineare. Man mano che la tua app diventa più complessa, puoi renderla più organizzata usando le funzionalità di React.
Ecco una panoramica della struttura di file e cartelle di un'app React completa.
componenti/ – Elementi riutilizzabili per la creazione di interfacce utente.
- Pulsanti, schede, schede, finestre modali, ecc.
- Ogni file di solito rappresenta un'idea visiva.
pagine/ o views/ – Schermate o sezioni dell'app. Le pagine organizzano le funzionalità dell'app; i componenti le costruiscono.
server/ oppure api/ – Dove risiedono le API esterne, dove la tua app comunica con il mondo esterno.
- Chiamate API Gemini
- Caricamenti Supabase
- Inferenza Hugging Face
utils/ Funzioni di supporto.
- Formattazione del testo
- Analisi delle risposte
- Logica riutilizzabile
Faremo in modo che Copilot aggiunga queste cartelle quando glielo chiediamo, dato che stiamo rendendo la nostra app un po' più complicata.
ATTIVITÀ 2
Aggiungi tutte le schermate delle app
Tempo stimato: 30 minuti
1. Aggiungi un secondo schermo, prova e ripeti
Se la tua app ha più di una schermata, puoi ripetere questi passaggi finché non hai creato tutte le schermate, concentrandoti solo sull'interfaccia utente per ora.
Inizia con una schermata in più e aggiungi questo pezzo importante al tuo prompt:
Aggiungi un secondo schermo, [Nome schermo].
Crea una cartella "pages" e aggiungi un file .jsx per ogni schermata.
Aggiungi anche una cartella dei componenti per l'interfaccia utente condivisa (barra di navigazione, pulsanti, schede).
Questa è la struttura standard delle app React. Le cartella contengono il codice per ogni schermata dell'app. La cartella componenti contengono blocchi riutilizzabili per i componenti dell'interfaccia utente.
Una volta che Copilot ha creato il codice, controlla che abbia fatto le cartelle e aggiunto i file giusti. Dai un'occhiata al codice per vedere se riesci a capire cosa sta facendo.
Assicurati di provare sia la nuova schermata che come ogni schermata si combina con l'altra.
2. Aggiungi le schermate che mancano, prova e ripeti
Segui gli stessi passaggi per aggiungere le schermate rimanenti. Chiedi a Copilot di creare prima l'interfaccia utente, poi aggiungi le funzioni di base.
Controlla che Copilot stia aggiungendo un nuovo file .jsx nella cartella delle tue pagine. Potrebbe essere necessario ricordarglielo. Ricordagli anche di aggiungere componenti riutilizzabili nella cartella dei componenti.
Prova ogni nuova schermata man mano che la aggiungi.
3. Aggiungi la navigazione di base (ancora senza IA)
Una volta che l'interfaccia utente ti sembra a posto, puoi iniziare ad aggiungere le interazioni che potrebbero mancare, come la navigazione tra le pagine, i messaggi di conferma e altro. Questo è super importante se la tua app ha diverse schermate. È probabile che Copilot abbia già aggiunto alcune interazioni perché cerca di anticipare le tue esigenze, quindi assicurati di controllare prima cosa manca, cosa può essere migliorato e poi continua a lavorarci.
4. Prova l'app per bene
Hai già provato ogni modifica un po' alla volta e l'hai ripetuta, ma è sempre meglio fare un altro giro per assicurarti che tutte le schermate, i pulsanti e la navigazione funzionino bene.
Per testare bene la tua app, ti consigliamo di usarla come farebbe un utente.
Ecco una lista di controllo di esempio che potrebbe essere utile:
- Ci vuole una schermata iniziale e si carica bene?
- Riesci a inserire testo o numeri nel modo giusto?
- Posso mandare un modulo vuoto? Se sì, valuta di aggiungere dei messaggi di errore.
- Riesci a passare da una schermata all'altra?
5. Salva le modifiche
Quando sei contento dell'interfaccia utente e delle funzioni di base, prepara, conferma e invia le modifiche al ramo del tuo repository.
Integrazione dell'intelligenza artificiale
Ora hai un'app funzionante con schermate e navigazione, ma ancora senza IA. Nel Founder's Toolkit hai creato un Feedback Analyzer che ha mandato i dati degli stakeholder a Gemini e ha mostrato le informazioni raccolte. Hai anche imparato a usare l'IA predittiva. Ora userai quelle stesse competenze per il tuo MVP.
In entrambi i casi, sia per l'IA generativa che per quella predittiva, il principio è lo stesso: l'IA è un livello che si aggiunge alle funzionalità già esistenti. La tua app dovrebbe funzionare (navigazione, visualizzazione delle schermate) prima di aggiungere l'IA. Questo rende il debug molto più facile e, se qualcosa non funziona dopo aver aggiunto l'IA, sai che il problema è proprio l'integrazione dell'IA.
Quale LLM?
Fuori da AI Studio, l'API Gemini non è più gratis senza registrarsi con una carta di credito. Se puoi, registrati, ma imposta degli avvisi per quando raggiungi le quote, così non ti ritrovi con costi di sviluppo troppo alti.
Per questo motivo, dobbiamo cercare delle alternative.
Ci sono diverse API LLM gratuite che funzionano bene per il tuo MVP. Useremo Groq nell'attività qui sotto. Puoi registrarti sul loro sito web senza carta di credito e ti danno un bel numero di richieste giornaliere.
Ecco altre API gratuite che puoi provare per il tuo MVP.
Fornitore
Registrazione
Il miglior modello di
(a febbraio 2026)
Protocollo
Groq
Email (senza CC)
llama-3.3-70b-versatile
SDK OpenAI
GitHub
Usa l'account GitHub
gpt-4o-mini
SDK Azure/OpenAI
OpenRouter
Email (senza CC)
google/gemma-2-9b-it:gratis
SDK OpenAI
Faccia abbracciata
Email (senza CC)
DeepSeek-R1-Distill-Llama-8B
API di inferenza Hugging Face
ATTIVITÀ 3
Aggiungi funzione AI
Tempo stimato: 30 minuti
In questa attività, aggiungerai funzionalità di intelligenza artificiale al tuo MVP usando Groq. La maggior parte degli MVP può sfruttare le funzionalità generative dell'intelligenza artificiale come la generazione di testo, l'analisi, la sintesi o le risposte conversazionali.
Se il tuo MVP ha bisogno di classificazione o previsione (analisi del sentiment, categorizzazione, ecc.), il modello di integrazione è lo stesso. Devi aggiungere un'API.
1. Decidi come funzionerà la tua API
Prima di scrivere qualsiasi prompt, chiarisci bene cosa dovrebbe fare la tua API. Nella lezione sul flusso di lavoro su GitHub hai imparato che istruzioni vaghe portano a risultati vaghi. Lo stesso vale anche qui.
Visto che molte app di squadra includono una chiamata all’API LLM, ecco un modello per chiarire una funzionalità LLM. Se la tua app usa un modello di IA diverso, dovrai inserire parametri diversi. Aggiorna l’elenco seguente in base al tuo MVP. Questo ti aiuterà a compilare il prompt al punto 4.
La mia specializzazione LLM:
- Cosa devono fare gli utenti: [ cosa devono inserire gli utenti]
- Cosa dovrebbe fare l'IA: [generare, riassumere, analizzare, consigliare, chattare]
- Cosa vedono gli utenti: [ risultato]
- Stile e tono dei contenuti: [ amichevole, educativo, breve, dettagliato?]
- Temperatura:
- Bassa temperatura (0,1-0,3): risposte costanti e prevedibili
- Alta temperatura (0,7-1,0): risposte più varie e creative
- Lunghezza dell'output: ricorda che i token di output costano, quindi rispondere in modo breve ti aiuterà a tenere bassi i costi dell'API AI.
- Esempio di interazione:
- L'utente inserisce: [esempio di input]
- Risposte dell'IA: [esempio di output]
Scrivere una coppia input/output concreta ti fa riflettere su cosa sia davvero "buono" per la tua app.
2. Registrati su Groq e prendi una chiave API
- Vai su groq.com e registrati.
- Clicca su Chiavi API e poi su Crea chiave API. Dagli un nome che ti sembra giusto, poi copia la chiave API e mettila al sicuro da qualche parte.
3. Aggiungi una chiamata API con l'aiuto di Copilot
- Chiedi a Copilot di aggiungere l'integrazione API oppure chiedi a un altro LLM di creare il codice che puoi copiare e incollare nel tuo spazio di lavoro.
Ecco un modello che puoi usare e personalizzare con le funzionalità/API della tua app. Tieni presente che abbiamo bisogno di un server backend per le chiamate API.
A sinistra c'è un modello che puoi usare e personalizzare con le funzionalità/API della tua app. Tieni presente che serve un server backend per le chiamate API.
A destra c'è un esempio che usa il modello per la nostra app TutorMatch.
Adesso, quando l'utente fa X, l'app mostra dei dati provvisori. Devi sostituirli con una vera chiamata API AI.
Quando clicchi sul pulsante:
- Prendi il testo che l'utente ha scritto
- Mandalo al [servizio AI] con questa istruzione: "xxx"
- Sostituisci i dati provvisori che ci sono adesso e mostra la risposta dell'IA nell'area dei risultati.
Tieni il messaggio di caricamento mentre aspetti la risposta dell'IA.
Stile e tono dei contenuti:
Stile: [stile dei contenuti tipo professionale?]
Tono: [rispettoso, amichevole?]
Lunghezza [meno di 200 parole]
Requisiti tecnici:
Backend:
– Server Node.js + Express
– Percorso API POST /api/analyze che chiama l'API.
– Usa la variabile d'ambiente dal file .env
Interfaccia utente:
– Dovrebbe chiamare il percorso backend
– mostra il risultato nell'interfaccia utente
– gestire caricamenti/errori.
Adesso, quando premi il pulsante, l'app mostra dei dati provvisori. Devi sostituirli con una vera chiamata API AI.
Quando l'utente clicca su "Ottieni consigli":
- Prendi il testo dalla descrizione dell'oggetto inserita
- Mandalo a Groq con queste istruzioni: "In base a quello che questo studente sta trovando difficile, suggerisci che TIPO di tutor dovrebbe cercare. Dai 3 caratteristiche o abilità specifiche che il tutor ideale dovrebbe avere. Concentrati sulle qualifiche del tutor, non sui nomi reali dei tutor". Rispondi in modo utile e incoraggiante. Le risposte dovrebbero essere 3 punti elenco, ciascuno con 2-3 frasi che descrivono le caratteristiche del tutor da cercare.
- Mostra la risposta dell'IA nell'area dei risultati (sostituisci i suggerimenti del segnaposto)
Tieni il messaggio "Analisi delle tue esigenze in corso..." mentre aspetti la risposta dell'IA.
Requisiti tecnici:
Backend:
– Server Node.js + Express
– Percorso API POST /api/analyze che chiama l'API.
– Usa process.env.API_KEY.
Interfaccia utente:
– Dovrebbe chiamare il percorso backend
– mostra il risultato nell'interfaccia utente
– gestire caricamenti/errori
4. Aggiungi la chiave API al file .env
Copilot dovrebbe indicarti di aggiungere la tua chiave API al file file .env , che dovrebbe anche creare. Se non lo fa, crea il file .env tu stesso nel File Manager, nella cartella server o api (a seconda di quale cartella ha creato Copilot per il backend). Assicurati di NON aggiungerlo alla cartella principale .env , perché non è sicuro (e il tuo backend non può vederla lì).
Aggiungi questa riga al tuo server/.env :
API_KEY=la tua chiave API
5. Prova con input reali degli utenti
Una volta che Copilot ha finito di scrivere il codice, segui le istruzioni di installazione. Dovrebbe aggiungere i pacchetti necessari al file package.json . Per testare:
- Nella finestra del terminale, digita:
npm run dev
Questo avvia l'esecuzione dell'app in una nuova finestra del browser.
- Devi anche avviare il server backend. Nella finestra del terminale, clicca sull'icona + e apri una seconda finestra del terminale.
- Digita npm run dev nella seconda finestra del terminale per avviare il server backend. Questo verrà eseguito in una seconda finestra del browser.
- Vai alla finestra del browser che ha l'app aperta.
- Inserisci una query utente (come quella che scriverebbe un utente reale).
- Clicca sul pulsante di azione.
- Controlla che appaia il messaggio di caricamento.
- Aspetta la risposta dell'IA.
- Vedi se ricevi una risposta. Controlla cosa ti viene restituito e verifica che soddisfi le tue esigenze.
- Se ricevi un messaggio di errore, risolvi il problema con l'aiuto di Copilot per individuare l'errore e correggerlo. Ecco alcuni errori comuni che si verificano quando si aggiunge una chiamata all'API LLM:
- Chiave API mancante/non valida – Nome variabile ambiente sbagliato o chiave non caricata
- Errori CORS – Chiamare l'API direttamente dal frontend invece che dal backend
- Nome del modello sbagliato: errore di battitura o modello non supportato per quell'API.
- Raggiunto il limite di velocità – Troppe richieste troppo in fretta
- Richiesta non corretta – Nomi dei parametri o struttura sbagliati
- Il server non funziona: il frontend va bene, ma il backend non parte.
Elenco di controllo per il debug veloce:
- Controlla la console del terminale del server backend per vedere se ci sono messaggi di errore.
- Controlla la scheda "Rete" negli strumenti di sviluppo per il frontend (app vera e propria) per vedere la richiesta/risposta.
- Metti la chiamata API in un try-catch e registra l'errore completo.
6. Salva le modifiche
Quando sei sicuro che l'API AI (o un'altra) funzioni e mandi le risposte giuste, prepara e salva le modifiche nel ramo del tuo repository.
Come impostare il prompt dell'intelligenza artificiale
La maggior parte delle aziende che si occupano di intelligenza artificiale (OpenAI, Anthropic, Mistral, Groq) usa questo formato per i prompt:
messages: [{role, content}]
Separando il messaggio standard dal contenuto specifico dell'utente (nel nostro caso, la materia per cui ha bisogno di aiuto), puoi risparmiare sull'uso dei token, il che alla fine ti fa risparmiare sui costi dell'API.
Impostare un ruolo di sistema fa sì che la tua IA risponda sempre allo stesso modo, così gli utenti sanno cosa aspettarsi dalla tua app. Senza questo, le risposte potrebbero cambiare in modo imprevedibile da una sessione all'altra.
Capire le istruzioni del sistema e i costi dei token:
Quando fai una chiamata API a Groq, puoi inviare due ruoli:
- Sistema: decide COME dovrebbe comportarsi l'intelligenza artificiale.
- Utente – La domanda o l'input vero e proprio
Entrambi vengono inviati ad OGNI richiesta.
Groq tratta le istruzioni di sistema esattamente come i comandi dell'utente: vengono considerati come token di input.
- Richiesta del sistema: Ogni parola nelle istruzioni del sistema viene tokenizzata e aggiunta alla "fattura" di input.
- Richiesta utente: Aggiunto al totale.
- Calcolo: Totale token immessi = (token di sistema) + (token utente) + (token cronologia chat).
Groq ha appena lanciato Automatic Prompt Caching (da fine 2025/inizio 2026).
Se ci sono più richieste che iniziano con lo stesso messaggio di sistema, Groq "memorizza" quella parte del messaggio.
- Sul livello a pagamento, i token memorizzati nella cache costano spesso il 50% in meno.
- Sul livello gratuito, i token memorizzati nella cache non contano per i limiti di utilizzo. Quindi, se usi un prompt di sistema lungo e complesso, solo la domanda unica dell'utente "usa" la tua quota gratuita limitata.
Proteggi le tue chiavi API
Finora hai fatto in modo che le tue chiavi API siano al sicuro salvandole nel file file .env del tuo progetto. Quel file file .env è salvato sul tuo computer e non fa parte del tuo repository Github. È fatto apposta ed è una buona misura di sicurezza.
Comunque, .env funziona nel tuo ambiente di sviluppo locale, ma non funzionerà quando lo distribuirai. Oppure, se altri membri del team stanno lavorando al progetto su un ramo separato, non hanno accesso alla tua chiave o al tuo file .env (a meno che tu non la condivida in qualche altro modo).
GitHub Secrets risolve questo problema di condivisione salvando i valori sensibili separatamente dal codice. La chiave è criptata e si carica solo quando si esegue l'app in Codespaces. Il codice può usare la chiave senza mai contenerla. Chiunque acceda al tuo repository avrà accesso alla chiave, anche se non potrà mai visualizzarla, poiché è crittografata. Finché mantieni privato il tuo repository e solo i membri del team hanno accesso, la tua chiave può essere utilizzata dal tuo team, ma non dal mondo esterno (almeno per ora)! Imparerai di più su dove memorizzare le tue chiavi API quando arriverai alla fase di distribuzione della tua app. Dipenderà dalla tua piattaforma di distribuzione.
Ecco un paio di motivi per usare GitHub Secrets:
- Le chiavi non compaiono mai nei tuoi file di codice o nella cronologia dei commit.
- I membri del team possono fare il deploy senza vedere i valori delle chiavi reali.
- Puoi cambiare le chiavi senza cambiare il codice.
- Necessario per le distribuzioni automatiche (GitHub Actions, piattaforme cloud)
Anche se potrebbe sembrare eccessivo per il tuo MVP, è una buona idea metterlo in pratica. Inoltre, renderà lo sviluppo e il debug molto più veloci.
Come funzionano i segreti GitHub in Codespaces:
Quando apri un Codespace per questo repository, GitHub carica automaticamente i tuoi segreti come variabili d'ambiente. Non hai bisogno di un file file .env . Il segreto apparirà nel tuo codice lato server. Comunque, dato che hai creato un file .env , continua a usarlo mentre sviluppi la tua app. Codespace userà la chiave segreta di Codespace, ma cercherà anche .env se la chiave segreta non c'è. Così, se mai dovessi decidere di lavorare al tuo progetto in locale (non in Codespaces), funzionerà comunque.
Per il tuo progetto, userai due livelli di sicurezza:
- Segreti di GitHub – Tieni le chiavi fuori dai tuoi file di codice
- Limiti API – Decidi cosa possono fare le chiavi e dove possono essere usate
Li configurerai entrambi, oltre a impostare il tuo sistema di intelligenza artificiale nell'attività 4.
ATTIVITÀ 4
Configura i prompt AI e proteggi le chiavi API
Tempo stimato: 30 minuti
In questa attività, prima configureremo un prompt di sistema per garantire la coerenza e risparmiare sull'uso dei token. Poi aggiungeremo la nostra chiave a GitHub Secrets.
1. Trova e controlla il prompt dell'API AI
Nel nostro esempio, imposteremo un ruolo di sistema con contenuti su come rispondere, seguito dal ruolo utente, con la richiesta specifica di quel particolare utente. Per il tuo prompt AI specifico, sarà diverso.
Groq memorizzerà il prompt di sistema, visualizzandolo nei prompt successivi, e non lo conteggerà nell'utilizzo dei token.
- Controlla il codice in server.js (o come Copilot ha chiamato il tuo file del server backend) per vedere come manda il prompt. Ecco cosa ha mandato per il nostro esempio:
Nel nostro caso, userInput è inserito nel mezzo di un singolo prompt. Tutto quello che viene dopo userInput viene contato in ogni chiamata API.
- Guarda come Copilot ha impostato il tuo prompt AI.
2. Dividi il prompt in ruoli di sistema e ruoli utente
- Chiedi a Copilot di dividere il prompt in due parti: sistema e utente. Metti le istruzioni standard su come rispondere nella parte del sistema e solo il prompt dell'utente nella parte dell'utente. Ecco un esempio di prompt.
Quando chiedi qualcosa, separa la richiesta standard al ruolo di sistema e la sfida dello studente con l'input dell'utente al ruolo utente.
- Controlla il codice generato da Copilot. Dovrebbe aver diviso il prompt in due parti, ciascuna con il proprio prompt. Il prompt utente dovrebbe essere molto conciso, in modo da contenere i costi dell'API.
Ecco il codice che Copilot ha creato per noi.
const systemPrompt = `You are an expert tutor advisor. Based on what a student is struggling with, recommend what TYPE of tutor they should look for. Provide 3 specific characteristics or skills the ideal tutor should have. Focus on tutor qualifications, not actual tutor names. Provide the response in a professional yet friendly tone. Keep it under 100 words. Format the response as a numbered list of 3 characteristics.`;
const userPrompt = `Student's challenge: "${userInput}"`;
// Groq API call
const groqUrl = 'https://api.groq.com/openai/v1/chat/completions';
const model = 'llama-3.3-70b-versatile';
try {
const groqResponse = await fetch(groqUrl, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${process.env.GROQ_API_KEY}`,
},
body: JSON.stringify({
model,
messages: [
{ role: 'system', content: systemPrompt },
{ role: 'user', content: userPrompt },
],
max_tokens: 300,
}),
})
Il systemPrompt e userPrompt vengono impostati separatamente all'avvio. Il nostro userPrompt sarà molto breve, con solo "Sfida dello studente: " seguito da quello che l'utente scrive nel modulo.
3. Migliora in base ai risultati
Ora che hai capito come funziona il formato delle domande, dai un'occhiata alle risposte che ti dà Groq.
I tuoi primi tentativi probabilmente non daranno risultati perfetti. È normale e prevedibile. Lo sviluppo di app, soprattutto se c'entra l'intelligenza artificiale, è un processo che va avanti per tentativi.
Se le risposte non sono proprio giuste, aggiusta il messaggio del sistema per Groq. Puoi aggiornarlo per chiedere cose come:
- "Le risposte non devono superare le 100 parole."
- Assicurati che il tono sia amichevole e incoraggiante.
- Aggiungi una frase che spinga a fare qualcosa alla fine di ogni risposta.
- I punti elenco dovrebbero essere numerati.
Ogni miglioramento dovrebbe basarsi sulla tua app attuale. Puoi anche aggiungere un impostazione della temperatura per assicurarti che la risposta sia adatta alle tue esigenze.
4. Prova i casi limite
Gli utenti scriveranno cose inaspettate. Devi testare questi casi limite adesso, così quando arriveranno gli utenti veri, la tua app potrà gestirli senza bloccarsi o sembrare difettosa. Questo crea fiducia con i tuoi primi utenti.
- Prova i casi limite per assicurarti che la tua app gestisca bene i problemi:
- Inserimento vuoto: invia senza scrivere niente. L'app lo accetta?
- Input molto lungo – Scrivi un sacco di testo. Funziona ancora?
- Input inaspettato – Prova con un testo a caso. Che succede?
- Clic veloci: clicca più volte di fila sul pulsante. Manda più richieste?
- Se trovi dei problemi, puoi descriverli a Copilot in questo modo:
- Quando l'utente inserisce un campo vuoto, fai apparire un messaggio che gli chiede di inserire qualcosa.
- Quando il testo da inserire è troppo lungo, taglialo a 500 caratteri prima di mandarlo all'intelligenza artificiale.
- Disattiva il pulsante mentre aspetti la risposta dell'IA e riattivalo quando arriva la risposta. Così eviti che gli utenti mandino più richieste per sbaglio.
Questo trucco per disattivare il pulsante può essere utile: evita chiamate API inutili e fa capire agli utenti che qualcosa sta succedendo. Durante le demo, evita anche momenti imbarazzanti in cui potrebbero apparire più risposte contemporaneamente.
5. Trova le chiavi API nel tuo codice
Ora che il prompt dell'IA e la chiamata API sembrano a posto, passiamo alla chiave API e vediamo come proteggerla meglio.
È una buona idea poter vedere e capire come il tuo server backend sta usando la tua chiave API.
Cerca un codice tipo:
const API_KEY = process.env.API_KEY;
Guarda in server.js o in qualsiasi altro file in cui Copilot ha aggiunto il tuo codice backend. Nel nostro caso, abbiamo usato GROQ_API_KEY come variabile di ambiente, che abbiamo aggiunto a .env e il server usa process.env.GROQ_API_KEY per prendere la chiave da .env.
6. Aggiungi la tua chiave API Groq ai segreti GitHub.
GitHub Secrets tiene le tue chiavi fuori dal controllo di versione e ti permette di distribuire la tua app senza mostrare le credenziali. Questo evita che le chiavi finiscano nella cronologia dei commit, dove potrebbero essere trovate anche dopo averle cancellate.
- Vai su GitHub -> Clicca sul tuo profilo in alto a destra -> Impostazioni (l'icona a forma di ingranaggio).
- Nella barra laterale sinistra, clicca su Codespaces.
- Clicca su Nuovo segreto.
- Per Nome, scrivi: GROQ_API_KEY (o il nome giusto per l'API che stai usando)
- Copia e incolla la tua chiave API GROQ (o altra), da dove l'hai salvata sul tuo computer o dal file .env del tuo progetto.
- Scegli il tuo repository.
- Clicca su Aggiungi segreto.
7. Controlla che la chiave API funzioni ancora
- Riavvia la tua app, ricordandoti di avviare il server backend E la tua app usando npm run dev.
- Prova a chiamare l'API per vedere se funziona.
- Se vuoi davvero verificare che il segreto di GitHub funzioni, puoi temporaneamente elimina la riga da .env, e riavvia l'app. Probabilmente non funzionerà. Potrebbe essere necessario ricreare il container di Codespace:
- In Codespace, premi Ctrl+Maiusc+P o Cmd+Maiusc+P per aprire la tavolozza dei comandi.
- Digita "Codespaces: Rebuild Container" per trovarlo nell'elenco.
- Scegli "Ricostruzione completa".
- Assicurati di aggiungere di nuovo la chiave nel tuo file file .env per seguire le migliori pratiche durante lo sviluppo.
8. Controlla che la tua chiave API sia davvero al sicuro
Questo è il passo più importante perché ti assicura che la tua sicurezza funzioni davvero.
- Avvia la tua app (e il server backend).
- Apri gli Strumenti di svilupponella finestra in cui gira l'app (F12 o clicca con il tasto destro → Ispeziona).
- Vai alla scheda Rete.
- Cancella tutte le richieste che ci sono.
- Fai una richiesta AI nella tua app.
- Dai un'occhiata alle richieste che compaiono.
Dovresti vedere una richiesta del tipo localhost:3001/api/generate. Il corpo della richiesta dovrebbe contenere il tuo prompt, NON la tua chiave API. Se vedi la tua chiave API in qualsiasi intestazione o nel corpo di una richiesta, c'è qualcosa che non va!
9. Prova finale
Prima di confermare le modifiche alla chiamata API e alla chiave API, fai un ultimo controllo per assicurarti che tutto funzioni come previsto.
- Controlla:
- UI Shell: La tua interfaccia utente si vede bene?
- Flusso di interazione: i pulsanti e gli input funzionano?
- Integrazione dell'IA: la tua funzione di IA funziona?
- Casi limite: hai provato con input vuoti, input lunghi, ecc.?
- Se trovi dei problemi, risolvili con l'aiuto di Copilot e/o altri LLM.
10. Aggiorna la documentazione README
Quando l'app è stata creata per la prima volta su GitHub, hai aggiunto una semplice descrizione per il file README .
È una buona idea aggiornare il file README . Questo è importante soprattutto se usi l'intelligenza artificiale per generare codice, perché l'IA guarda sempre questa documentazione prima di fare modifiche.
- Vai alla cartella principale e trova il file README.md .
- Aggiungi più dettagli al file, spiegando quali funzioni ci sono nell'app, l'integrazione dell'intelligenza artificiale, ecc.
11. Esegui il commit e unisci le modifiche
- Quando sei sicuro che il codice funzioni come previsto, esegui lo stage e il commit sul ramo.
- Vai su GitHub, crea una pull request e unisci il tuo ramo al ramo principale.
Hai fatto un sacco di progressi sul tuo MVP, partendo dall'interfaccia utente della tua prima schermata, aggiungendo funzionalità, altre schermate, altre funzionalità e, alla fine, la tua chiamata API AI.
Potresti avere altro da aggiungere alla tua app, ma ricorda di includere solo le funzionalità MVP. Assicurati che funzionino bene e come previsto. Avrai utenti reali che useranno la tua app, quindi quello che pubblichi dovrebbe funzionare bene.
Potresti dover aggiungere altre chiamate API alla tua app, se hai funzioni come l'accesso utente o l'archiviazione cloud. Ricordati solo di procedere passo dopo passo e di testare ogni nuova parte man mano che la aggiungi.
Riflessione
Hai passato un bel po' di tempo a programmare per creare la prima bozza del tuo MVP! Ecco alcune domande da considerare:
Termini chiave
- Approccio iterativo: creare software in piccole parti (schermata per schermata), testando dopo ogni parte, invece di fare tutto in una volta. Permette di individuare i problemi in anticipo e rende più facile il debug.
- Costruzione schermata per schermata: aggiungere una schermata alla volta, provando la navigazione prima di passare a quella successiva. Ogni schermata è un "blocco" nell'approccio iterativo.
- Richiesta di sistema: le istruzioni che decidono come risponde un LLM, tipo il tono, il formato, la lunghezza e i limiti. L'hai provato in Tech 2 con il Feedback Analyzer.
- Frontend: la parte dell'app che gli utenti vedono e con cui interagiscono. Funziona nel browser. Tutto quello che hai creato nell'attività 1 è frontend.
- GitHub Secrets: spazio di archiviazione crittografato per le chiavi API su GitHub. Le chiavi non compaiono mai nel codice o nella cronologia dei commit. Si caricano automaticamente quando apri Codespaces.
- Stato di caricamento: un feedback visivo (tipo "Sto cercando il tutor perfetto per te...") che appare mentre aspetti la risposta dell'IA. È super importante perché le chiamate dell'IA ci mettono qualche secondo.
- Caso limite: input strani (vuoti, lunghissimi, fuori tema) che mettono alla prova come la tua app gestisce le situazioni inaspettate. Testarli evita brutti incidenti durante le demo.
Risorse aggiuntive
- GitHub Codespaces: ambienti di sviluppo cloud
- Documentazione GitHub Secrets: archiviazione sicura delle chiavi API
- Hugging Face Inference API: ti dà accesso a modelli di machine learning per fare previsioni.
- Documentazione API Groq
- Documentazione Tailwind CSS: Riferimento allo stile per il codice generato
- Documentazione React: riferimento al framework per capire il codice generato
- Git per principianti: commit e push su GitHub
