Cours Vibe coding avec Claude Code · Module 2: Un projet Next.js avec Claude Code

D'abord le plan : un mini PRD pour Kraken's Call

11 min de lecture ·
Dans cette leçon11

Ohé ! Kraken's Call a une section hero, une page de l'équipage et un journal de bord sur GitHub. D'ici la fin de ce lieu, tu transformeras tout cela en landing page, c'est-à-dire une page d'accueil qui, en quelques secondes, dit au visiteur ce qu'est le jeu et l'invite à monter à bord. Mais avant que le premier ordre de construction ne soit donné, tu vas dessiner la carte.

Problème : quatre sections et cent suppositions

La demande « fais une landing page pour Kraken's Call » semble précise, mais elle laisse à Claude des dizaines de décisions. Combien de sections la page doit-elle avoir ? Les cartes de l'équipage vont-elles sur la page d'accueil, ou restent-elles à l'adresse /crew ? Que fait le bouton « Rejoindre l'équipage » ? Le pied de page a-t-il des liens ? Tu sais depuis la leçon 0_4 que Claude comble ces trous à sa façon. Au bout d'un quart d'heure, tu reçois une page avec des animations, un formulaire d'inscription à une newsletter et un nouveau paquet npm, puis tu passes un second quart d'heure à retirer ce que tu n'avais pas demandé.

Le remède est vieux comme la navigation : avant de lever l'ancre, note où tu vas, ce que tu ne fais pas et à quoi tu reconnaîtras le port.

Un mini PRD, c'est-à-dire SPEC.md

Un PRD (Product Requirements Document) est un document d'exigences du produit. Dans les entreprises, il décrit ce qui doit naître, pour qui, et à quoi l'on voit que c'est prêt. Le nôtre sera un mini : un seul fichier SPEC.md à la racine du projet, en cinq parties :

  • objectif : une phrase sur la raison d'être de la page ;
  • public : qui y arrive et depuis quel appareil ;
  • sections de la page : ce qui s'y trouve, de haut en bas ;
  • ce que nous ne faisons pas : les limites que Claude ne franchit pas ;
  • comment nous vérifions : les commandes et les observations qui disent « c'est prêt ».

Tu as rencontré l'interview et SPEC.md dans la leçon 0_5, pour un seul fichier HTML. Ici, la même technique planifie un vrai projet, et le fichier restera dans le dépôt comme carte pour les leçons suivantes.

Demande : l'interview

Ouvre le dossier krakens-call dans Cursor, lance claude dans le terminal et passe la session en Manual. L'interview elle-même ne change rien : Claude ne demandera ton accord que lorsqu'il voudra écrire un fichier.

Demande pour Claude Code :

Je veux transformer la page d'accueil @app/page.tsx en landing page
du jeu Kraken's Call. La section hero existe déjà, et les cartes de
l'équipage sont dans @app/crew/page.tsx. Fais-moi passer une
interview : pose les questions une par une, trois au maximum à la
fois, jusqu'à ce que tu puisses écrire une spécification. Écris-la
dans SPEC.md en cinq parties : objectif, public, sections de la page,
ce que nous ne faisons pas, comment nous vérifions. Ne modifie aucun
autre fichier.

La demande désigne les fichiers avec @, donc Claude sait tout de suite ce qui se trouve déjà à bord. Elle impose aussi la forme de la spécification et ferme la porte aux changements de code : à cette étape, seule la carte naît.

À quoi ressemble l'interview

La documentation de Claude Code décrit qu'au cours de l'interview, Claude pose des questions, souvent avec des réponses à choix, sur des points auxquels tu n'as pas encore pensé, y compris sur ce qui reste hors du périmètre. Un premier tour pourrait ressembler à ceci :

1. Qui arrivera le plus souvent sur la page ?
   a) des joueurs qui entendent parler du jeu pour la première fois  b) des joueurs actuels
2. Combien d'étapes la section « Comment jouer » doit-elle avoir ?  a) trois  b) cinq
3. Que fait le bouton « Rejoindre l'équipage » ?
   a) rien pour l'instant  b) il mène à un formulaire d'inscription

Tes questions sonneront autrement, et leur nombre dépend de ce que tu as laissé dans le flou. Réponds brièvement. Quand tu ne sais pas, écris : « propose une réponse et justifie-la en une phrase ». Conseil du capitaine : les réponses les plus précieuses sont les « ça, on ne le fait pas », car chacune retire une heure de travail du futur plan.

Ce que Claude a écrit : SPEC.md

Quand l'interview est terminée, Claude demandera l'accord pour écrire. Ouvre SPEC.md dans Cursor. Ton fichier aura d'autres mots, mais les mêmes parties. En haut se trouvent l'objectif et le public :

# SPEC : page d'accueil de Kraken's Call

## Objectif
Le visiteur comprend en quelques secondes ce qu'est le jeu et clique sur « Rejoindre l'équipage ».

## Public
Des joueurs qui arrivent sur le site pour la première fois, le plus souvent depuis un téléphone.

