Specifiche app mobile: modello di una pagina

Documento di specifiche per un'app mobile: la risposta breve

Quando crei la tua app, un buon documento di specifiche sta in una pagina. Risponde a dieci domande: per chi, quale problema, quale funzione principale, come guadagna l'app, cosa succede senza account, quali dati devono sopravvivere, su quale piattaforma, cosa resta fuori dalla prima versione, come saprai che funziona e con quali vincoli. Il modello da copiare è più sotto. Puoi anche scaricare lo schema e la sua griglia di verifica (.md), senza registrazione.

I modelli da 40 pagine che trovi online sono scritti per un altro uso: un cliente che commissiona un'app a un fornitore e ha bisogno di un documento contrattuale. Tu invece sei sia chi decide sia chi costruisce, spesso con l'aiuto dell'IA. Il tuo documento di specifiche serve a due cose: prendere le decisioni prima di scrivere codice e dare a Claude, ChatGPT o Cursor un contesto chiaro perché costruiscano l'app giusta.

Pubblico le mie app iOS. Solys, una sveglia con minigiochi, e TradaZen, un simulatore di trading, sono sull'App Store. Nolera e Clic sono state rifiutate da Apple, poi corrette. È il metodo che applico a ognuna di loro, ed è quello che ti propongo qui.

Perché una pagina basta per inquadrare la tua app

Un documento lungo dà l'impressione di essere andati avanti. In pratica viene scritto una volta, riletto di rado, e il progetto se ne allontana già nelle prime settimane. Una pagina, invece, si rilegge in due minuti prima di ogni sessione di lavoro.

Il limite di spazio ha anche un effetto utile: ti obbliga a decidere. Se una risposta supera due frasi, spesso è perché la decisione non è stata presa. Meglio scoprirlo su un foglio che nel codice, tre settimane dopo.

Infine, una pagina è la misura giusta per l'IA. Puoi incollarla per intero in una conversazione o metterla nel file di contesto del progetto. Un documento breve facilita la rilettura e riduce le istruzioni contraddittorie. Non garantisce che l'IA le seguirà: verifica le sue proposte rispetto a questo quadro.

Cosa deve contenere un documento di specifiche per un'app mobile?

Rispondi a ognuna di queste domande in una o due frasi.

1. Chi usa l'app, e in quale situazione? Non "i 18-35enni". Piuttosto una persona precisa, in un momento preciso della sua giornata.
2. Quale problema risolve l'app, in una frase? Se ti serve un "e inoltre", stai descrivendo due app.
3. Qual è LA funzione principale della prima versione? Una sola. Le altre aspetteranno i numeri. La pagina MVP di un'app iOS spiega come sceglierla.
4. Come guadagna l'app? Abbonamento, acquisto unico o gratuita. Questa risposta cambia l'app fin dalla prima schermata. Se sei indeciso, leggi abbonamento o acquisto unico per un'app iOS.
5. Cosa si può fare senza creare un account? Decidere presto cosa è accessibile senza registrazione ti evita di rifare tutto il percorso di benvenuto.
6. Quali dati devono sopravvivere a un cambio di telefono? È la domanda che decide se ti serve un backend come Supabase o se tutto può restare sul dispositivo.
7. Solo iOS, o iOS e Android? Il mio consiglio quando sei agli inizi: prima iOS. Spiego perché in app iOS e Android insieme.
8. Cosa è esplicitamente FUORI dalla prima versione? La sezione più utile del documento. Taglia le discussioni prima che nascano, con te stesso come con l'IA.
9. Come saprai che funziona? Un solo segnale, misurabile nelle settimane dopo l'uscita: prove gratuite avviate, abbonati, utenti che tornano.
10. Quali sono i tuoi vincoli reali? Il tempo che puoi dedicarci ogni settimana, la tua attrezzatura e il tuo account Apple Developer, che costa 99 $ all'anno. Niente Mac? Non è un ostacolo, come spiego in pubblicare un'app iOS senza Mac.

