Spécification produit d'une page pour builds IA : écrans, champs et règles

Pourquoi les builds IA dérapent sans une spec claire

Quand vous donnez à un constructeur IA une consigne vague, il doit deviner. Il complète les détails manquants avec des schémas qu'il a vus auparavant, pas avec ce que vous vouliez dire. C'est pour ça que les apps générées par IA peuvent sembler aléatoires, même si la première démo a l'air correcte.

Ce sentiment d'« aléatoire » se manifeste souvent par des petits défauts pénibles : un écran manque un champ que vous teniez pour évident, un formulaire accepte des valeurs qui devraient être bloquées, ou un bouton mène au mauvais endroit parce que l'outil a imaginé un autre flux.

L'incohérence est un autre symptôme fréquent. Un écran l'appelle « Company », un autre « Organization ». Les admins peuvent modifier quelque chose à un endroit mais pas à un autre. La base de données finit avec des colonnes en trop, des colonnes manquantes ou des types incorrects parce que l'UI et le modèle de données ont été inventés séparément.

Une spécification produit d'une page réduit ces suppositions. Elle donne à l'outil un ensemble serré de décisions qu'il n'a pas à prendre, donc vous avez moins de reconstructions et moins d'aller-retours. Quand quelque chose est faux, vous pouvez pointer une seule phrase et la corriger au lieu de débattre de ce que le prompt « voulait vraiment dire ».

Sans une spec claire, vous verrez souvent :

