← mobang.fr

· Vibecoding

Spec d'une page : le document qui garde ton app cohérente

Avant de taper ton premier prompt, écris une spec d'une page. Pas un cahier des charges de quarante pages : une seule page qui dit ce que fait ton app, pour qui, avec quel modèle de données, quels écrans, quelles règles métier, quelle sécurité — et ce qu'elle ne fait pas. Ensuite, tu colles cette page en tête de contexte à chaque nouvelle session avec ton IA.

Pourquoi ? Parce que l'IA optimise localement. Chaque prompt pris isolément est bien traité : le code sort, ça tourne. Mais l'architecture globale, elle, s'improvise au fil des sessions. Résultat classique au bout de trois semaines : des doublons, des modèles de données contradictoires, des écrans qui ne se parlent pas. Ce n'est pas que l'IA code mal — c'est qu'elle n'a aucune mémoire de tes décisions si tu ne les lui redonnes pas.

La spec d'une page, c'est cette mémoire. C'est le document le moins cher et le plus rentable de tout ton projet. Voici comment l'écrire, avec un exemple complet.

Le problème : l'IA optimise localement, ton app vit globalement

Chaque session avec un assistant IA repart de zéro, ou presque. Tu demandes « ajoute la gestion des annulations », il te livre une gestion des annulations propre… construite sur les hypothèses qu'il invente à ce moment-là.

Concrètement, ça donne :

  • La session 1 crée une table users, la session 4 crée accounts pour la même chose.
  • Un écran affiche les prix TTC, un autre HT — personne ne l'a décidé.
  • La règle « un créneau = une réservation » existe dans un formulaire, mais pas dans l'API.

Aucun de ces problèmes n'est du « mauvais code ». Chaque morceau, isolément, est correct. C'est l'assemblage qui est incohérent, parce que personne — ni toi, ni l'IA — ne portait la vision d'ensemble.

Ce que contient la spec (et rien de plus)

Une page. Sept blocs. Si ça déborde, tu coupes.

  • Ce que fait l'app : deux phrases, pas plus.
  • Pour qui : le ou les types d'utilisateurs.
  • Le modèle de données : 3 à 10 entités et leurs relations, en liste simple.
  • Les écrans ou parcours principaux : la colonne vertébrale de l'expérience.
  • Les règles métier non négociables : ce qui doit être vrai partout, tout le temps.
  • La sécurité : qui voit quoi, qui peut faire quoi.
  • Le hors-périmètre : ce que l'app ne fait PAS en v1. Ce bloc compte autant que les autres.

Pas de maquettes, pas de stack technique détaillée, pas de user stories numérotées. Tout ça viendra plus tard — ce n'est pas ce qui conditionne la cohérence. La spec, si.

Exemple : la spec d'une app de réservation

# Spec — Résacoach (v1)

## Quoi
App de réservation de séances pour coachs sportifs indépendants.
Un coach publie ses créneaux, un client réserve et paie en ligne.

## Pour qui
Coachs solo (un agenda chacun) et leurs clients. Pas de salles, pas d'équipes.

## Modèle de données
- Coach : nom, email, fuseau horaire
- Créneau : coach, date/heure, durée, prix, statut (libre/réservé/annulé)
- Client : nom, email
- Réservation : créneau, client, statut paiement, date de création
Relations : un Coach a plusieurs Créneaux ;
une Réservation lie exactement 1 Créneau à 1 Client.

## Écrans
1. Agenda public du coach (liste des créneaux libres)
2. Tunnel de réservation (choix créneau → infos client → paiement)
3. Dashboard coach (créneaux, réservations, annulations)

## Règles métier non négociables
- Un créneau ne peut être réservé qu'une seule fois.
- Annulation gratuite jusqu'à 24 h avant, sinon non remboursé.
- Tous les horaires sont stockés en UTC, affichés dans le fuseau du client.

## Sécurité
- Un coach ne voit que SES créneaux et SES réservations.
- Un client ne voit que SES réservations.
- Aucune donnée de paiement stockée chez nous (déléguée au prestataire).

## Hors périmètre v1
- Pas de multi-coachs, pas d'abonnements, pas d'app mobile, pas d'avis clients.

Relis-la : tout tient sur une page, et pourtant presque toutes les décisions structurantes sont prises. L'IA n'a plus à deviner si un créneau peut être réservé deux fois, ni comment gérer les fuseaux horaires.

Pourquoi ça marche : l'IA remplit un cadre au lieu d'inventer

Un modèle de langage complète toujours ce qui manque. Si le contexte ne dit pas comment s'appelle l'entité centrale, il choisit un nom plausible — pas forcément le même qu'hier. Avec la spec en tête de contexte, il n'y a plus rien à inventer sur les fondations : les noms, les relations, les règles sont déjà là. L'IA passe d'architecte improvisé à exécutant discipliné, exactement le rôle où elle excelle.

Ce n'est pas une lubie de puriste. Andrej Karpathy, qui a inventé le terme « vibe coding » début 2025, décrivait dès la conférence AI Ascent 2026 la transition de l'industrie du codage informel vers l'« ingénierie d'agents » (agentic engineering) : la rigueur méthodique revient au centre du jeu. La spec préalable en est la première brique — et la plus simple à poser.

Bonus : cette page sert aussi aux humains. Dans six mois, c'est elle qui te réexpliquera ton propre projet en deux minutes — j'en parle dans coder pour dans six mois.

Comment l'utiliser au quotidien

Trois règles d'usage, pas plus :

  • Colle-la en tête de chaque session. Premier message du chat, ou mieux : dans le fichier de contexte permanent de ton outil (CLAUDE.md, règles Cursor, instructions projet…).
  • La spec fait foi. Si l'IA propose quelque chose qui la contredit, tu refuses — ou tu modifies la spec consciemment, puis tu continues. Jamais l'inverse.
  • Mets-la à jour au fil de l'eau. Une décision prise en discutant avec l'IA (« finalement, les annulations sont remboursées à 50 % ») va dans la spec le jour même. Une spec périmée est pire qu'aucune spec.

Le point clé : la spec vit dans ton repo, versionnée comme le code. Un SPEC.md à la racine, commité. C'est tout.

Par où commencer aujourd'hui

Trente minutes suffisent pour une première version. Dans l'ordre :

  1. Crée un fichier SPEC.md à la racine de ton projet — même s'il existe déjà du code.
  2. Écris les deux phrases « ce que fait l'app » et « pour qui ». Si tu n'y arrives pas en deux phrases, c'est déjà une information précieuse.
  3. Liste tes entités (3 à 10). Si tu as déjà du code, ouvre ta base de données et note ce qui existe vraiment — y compris les doublons que tu vas découvrir.
  4. Note 3 à 5 règles métier non négociables, et qui voit quoi.
  5. Écris le hors-périmètre v1. Sois brutal : tout ce qui est « plus tard » va là.
  6. Colle la spec en tête de ta prochaine session IA, et observe la différence.

Elle n'a pas besoin d'être parfaite. Une spec imparfaite mais présente bat une architecture parfaite qui n'existe que dans ta tête.