Il modello di documento di specifiche da copiare

Copia questo modello in una nota o in un file di testo nella root del progetto, poi sostituisci ogni riga.

• Nome provvisorio dell'app: …
• Per chi: una persona che … nel momento in cui …
• Problema risolto, in una frase: …
• Funzione principale della versione 1: …
• Cosa vede l'utente aprendo l'app per la prima volta: …
• Modello di business: abbonamento / acquisto unico / gratuito, e cosa è a pagamento: …
• Senza account si può: …
• Dati da conservare tra due telefoni: nessuno / …
• Piattaforma: prima iOS (Android più avanti se i numeri lo giustificano)
• Fuori dalla versione 1: …, …, …
• Segnale di successo: …
• Stack: React Native, Expo, Supabase se servono account, RevenueCat per gli abbonamenti
• Vincoli: … ore a settimana, account Apple Developer aperto o no, Mac o no
• App di cui mi piace l'esperienza, e perché: …

Aggiungi da tre a cinque screenshot di app che ti piacciono, con una parola su cosa ti piace. Dice più di una guida di stile, per te come per l'IA.

Un documento di specifiche non è una lista dei desideri. È una lista di decisioni prese.

Esempio: la pagina compilata per un'app inventata

Per vedere il livello di dettaglio atteso, ecco il modello compilato per un'app inventata per l'esempio, un timer per lo studio.

• Per chi: uno studente che ripassa da solo la sera e si distrae dopo dieci minuti.
• Problema: non riesce a reggere una sessione di studio senza toccare il telefono.
• Funzione principale: avviare una sessione cronometrata e vedere la propria serie di giorni mantenuti.
• Prima schermata: un solo pulsante per avviare una sessione.
• Modello di business: abbonamento per le statistiche dettagliate, sessione base gratuita.
• Senza account: tutto, tranne il backup tra due telefoni.
• Fuori dalla versione 1: modalità di gruppo, classifica tra amici, widget, versione Android.
• Segnale di successo: utenti che tornano più giorni di fila.

Nota cosa manca di proposito: nessuna lista di venti schermate, nessun colore imposto, nessuna architettura. Queste scelte arriveranno costruendo, e la pagina ti serve a verificare che restino al servizio della funzione principale.

Come usare il documento di specifiche per guidare l'IA

È qui che la tua pagina rende di più. Un'IA che scrive codice senza contesto tira a indovinare, e spesso indovina un'app diversa dalla tua.

Metti la pagina nel contesto permanente del progetto. Claude Code legge un file CLAUDE.md nella root, Cursor ha i suoi file di regole. Incollaci il documento di specifiche, insieme al tuo stack. Così ogni richiesta parte dalla stessa base.

Cita la sezione "fuori dalla versione 1" quando l'IA esagera. Gli assistenti propongono volentieri funzioni in più: una modalità scura, una condivisione, una notifica. La tua lista di esclusioni ti dà una risposta già pronta: non adesso.

Chiedi un piano che rispetti la pagina. Prima di un lavoro grosso, scrivi: "ecco il mio documento di specifiche, proponi un piano per la funzione principale, non scrivere ancora codice". Capisci subito se il piano si allontana da quello che hai deciso.

Fagli rileggere la pagina, non solo il codice. Chiedi: "quali domande di questo documento di specifiche sono vaghe o contraddittorie?". È un uso sottovalutato dell'IA, e ti evita settimane di lavoro nella direzione sbagliata.

Per approfondire, ho descritto trappole e verifiche in creare un'app iOS con l'IA.

Trasformare le decisioni in criteri di verifica

Una funzione principale deve avere un risultato osservabile. Per il timer inventato di questo esempio, "il timer funziona" è troppo vago. Scrivi piuttosto: "Avvio una sessione, vedo il tempo rimanente, posso fermarla e ritrovare l'ultima sessione completata dopo aver riaperto l'app." Decidi a parte se il timer deve continuare a schermo bloccato: questa scelta può cambiare il lavoro tecnico.