• Des écrans supplémentaires que vous n'avez pas demandés, alors que des écrans clés sont oubliés
• Des champs requis devenus optionnels (ou l'inverse)
• Des permissions incohérentes (qui peut voir, créer, éditer, supprimer)
• Des règles de validation manquantes, permettant à des données erronées de passer
• Plusieurs versions du même flux (deux façons de faire une même tâche)

Cette approche convient aux fondateurs, PM, designers et agences qui utilisent des outils comme Lovable, Bolt, v0, Cursor ou Replit et veulent des builds prévisibles. Elle est aussi utile si vous avez hérité de code généré par IA et voulez que la prochaine itération soit moins chaotique et plus facile à réparer.

Ce que signifie « spécification d'une page » en pratique

Une spécification produit d'une page est une note courte et structurée qui supprime les suppositions avant de demander à un outil IA de construire. Elle n'essaie pas de capturer toute votre vision. Elle capture les décisions que les builders ont tendance à « remplir », c'est là que naissent les fonctionnalités aléatoires et la logique cassée.

Pensez-y comme un contrat : ce sont les écrans, ce sont les champs, et ce sont les règles. Si un détail change le comportement de l'app, il appartient à la page. Si ce n'est que du texte ou du style, en général ce n'est pas nécessaire.

Une spec pratique inclut :

• Une liste d'écrans avec une phrase par écran (ce que l'utilisateur peut y faire)
• Les champs de données qui doivent exister (nom, type, requis/optionnel)
• Les règles qui gouvernent le comportement (validation, permissions, changements d'état)
• Quelques contraintes pour éviter de mauvaises valeurs par défaut (méthode d'auth, rôles, limites de sécurité basiques)

Elle n'inclut pas un design UI complet, de longues user stories ou des pages de cas limites. Vous pouvez ajouter des maquettes plus tard, mais la spec doit être lisible et suffisante en elle-même.

Pour rester courte sans être vague, écrivez en statements « doit » et en « si/alors ». « Seuls les admins peuvent supprimer un projet » vaut mieux que « Les admins gèrent les projets. » « L'email est requis et doit être unique » vaut mieux que « Les utilisateurs s'inscrivent avec un email. »

Un test simple : si vous donniez cette page à quelqu'un d'autre, pourrait-il construire le comportement que vous attendez sans poser 20 questions ? Si non, la page a besoin de règles plus claires ou de champs manquants.

Étape par étape : transformer une idée en spécification d'une page

Une bonne one-page spec n'est pas un roman. C'est un ensemble d'instructions claires qui empêche un build IA de deviner. Si vous pouvez l'imprimer et que quelqu'un d'autre peut expliquer votre app en retour, elle fait son travail.

Commencez par une phrase simple qui décrit le job de l'app. Évitez le jargon. Exemple : « Aider une petite équipe à suivre les demandes clients de la boîte de réception à la résolution. »

Ensuite, nommez vos types d'utilisateurs. Restez concis (2 à 4). Pour chacun, écrivez ce qu'il est autorisé à faire en verbes simples : view, create, edit, approve, delete. Cela prévient le chaos des permissions plus tard.

Un ordre fiable pour garder la spec ancrée :

1. Écrivez la phrase job (ce à quoi ressemble le succès).
2. Définissez les types d'utilisateurs et les permissions (qui peut faire quoi).
3. Écrivez le happy path en 5 à 8 étapes (le parcours qui doit marcher à chaque fois).
4. Listez les écrans avant les fonctionnalités (quelles pages existent et ce que chaque écran doit faire).
5. Ajoutez les champs de données et les règles en dernier (une fois les écrans stabilisés).

Pour le happy path, restez concret. Pour une app de suivi de demandes : l'utilisateur se connecte, crée une demande, assigne un propriétaire, le propriétaire change le statut, le demandeur est notifié, le manager consulte un résumé hebdo.

Après que la liste d'écrans soit claire, ajoutez les champs de données nécessaires à chaque écran (titre, description, statut, propriétaire, timestamps) et les règles (champs requis, changements de statut autorisés, qui peut éditer après approbation). C'est là où les prototypes générés par IA échouent souvent : des règles ont été sous-entendues au lieu d'être écrites.

Définir les écrans de manière exécutable pour un outil IA

Si vous voulez un build prévisible, votre liste d'écrans doit se lire comme des instructions, pas comme un moodboard. Une règle simple de nommage aide : utilisez verbe + nom pour que chaque écran implique ce qui s'y passe.

Exemples : « View Orders », « Create Invoice », « Edit Profile », « Reset Password ». Évitez les noms vagues comme « Dashboard » à moins de préciser ce qu'il contient.

Traitez chaque écran comme une petite fiche avec les mêmes champs à chaque fois :

• Purpose : une phrase décrivant ce que signifie « succès » sur cet écran.
• Who can access : rôles (Guest, Signed-in user, Admin) et limites particulières.
• Main actions : 2 à 4 actions écrites comme des libellés de boutons.
• Data shown/edited : les objets clés impliqués.
• Outputs : ce qui change après l'action (enregistrement créé, email envoyé, statut mis à jour).

Indiquez les points d'entrée pour que la navigation ne soit pas inventée. Par exemple : onboarding depuis le premier lancement, connexion depuis « Sign in », un lien d'invitation vers « Accept Invite », ou un deep link vers un élément spécifique.

Définissez aussi les états ennuyeux mais importants à ne pas oublier. Pour chaque écran, ajoutez une note d'une ligne pour :

• Empty state : ce que voit l'utilisateur quand il n'y a pas encore de données.
• Error state : ce que voit l'utilisateur quand quelque chose échoue, plus l'action de récupération.

Enfin, empêchez le scope creep en nommant les écrans qui ne doivent pas exister. Exemple : « Ne doit pas exister : Admin analytics, profils publics, chat in-app. » C'est une ligne simple qui évite données, permissions et bugs en plus.

Rendre les parcours utilisateurs prévisibles, pas imaginatifs

Les outils IA comblent bien les vides, et c'est le problème. Si vous n'énoncez pas les flux principaux, l'outil inventera des étapes, des écrans et une navigation qui semblent plausibles mais ne correspondent pas à ce que vous vouliez.

Choisissez 2 à 3 flux centraux et écrivez-les bout en bout en étapes simples. Première passe linéaire, puis n'ajoutez que les branches qui empêchent une mauvaise UX et une logique cassée.

Une façon simple d'écrire les flux

Écrivez chaque flux comme un chemin numéroté avec un début et une fin clairs. Utilisez les noms d'écran exacts que vous avez listés ailleurs et dites ce qui se passe après chaque action.

• Flow 1 : Sign up -> Verify email -> Create profile -> Atterrir sur Dashboard
• Flow 2 : Create item -> Save -> Voir le détail de l'item -> Retourner à la liste avec un message de succès
• Flow 3 : Checkout -> Pay -> Confirmation -> Atterrir sur Orders (pas retour au panier)

Ajoutez ensuite quelques branches critiques :

• Cancel : si l'utilisateur abandonne à mi-chemin, où atterrit-il ?
• Retry : que se passe-t-il après un paiement échoué ou un upload raté ?
• Permission denied : que voit l'utilisateur et où peut-il aller ensuite ?
• Delete : étape de confirmation et où l'utilisateur atterrit après la suppression ?

Soyez explicite sur la navigation. Si l'app utilise des onglets, nommez-les. Si elle utilise une barre latérale, listez les sections. Si c'est un flux linéaire, dites-le. Notez aussi les attentes de « retour à » comme « après édition, revenir au détail de l'item » ou « après enregistrement des paramètres, rester sur la même page ».

Lister les champs de données pour aligner DB et UI

Si vous n'écrivez pas les champs de données, un outil IA les inventera. C'est comme ça que vous vous retrouvez avec une UI qui demande une chose et une DB qui en stocke une autre.

Un petit tableau de champs suffit souvent pour garder la build cohérente.

Utiliser un tableau compact de champs

Choisissez les objets principaux (ex. : User, Project, Item) et listez les champs pour chacun. Restez concis : nom, type, requis, et un exemple.

Sous le tableau, ajoutez une ligne : quels champs sont saisis par l'utilisateur vs générés par le système. Exemple : title et due_date sont saisis par l'utilisateur ; status par défaut = draft ; owner_user_id est défini depuis l'utilisateur connecté ; created_at est automatique.

Les relations comptent car elles entraînent écrans et permissions. Écrivez-les simplement : « Un utilisateur possède plusieurs projets. Un projet a plusieurs items. Un item appartient à un projet. »

Les valeurs par défaut et les timestamps évitent les bugs « pourquoi c'est vide ? ». Indiquez-les : status = draft, role = member, updated_at change à chaque édition, deleted_at pour soft delete (si vous le voulez).

Les champs sensibles nécessitent un traitement explicite :

• Passwords : stocker uniquement un hash, jamais en clair
• Tokens/keys : stocker chiffrés, ne jamais afficher la valeur complète dans l'UI
• Secrets : hors du client et hors des logs

Rédiger les règles qui stoppent la logique cassée

Une liste d'écrans et de champs dit à l'IA quoi construire. Les règles lui disent comment l'app doit se comporter quand de vraies personnes l'utilisent. Sans règles, vous obtenez du code « ça marche à peu près » : formulaires acceptent de mauvaises données, des utilisateurs voient des choses qu'ils ne devraient pas, des statuts changent hors ordre.

Rédigez les règles en langage courant, mais rendez-les testables. Quelqu'un doit pouvoir lire une règle et répondre « pass » ou « fail ? »

Les trois types de règles à inclure

• Validation : requis vs optionnel, longueur min/max, formats autorisés, conditions cross-field
• Permissions : qui peut view, create, edit, delete, et ce qui arrive s'ils essaient quand même
• Logique métier : comment les enregistrements évoluent (statuts), limites, unicité, dédoublonnage

Exemple : formulaire « Demander un devis ».

Validation : l'email doit matcher un format email normal ; le nom de société 2 à 80 caractères ; le budget requis seulement si le type de projet = Full rebuild.

Permissions : n'importe qui peut créer une demande ; seuls les admins peuvent changer le statut ; le demandeur ne voit sa demande que via un lien magique.

Logique métier : le statut peut évoluer Draft -> Submitted -> Approved/Rejected, jamais en arrière ; une seule demande active par email et par jour ; les doublons fusionnent les notes au lieu de créer un second enregistrement.

Décider ce qui se passe quand tout foire

Ne vous arrêtez pas à « afficher une erreur ». Spécifiez le comportement pour que l'UI et l'API s'alignent.

Restez simple :

• Le message est court et précis (pas de termes techniques).
• Il apparaît au même endroit (inline sous le champ ou dans une bannière en haut).
• La saisie de l'utilisateur est préservée.
• Les échecs de permission sont deny par défaut.
• Les échecs sont loggés avec une raison consultable par les admins.

Cas limites à signaler : liens expirés, utilisateurs supprimés référencés par d'anciens enregistrements, double-clic envoyant deux fois la même requête.

Ajouter quelques non-négociables (sécurité, auth, scalabilité)

Une one-page spec n'est complète que lorsque vous nommez ce que la build ne doit pas rater. Ces garde-fous évitent des reconstructions de dernière minute.

Sécurité et authentification (choisir, ne pas sous-entendre)

Soyez explicite sur la façon dont les gens se connectent. Si vous ne choisissez pas, l'IA décidera.

Décidez :

• Auth method : email + mot de passe, magic link, OAuth (Google, etc.) ou pas d'auth
• Roles : qui voit quoi (par ex. admin vs utilisateur)
• Session rules : déconnexion automatique, « se souvenir de moi » on/off

Écrivez aussi deux attentes basiques en clair : « Pas de secrets dans le code ou le client » et « Toutes les entrées utilisateur doivent être validées et sûres. » Cela aide à prévenir clés API exposées, injections SQL et formulaires acceptant n'importe quoi.

Scalabilité, logs et déploiement

Pas besoin de chiffres exacts, juste des cibles approximatives. Exemple : « lancer avec ~200 utilisateurs, montée possible à 10 000 ; un compte typique a 50 à 5 000 enregistrements. »

Ajoutez ce qui doit être loggé pour l'audit et le debug : connexions, échecs de connexion, changements de permissions, suppressions.

Enfin, dites où ça tournera. « On a besoin de staging et production » suffit. Précisez que les secrets doivent être des variables d'environnement (pas en dur) et listez ceux que vous connaissez (database URL, clé provider email).

Poser des limites pour garder le build focalisé

Les outils IA sont rapides, mais ils « aident » aussi en ajoutant des fonctionnalités que vous n'avez pas demandées. Une one-page spec a besoin de garde-fous pour que le v1 reste petit, testable et livrable.

Commencez par une séparation simple : must have vs nice to have. Les must-haves sont l'ensemble minimal rendant le produit utilisable de bout en bout. Les nice-to-have sont de bonnes idées, mais ne doivent pas bloquer le v1.

Définissez ce que signifie « done » pour le v1 en termes simples. C'est l'autorisation d'ignorer les gonflements de scope : polish design, filtres avancés, rôles non nécessaires, multi-langue, analytics poussés.

Pour garder l'évaluation objective, ajoutez quelques checks d'acceptation par écran :

• L'écran se charge sans erreur et affiche l'état vide adéquat
• L'utilisateur peut accomplir l'action principale en 3 étapes ou moins
• Les erreurs de validation s'affichent à côté du champ et bloquent l'enregistrement
• Le feedback de succès apparaît et les données sont visibles après refresh
• Les règles de permission sont appliquées (utilisateurs bloqués ne voient ni n'éditent)

Décidez aussi ce qui peut être mocké en v1 vs ce qui doit être réel. Les mocks sont acceptables s'ils sont clairement identifiés. Exemple : paiement factice (pas de charge réelle), emails écrits dans un log au lieu d'être envoyés, URL d'upload factices, réponses fixes pour des APIs externes.

Exemple de one-page spec (scénario simple et réaliste)

Voici une one-page spec que vous pourriez remettre à un constructeur IA pour une petite app de prise de rendez-vous en clinique.

App : “BrightClinic Booking”

Users : Patients et admins clinique.

Screens : Landing (présentation + « Book »), Sign up / Log in, Book appointment, My bookings, Admin schedule.

Sur Book appointment, l'utilisateur choisit une date, voit les créneaux disponibles, sélectionne un horaire, ajoute une note optionnelle et confirme. Sur My bookings, l'utilisateur voit les rendez-vous à venir et peut reprogrammer ou annuler.

Champs (Appointment) : Patient name (text), phone (text), appointment time (date/time), status (scheduled, cancelled), notes (optional text). Gardez le profil patient minimal pour le v1 : name et phone.

Règles (la logique qui NE DOIT pas casser)

• Pas de double réservation : un seul rendez-vous par créneau.
• Période d'annulation : les patients peuvent annuler jusqu'à 24h avant l'heure du rendez-vous.
• Édits réservés aux admins : seuls les admins peuvent changer le statut, déplacer une réservation ou éditer les notes après confirmation.
• Les patients ne peuvent voir et gérer que leurs propres réservations.

Checks rapides d'acceptation :

1. Un patient peut s'inscrire, réserver un créneau et le voir dans My bookings.
2. La reprogrammation libère l'ancien créneau et réserve le nouveau.
3. L'annulation dans les 24h est bloquée avec un message clair.
4. L'admin schedule montre tous les rendez-vous, y compris le statut.
5. Un patient ne peut pas accéder à l'écran admin.

Erreurs courantes qui rendent le code IA bordélique

La plupart des projets IA désordonnés démarrent avec une spec qui « sonne » complète mais laisse de côté les détails dont une IA a besoin pour garder la cohérence. Le résultat : écrans aléatoires, données décalées et logique qui marche à un endroit mais pas ailleurs.

Les motifs qui posent le plus de problèmes :

• Notes « features only » sans écrans. « Les utilisateurs gèrent les factures » n'est pas suffisant. Sans nommer les écrans (List, Create, Detail, Edit), le build oublie souvent les états vides et les confirmations.
• Permissions et rôles manquants. Si vous ne dites pas qui peut view/create/edit/delete, le défaut devient souvent « tout le monde peut tout faire. »
• Pas d'exemples de champs. Dire « phone number » ou « status » sans valeurs d'exemple laisse l'IA deviner les formats et noms. Vous vous retrouvez avec phone, phoneNumber et mobile dans différents fichiers, plus des valeurs de status concurrentes.
• Pas de gestion des erreurs. Beaucoup de builds décrivent uniquement le happy path. Un login raté ou une liste vide mène alors à des écrans vides ou à un chargement sans fin.
• Mélanger v1 et « plus tard ». Quand les idées futures partagent la même spec, le build essaie d'inclure tout à la fois. Vous obtenez des réglages à moitié faits, des tables inutilisées et une navigation confuse.

Un autre test : si vous donniez votre spec à un nouveau coéquipier, pourrait-il dire exactement quoi construire demain et quoi ignorer pour plus tard ? Si non, l'IA remplira les vides.

Checklist rapide et prochaines étapes

Avant de cliquer sur « build », faites un passage rapide sur votre one-page spec. Si vous pouvez répondre à ces items sans deviner, votre outil IA produira probablement quelque chose de cohérent.

Confirmez que vous avez :

• Portée claire des écrans (ce que vous pouvez faire sur chaque écran, pas seulement le titre)
• Rôles et permissions, plus les flux principaux écrits bout en bout
• Champs de données listés (nom, type, requis/optionnel, valeur par défaut, exemple)
• Validation, permissions et comportement en cas d'échec (message affiché, emplacement, action suivante)
• Limites pour le v1 (must have vs nice to have)

Si quelque chose semble flou, corrigez-le maintenant. « Les utilisateurs peuvent éditer un profil » est vague. « L'utilisateur peut éditer name et phone ; email est en lecture seule ; le phone doit faire 10 à 15 chiffres ; afficher l'erreur sous le champ ; le bouton Enregistrer reste désactivé tant que le champ n'est pas valide » est quelque chose que l'outil peut suivre.

Étapes suivantes :

1. Collez la spec dans votre builder IA et demandez une v1 fonctionnelle, pas un produit complet.
2. Testez le happy path et quelques cas d'échec (mauvais mot de passe, champ requis manquant, pas de permission, état vide, erreur réseau).
3. Si vous observez un comportement étrange, mettez d'abord à jour la spec, puis reconstruisez ou régénérez seulement la partie affectée.

Si vous avez déjà un prototype IA qui est cassé ou dangereux (problèmes d'auth, secrets exposés, logique incohérente), FixMyMess (fixmymess.ai) est fait pour cette passation : diagnostiquer les problèmes, réparer et durcir le code, et préparer le prototype pour la mise en production.