Costruire un SaaS con un coding agent: un flusso pratico

Inizia da un risultato osservabile

Un coding agent può produrre un'interfaccia dall'aspetto convincente prima ancora che tu abbia deciso cosa deve fare. Inizia da un piccolo risultato utente: un utente connesso modifica un profilo, salva e vede il nome salvato dopo un ricaricamento. Questo dà a implementazione e revisione un obiettivo concreto.

Includi nel brief il comportamento attuale, quello atteso e i casi di fallimento che contano. Nomina il modulo esistente che sostiene il lavoro. Una richiesta di aggiungere la modifica del profilo dovrebbe puntare al livello di autenticazione invece di lasciare che l'agente inventi un secondo store di utenti. Tieni le credenziali fuori da prompt e screenshot — un apps/web/.env.local incollato o un cookie di sessione diventa parte del registro della conversazione.

Un brief funzionante suona così: «Nella schermata dell'account, permetti a un utente connesso di modificare il suo nome visualizzato e di vederlo dopo il ricaricamento. Il modulo di autenticazione possiede il record utente; non aggiungere una tabella. Un nome vuoto, o una richiesta che nomina il record di un altro utente, deve essere rifiutata. Dimostralo con pnpm test e un salvataggio manuale a larghezza ridotta.» Cinque frasi, e gran parte delle supposizioni è sparita.

• Il risultato visibile all'utente, formulato in modo da poterlo verificare nell'app in esecuzione.
• Il file o modulo che possiede il comportamento oggi — e le aree che devono restare intatte.
• Almeno un caso di fallimento: un tentativo non autenticato, un input non valido o una richiesta ripetuta.
• Il controllo che lo dimostra — un comando di test, un fixture o una verifica manuale esplicita.

Fai sì che il repo si spieghi da solo

Documenta come eseguire l'app, quali controlli sono deterministici e dove viene fatto valere il possesso. In supastack, AGENTS.md registra il confine del workspace e .ai/ le decisioni a livello di file. Queste note sono più utili quando spiegano al prossimo contributore — umano o agente — perché esiste un'implementazione, non solo quali file sono cambiati. La guida alla configurazione degli agenti mostra come il kit espone quel materiale, e la guida all'installazione locale è il percorso che l'agente seguirà davvero.

Chiedi all'agente di leggere il codice rilevante prima di modificare. Una modifica ristretta di solito ha bisogno dell'interfaccia, della sua frontiera server e dei test attorno a quella frontiera. Caricare l'intero repo è meno utile che capire i pochi punti che decidono se il nuovo comportamento è corretto: il controllo di possesso, lo schema, il permesso.

Quando una funzionalità tocca la configurazione, nomina il file invece di trascriverlo — «aggiungi la chiave ad apps/web/.env.local» tiene i segreti sul disco. La stessa disciplina vale per le dashboard dei provider: descrivi la destinazione, non incollare la credenziale.

Lavora in modifiche piccole e revisionabili

Gli agenti sono più affidabili quando una modifica ha un solo proprietario e un solo risultato verificabile. «Aggiungi la modifica del profilo» è revisionabile; «migliora l'area account» invita refactor che nessuno ha chiesto. Se una funzionalità si scompone in una modifica di schema, una frontiera server e una schermata, eseguili come brief separati che lasciano ciascuno il build verde.

Fai commit o checkpoint prima di ogni esecuzione dell'agente. Una base pulita trasforma un output sbagliato in un diff cancellato invece che in un esercizio di archeologia, e dà alla tua revisione un prima-e-dopo stabile da confrontare.

Revisiona una modifica completa alla volta

Scrivi un controllo di accettazione prima di cambiare il comportamento. Per la modifica del profilo, copri un aggiornamento valido e un tentativo non autorizzato. Costruisci l'implementazione minima che soddisfa quei casi, poi ispeziona l'interazione reale con testo realistico e un viewport stretto.

Revisiona il diff quanto il risultato. Cerca logica di business duplicata, gestione delle eccezioni troppo ampia e nuove dipendenze che risolvono un problema già coperto dallo stack esistente. Esegui i controlli del progetto e registra ciò che stabiliscono. Un fixture browser può verificare un'interazione di form; non può stabilire che il database di produzione o un provider esterno sia configurato correttamente.

Ogni comando risponde a una domanda diversa. pnpm test esercita il comportamento contro adattatori fake e locali deterministici, pnpm check copre lint, typecheck e formattazione, e pnpm build fa emergere gli errori di integrazione che compaiono solo al momento del bundle. Insieme sono la base della revisione — la checklist di lancio copre ciò che deve ancora essere dimostrato nell'ambiente reale.

pnpm test
pnpm check
pnpm build

Quando l'agente sbaglia

Quando un risultato è sbagliato, resisti alla tentazione di impilare prompt di correzione su un diff difettoso. Torna al checkpoint, stringi il brief attorno a ciò che è stato frainteso — di solito un vincolo non dichiarato o un proprietario mancante — e riesegui. Ogni tentativo dovrebbe portare informazioni nuove, non solo nuova urgenza.

Un fallimento persistente di solito significa che il brief presume un contesto che il repository non contiene. Se l'agente continua a inventare un secondo posto dove conservare gli utenti, la correzione è una frase in AGENTS.md su dove vive l'identità, non un tono più fermo. Aggiorna il documento, poi riprova il task — la guida ai workflow con agenti è dove il kit conserva questo flusso di lavoro.

Domande frequenti sui workflow con agenti

Alcune domande emergono ogni volta che un founder inizia ad affidare a un coding agent lavoro di prodotto reale.

• Un coding agent può costruire un intero SaaS da solo? — Può assemblare rapidamente le parti visibili, ma quelle durevoli — autorizzazione, ciclo di vita della fatturazione, isolamento dei dati — richiedono ancora un brief, un controllo e una revisione. La velocità senza quel ciclo si trasforma in rilavorazione.
• Quanto dev'essere grande un task per un coding agent? — Abbastanza piccolo da verificarne il risultato nell'app in esecuzione in pochi minuti: un risultato visibile all'utente, un modulo proprietario, un controllo di accettazione.
• Cosa non deve mai finire in un prompt? — I segreti dei provider, i cookie di sessione, il contenuto di .env.local e i dati dei clienti. Nomina i file e lascia che lo strumento li legga in locale invece di copiare i valori in un log di chat.
• Il codice scritto da un agente cambia il modo di revisionare? — La revisione si sposta dallo scrivere al leggere: ispeziona il diff in cerca di logica duplicata, gestione delle eccezioni troppo ampia e dipendenze che risolvono di nuovo un problema che lo stack già gestisce.
• Quali test contano di più per l'output di un agente? — Quelli che fissano possesso e comportamento nei fallimenti: richieste non autorizzate, input non validi e submission ripetute, non solo il percorso felice mostrato dalla demo.