Aggiungi per ogni funzione tre righe: azione, risultato atteso, prova. La prova può essere un test automatico per un calcolo o una verifica sul dispositivo per un percorso. Annota anche cosa non è stato testato. Questa piccola griglia evita di confondere una schermata finita con una funzione pronta all'uso.

Ecco una griglia compilata per il nostro timer inventato. Sono criteri da verificare, non test già superati:

Decisione del documento	Da testare	Risultato atteso
La sessione base è accessibile senza account	Installare l'app e avviare una sessione senza registrarsi	Nessun modulo di registrazione blocca l'avvio
Una sessione abbandonata non conta nella serie	Fermare una sessione prima della fine, poi aprire lo storico	Non viene aggiunta nessuna sessione completata
Lo storico resta sul dispositivo	Completare una sessione, chiudere e riaprire l'app	La sessione compare una sola volta con la durata giusta
Il timer base funziona senza rete	Attivare la modalità aereo e completare una sessione	Il timer e il salvataggio locale restano utilizzabili
Le statistiche dettagliate sono a pagamento	Aprire le statistiche senza abbonamento	Compare l'offerta; la sessione base resta accessibile

I punti ancora vaghi diventano decisioni da prendere. Per esempio: cosa fare se l'utente blocca lo schermo o cambia l'ora del telefono durante una sessione? Non lasciare che l'agente scelga in silenzio. Scrivi il comportamento voluto, poi aggiungi il caso alla griglia. Per organizzare questo collaudo su un'installazione reale, usa la guida testare la tua app iPhone con TestFlight.

Decidere cosa togliere quando la prima versione straborda

Riprendi ogni funzione e fatti una domanda: "Senza di lei, l'utente può ancora ottenere il risultato promesso?" Per il nostro timer, una classifica tra amici può aspettare. Ritrovare una sessione completata è necessario se prometti una serie di giorni. Una schermata di abbonamento diventa necessaria solo se vendi davvero le statistiche già in questa versione.

Annota la decisione e il motivo nel registro del modello scaricabile. Potrai tornare su questa scelta dopo i test, senza perdere il perché del perimetro iniziale. Il tutorial creare un'app con Claude Code mostra poi come trasformare questo quadro in richieste limitate e verificabili.

Per un'esperienza sul campo, TradaZen ha cambiato perimetro dopo la pubblicazione. Il documento serve a far uscire una prima versione misurabile, poi a decidere la successiva con riscontri reali.

La trappola del catalogo di funzionalità

Il riflesso naturale è elencare tutto quello che l'app "dovrà fare": la mappa, la chat, le notifiche, i referral, la modalità offline. Questo catalogo è il segnale più affidabile di un progetto che non arriva in fondo, per un motivo semplice: ogni funzione aggiunta prima dell'uscita rimanda il momento in cui utenti veri ti dicono cosa conta.

Una buona prima versione fa una cosa, e la fa bene. Attenzione però all'eccesso opposto: Apple chiede che un'app vada oltre un sito web impacchettato, secondo la regola 4.2 delle App Review Guidelines. Una sola funzione principale, sì; un guscio vuoto, no: è il motivo della guideline 4.2.

Cosa non deve contenere un documento di specifiche per app mobile

• Una guida di stile completa. All'inizio bastano alcuni screenshot di riferimento.
• Una pianificazione giorno per giorno. Non hai ancora le informazioni per rispettarla. Basta un obiettivo settimanale.
• Un'architettura tecnica dettagliata. Scegli uno stack collaudato, poi lascia che i dettagli si decidano costruendo.
• Funzioni "per dopo" mescolate al resto. Vanno tutte nella sezione fuori dalla versione 1.