L'objectif est une phrase qu'on peut vérifier, pas une « jolie page ». Le public avec un téléphone rappelle la règle de la leçon 1_3 : d'abord l'écran étroit. Ni l'objectif ni le public ne disent encore rien du code.

Viennent ensuite les sections de la page, écrites dans l'ordre où le visiteur les verra, de haut en bas :

## Sections de la page (du haut)
1. Hero : le nom du jeu, une phrase de description, le bouton « Rejoindre l'équipage ».
2. Équipage : trois cartes de pirates, les mêmes que sur la page /crew.
3. Comment jouer : trois étapes, chacune avec un titre et une phrase.
4. Pied de page : le nom du jeu, l'année et le lien vers le dépôt sur GitHub.

Chaque section a un contenu et des nombres : « trois étapes », pas « quelques ». La formule « les mêmes que sur la page /crew » dit à Claude d'utiliser les cartes existantes, pas d'en écrire de nouvelles.

À la fin se trouvent les deux parties auxquelles tu reviendras le plus souvent, car ce sont elles qui gardent les limites de la construction et disent quand le voyage se termine :

## Ce que nous ne faisons pas
- ni connexion, ni base de données, ni formulaires ;
- ni animations, ni nouveaux paquets npm ;
- pas d'action du bouton : pour l'instant, il ne fait que s'afficher ;
- pas de changement dans next.config.ts, Cache Components reste désactivé.

## Comment nous vérifions
- npm run build, npm run lint et npx tsc --noEmit sans erreurs ;
- page lisible à la largeur d'un téléphone ;
- chaque texte se détache nettement du fond.

« Ce que nous ne faisons pas » est la liste avec laquelle tu vas comparer le plan dans un instant. « Comment nous vérifions » rassemble les contrôles des leçons 1_2 et 1_4 et deux choses qu'aucune commande n'évaluera : l'écran étroit et le contraste. Quand le fichier te convient, demande un commit avec une description et lis les commandes avant de les accepter.

D'abord le « quoi », ensuite le « comment »

Remarque ce qui manque dans SPEC.md : ni noms de fichiers, ni composants, ni ordre de travail. La spécification répond aux questions « quoi » et « pourquoi », et le plan à la question « comment et dans quel ordre ». Tu les sépares exprès. Tu valides la spécification en capitaine qui connaît le but du voyage, et le plan est dressé par Claude, qui lit le code. Si le plan échoue, tu jettes le plan, et la spécification reste. Tu découperas le plan en petites étapes, chacune terminée par une vérification : si le build casse après l'étape trois, tu sais tout de suite où chercher le coupable.

Session neuve et mode plan

La conversation de l'interview est pleine d'idées que tu as écartées en chemin. Les bonnes pratiques de Claude Code conseillent de commencer la construction à partir de la spécification dans une session neuve : avec un contexte propre et une définition écrite de « prêt ». Tape /clear : cette commande commence une nouvelle conversation, et l'ancienne pourra être reprise plus tard. Donne ensuite une demande avec le préfixe /plan de la leçon 0_4, qui fait passer la session en mode plan :

Demande pour Claude Code :

/plan À partir de @SPEC.md, planifie la landing page en petites
étapes : une étape, c'est une section ou un changement dans les
fichiers. Pour chaque étape, indique les fichiers que tu modifieras
et termine-la par npm run build. Ne planifie rien qui sorte de
SPEC.md. Après acceptation, ajoute le plan à la fin de SPEC.md comme
partie « Plan de construction » et arrête-toi là.

La dernière phrase est nouvelle : le plan de la conversation disparaît après /clear, alors que le plan dans un fichier survit à chaque session. La construction ne démarrera que dans la leçon 1_8, étape par étape, et aujourd'hui seule naît la carte de la route.

Ce que Claude a préparé : le plan

En mode plan, Claude lit SPEC.md, les fichiers des deux pages et la configuration du projet, puis il montre un plan et demande la suite. Ton plan aura peut-être d'autres mots, mais une forme semblable :

Plan de construction
1. Déplace les types CrewRole et CrewMember, les données de l'équipage
   et CrewCard de app/crew/page.tsx vers un nouveau fichier
   components/crew.tsx ; la page /crew les importe de là et reste
   identique. npm run build.
2. app/page.tsx : le hero comme première section, en dessous la section
   « Équipage » avec les cartes CrewCard. npm run build.
3. app/page.tsx : la section « Comment jouer » avec trois étapes. npm run build.
4. app/page.tsx : le pied de page avec le nom du jeu, l'année et le lien. npm run build.
5. app/layout.tsx : titre et description de la page, lang="fr".
   npm run build et npm run lint.
Sans nouveaux paquets et sans changement dans next.config.ts.

La première étape crée un nouveau fichier, mais pour une bonne raison : les cartes de l'équipage s'afficheront maintenant sur deux pages, et le code commun doit se trouver à un seul endroit. Chaque étape nomme les fichiers et se termine par une vérification. Sur le disque, rien n'a encore changé.

Correction avant acceptation