Quando aggiornare il documento di specifiche?

Rileggilo all'inizio di ogni settimana di lavoro. Aggiornalo solo quando una decisione cambia per un motivo vero: un test sul tuo iPhone che mostra che una schermata non funziona, un riscontro di un tester, un vincolo di Apple scoperto strada facendo. Se lo modifichi ogni giorno, vuol dire che non inquadra più niente.

Una volta pubblicata la prima versione, la pagina diventa la base della successiva: ciò che era fuori dalla versione 1 risale, ordinato in base a quello che ti dicono i numeri. La panoramica del percorso, dall'idea alla pubblicazione, è nella pagina creare un'app per iPhone.

Dalla pagina all'app pubblicata

Se hai risposto alle dieci domande, hai già fatto il lavoro che molti progetti saltano. Il seguito è costruire la funzione principale, testarla sul tuo iPhone, collegare gli abbonamenti e preparare il dossier per Apple.

Questo percorso è quello dell'iOS Kit, in quattro tappe da seguire al tuo ritmo: la prima serve a scegliere l'app che può rendere, il suo pubblico e il suo prezzo, e il tuo documento di specifiche ne è il punto di partenza.

Non sai se la tua idea è pronta a stare in una pagina? La diagnosi gratuita ti dice cosa blocca oggi il tuo progetto e quale tappa affrontare per prima. La home mostra poi come creare un'app mobile partendo da questo quadro, con Claude Code.

Non ti prometto né guadagni né pubblicazione: è Apple a convalidare, e il mercato decide il resto. Anche senza il kit, questo modello ti basta per iniziare.

Domande frequenti

Come si scrive un documento di specifiche per un'app mobile?

Fai stare il documento in una pagina: dieci domande, una o due frasi per risposta. Riguardano il pubblico, il problema, la funzione principale, il modello di business, cosa succede senza account, i dati che devono sopravvivere, la piattaforma, cosa è fuori dalla prima versione, il segnale di successo e i vincoli. Se una risposta supera due frasi, spesso la decisione non è stata presa.

Quale software usare per scrivere un documento di specifiche per un'app?

Una semplice nota o un file di testo nella root del progetto: ci copi il modello, poi sostituisci ogni riga. Puoi anche scaricare lo schema e la sua griglia di verifica (.md), senza registrazione. Per guidare un'IA, mettilo poi nel file di contesto del progetto.

Serve un documento di specifiche da 40 pagine per un'app?

No, quando crei la tua app basta una pagina. I modelli da 40 pagine che si trovano online sono scritti per un cliente che commissiona un'app a un fornitore e ha bisogno di un documento contrattuale. Tu decidi e costruisci: la tua pagina serve a prendere le decisioni prima di scrivere codice e a dare contesto all'IA.

Come dare il documento di specifiche a un'IA che scrive codice?

Metti la pagina nel contesto permanente del progetto: Claude Code legge un file CLAUDE.md nella root, Cursor ha i suoi file di regole. Cita la sezione "fuori dalla versione 1" quando l'IA esagera. Prima di un lavoro grosso, chiedi un piano che rispetti la pagina, senza scrivere subito codice.

Come verificare che una funzione rispetti il documento di specifiche?

Aggiungi per ogni funzione tre righe: l'azione, il risultato atteso e la prova. La prova può essere un test automatico per un calcolo o una verifica sul dispositivo per un percorso. Annota anche cosa non è stato testato, per non confondere una schermata finita con una funzione pronta all'uso.

Cosa non mettere in un documento di specifiche per un'app?

Quattro cose da evitare: una guida di stile completa, una pianificazione giorno per giorno, un'architettura tecnica dettagliata e funzioni "per dopo" mescolate al resto. All'inizio bastano alcuni screenshot di riferimento, e per la pianificazione basta un obiettivo settimanale. Le funzioni per dopo vanno tutte nella sezione fuori dalla versione 1.