Supposons que dans ton plan apparaisse une étape « J'installe une bibliothèque d'animation pour que les cartes entrent en douceur à l'écran ». C'est l'erreur typique de l'agent : un plan « de trop », qui ajoute des choses que personne n'a demandées. Ici, il enfreint directement l'interdiction des nouveaux paquets de SPEC.md. Choisis No, keep planning et écris :

Supprime l'étape avec la bibliothèque d'animation : SPEC.md exclut
les nouveaux paquets. Laisse le reste du plan inchangé.

Claude montrera le plan corrigé, et les fichiers restent intacts. Une petite correction, tu peux aussi la faire toi-même : Ctrl+G ouvre le plan dans l'éditeur de texte par défaut. Quand le plan passe la revue, choisis Yes, manually approve edits : l'acceptation met fin au mode plan, et chaque modification, tu l'approuves toi-même. Claude demandera l'accord pour ajouter le plan à SPEC.md et s'arrêtera là.

La revue du capitaine

Avant d'accepter le plan, vérifie quatre choses :

  1. Les fichiers : chaque étape nomme ses fichiers, et chaque nouveau fichier a une raison.
  2. Les limites : rien qui sorte de SPEC.md : ni nouveaux paquets, ni connexion, ni changements dans next.config.ts.
  3. La vérification : chaque étape se termine par npm run build.
  4. La taille de l'étape : une étape, c'est une section. Une étape du genre « construis le reste de la page » est le signe qu'il faut découper le plan.

Après l'acceptation, ouvre Source Control : seul SPEC.md a changé, et le diff montre à la fin du fichier la nouvelle partie « Plan de construction ».

Étape suivante

Demande un commit avec une description, par exemple « SPEC.md : plan de construction de la landing page ». La carte repose dans le journal. Dans la leçon suivante, tu apprendras au navire à se souvenir des règles du projet, et dans la leçon 1_8 tu lanceras la construction. Dans l'éditeur ci-dessous t'attend un SPEC.md prêt avec son plan et un second fichier avec un plan « de trop » : cherche-y les étapes qui enfreignent la spécification, et celle qui est trop grosse.

Retiens : une carte dessinée avant le voyage coûte un quart d'heure, et errer sans elle coûte toute une journée.

Code de cette leçon : SPEC.md
# SPEC : page d'accueil de Kraken's Call

## Objectif
Le visiteur comprend en quelques secondes ce qu'est le jeu et clique sur « Rejoindre l'équipage ».

## Public
Des joueurs qui arrivent sur le site pour la première fois, le plus souvent depuis un téléphone.

## Sections de la page (du haut)
1. Hero : le nom du jeu, une phrase de description, le bouton « Rejoindre l'équipage ».
2. Équipage : trois cartes de pirates, les mêmes que sur la page /crew.
3. Comment jouer : trois étapes, chacune avec un titre et une phrase.
4. Pied de page : le nom du jeu, l'année et le lien vers le dépôt sur GitHub.

## Ce que nous ne faisons pas
- ni connexion, ni base de données, ni formulaires ;
- ni animations, ni nouveaux paquets npm ;
- pas d'action du bouton : pour l'instant, il ne fait que s'afficher ;
- pas de changement dans next.config.ts, Cache Components reste désactivé.

## Comment nous vérifions
- npm run build, npm run lint et npx tsc --noEmit sans erreurs ;
- page lisible à la largeur d'un téléphone ;
- chaque texte se détache nettement du fond.

## Plan de construction
1. Déplace les types CrewRole et CrewMember, les données de l'équipage
   et CrewCard de app/crew/page.tsx vers un nouveau fichier
   components/crew.tsx ; la page /crew les importe de là et reste
   identique. npm run build.
2. app/page.tsx : le hero comme première section, en dessous la section
   « Équipage » avec les cartes CrewCard. npm run build.
3. app/page.tsx : la section « Comment jouer » avec trois étapes. npm run build.
4. app/page.tsx : le pied de page avec le nom du jeu, l'année et le lien. npm run build.
5. app/layout.tsx : titre et description de la page, lang="fr".
   npm run build et npm run lint.
Sans nouveaux paquets et sans changement dans next.config.ts.

Tu as repéré une erreur dans cette leçon ?

Teste tes connaissances

Réponds aux questions de cette leçon. Choisis une réponse pour voir tout de suite si elle est correcte.

  1. 1. Pourquoi, avant de construire la landing page, écris-tu avec Claude un mini PRD dans le fichier SPEC.md ?

  2. 2. Quelle étape du plan de la landing page est la mieux construite ?

  3. 3. Le plan de Claude prévoit d'installer une bibliothèque d'animation, alors que SPEC.md exclut les nouveaux paquets. Que fais-tu ?

Tâches pratiques dans le jeu

  • Tri vertical

    Ordonne les étapes, de la spécification prête jusqu'au plan de construction écrit dans le fichier :

  1. QuestionQuiz : pourquoi SPEC.md avant la construction
  2. QuestionQuiz : une bonne étape du plan
  3. Remets dans l'ordreOrdre : de SPEC.md au plan dans le fichier
  4. QuestionQuiz : une bibliothèque hors de SPEC dans le plan

Articles utiles