Cours Vibe coding avec Claude Code · Module 11: Clone de Spotify

Le déploiement : Claude prépare l'aperçu, tu valides la production

11 min de lecture
Dans cette leçon13

Sea Shanty Sounds tourne sur ton ordinateur mais l'équipage veut écouter des shanties au port, sur les téléphones. Il faut prendre la mer : construire l'application sur un serveur et lui donner une adresse sur internet. C'est le déploiement, en anglais deployment. Claude Code le fera en une minute, et c'est précisément ce qui est dangereux. Un agent travaille plus vite que tu ne lis, et un déploiement en production, tous les utilisateurs le voient aussitôt.

Ce que tu vas apprendre

  • distinguer le déploiement d'aperçu du déploiement de production et savoir quand naît lequel ;
  • garder les valeurs des variables sur la plateforme et, dans le dépôt, seulement .env.example ;
  • autoriser les images d'un serveur externe avec images.remotePatterns dans next.config.ts ;
  • écrire un skill /deploy que toi seul lances et qui ne déploie que l'aperçu ;
  • ajouter une règle ask pour les commandes de déploiement et savoir ce que le mode auto fait de la production ;
  • promouvoir un aperçu en production de ta propre main et avoir un plan de repli.

Ce qui peut mal tourner

Trois choses font couler le plus souvent. Un secret atterrit dans le dépôt ou dans le code envoyé au navigateur. Une nouvelle version casse le site pour tout le monde à la fois. Un agent déploie quelque chose dont tu ne sais rien, parce qu'il "voulait vérifier que ça marche". Chacune reçoit dans cette leçon son verrou.

Aperçu et production

Dans le cours, nous déployons sur Vercel. Sa documentation décrit trois environnements : local, aperçu (Preview) et production (Production). L'aperçu est une version à vérifier à une adresse séparée, qui ne touche pas la page principale. Il naît quand tu pousses une branche autre que celle de production, ouvres une pull request ou lances vercel sans le drapeau --prod. La production naît de la branche de production, en général main, ou de vercel --prod. Il y a une exception que l'agent oublie volontiers : le premier déploiement d'un nouveau projet est toujours un déploiement de production, même sans --prod et depuis une autre branche.

La demande : prépare, ne déploie pas

Demande pour Claude Code :

Prépare Sea Shanty Sounds pour un déploiement sur Vercel. Ne déploie pas.
1. Les pochettes d'albums d'images.unsplash.com dans le lecteur via
   next/image, et dans next.config.ts un images.remotePatterns
   seulement pour cet hôte.
2. L'adresse du dossier des enregistrements dans NEXT_PUBLIC_AUDIO_BASE_URL,
   par défaut /audio en local.
3. Un .env.example avec les noms des variables que lit le code, sans
   valeurs. Vérifie que Git ne l'ignore pas.
À la fin, les commandes de vérification de CLAUDE.md et git status --short.

"Ne déploie pas" est au début exprès. Selon la documentation du mode auto, une limite énoncée dans la conversation vaut pour le classificateur comme une interdiction, tant que tu ne la lèves pas.

Ce que Claude a écrit : une variable au lieu d'une adresse

Sea Shanty Sounds n'a aujourd'hui aucun secret. Il a en revanche une valeur qui diffère selon l'environnement : l'adresse du dossier des enregistrements. Ouvre lib/catalog.ts dans Cursor :

const AUDIO_BASE_URL = process.env.NEXT_PUBLIC_AUDIO_BASE_URL ?? "/audio";

?? prend le côté droit quand le gauche n'existe pas, donc en local les enregistrements viennent toujours de public/audio. Le préfixe NEXT_PUBLIC_ te vient de la leçon 8_4 : Next.js écrit cette valeur dans le code destiné au navigateur au moment du build. Nous avons construit le projet avec la variable définie, et dans un fichier de .next/static/chunks figurait let o="https://szanty.example.test/audio". Pour une adresse publique, c'est parfait ; pour une clé, jamais. À côté du code, Claude a écrit .env.example :

# Adresse du dossier des enregistrements. En local, vide : l'application prend /audio dans public/.
# Sur Vercel, à définir séparément pour Preview et Production.
NEXT_PUBLIC_AUDIO_BASE_URL=

Le fichier montre des noms, jamais des valeurs. Le piège de la leçon 8_5, Claude l'a contourné seul : il a ajouté à .gitignore la ligne !.env.example, et git status --short a montré le nouveau fichier.

Les valeurs, tu les saisis sur la plateforme. Selon la documentation de Vercel, dans le projet tu choisis dans le menu latéral Environment Variables, tu donnes un nom, tu coches les environnements (Production, Preview, Development) et le type : Config reste lisible par les personnes autorisées, tandis qu'un Secret ne peut plus qu'être écrasé après l'enregistrement. Le changement ne vaut que pour les nouveaux déploiements, donc après lui il faut déployer de nouveau.

Ce que Claude a écrit : les images d'un serveur externe

Le lecteur affiche la pochette avec le composant Image de la leçon 3_1, et l'adresse de la pochette se trouve dans les données de l'album. next/image fait passer la photo par l'optimiseur de ton serveur, donc Next.js doit savoir de quels hôtes il a le droit de la récupérer. Ouvre next.config.ts :

  images: {
    remotePatterns: [
      { protocol: "https", hostname: "images.unsplash.com", pathname: "/**", search: "" },
    ],
  },

L'entrée n'admet que https, que cet hôte, n'importe quel chemin (/**) et les adresses sans paramètres (search: ""). Nous l'avons vérifié après npm run build et npm start : la pochette d'images.unsplash.com est revenue de l'optimiseur avec le code 200, tandis que la même adresse avec ?w=1280, une adresse en http et une photo d'un autre hôte ont reçu un 400 avec le message "url" parameter is not allowed. Sans cette entrée, npm run dev rendait la page avec une erreur 500 et le message hostname "images.unsplash.com" is not configured under images.

L'erreur typique de l'agent est l'option des vieux tutoriels, images: { domains: ["images.unsplash.com"] }. Chez nous, npx tsc --noEmit et npm run lint n'ont rien dit, et le build est passé avec un avertissement indiquant que images.domains est déprécié au profit de images.remotePatterns. La documentation de Next.js explique que domains ne sait limiter ni le protocole, ni le port, ni le chemin. Un avertissement dans le build, tu le lis aussi attentivement qu'une erreur.

Le skill /deploy : toi seul lèves l'ancre

Les skills, tu les as découverts dans la leçon 6_1, et le champ disable-model-invocation y servait pour le formulaire. Ici, il est essentiel.

Demande pour Claude Code :

Écris le skill /deploy dans .claude/skills/deploy/. Moi seul peux le
lancer. Le skill vérifie que le projet est relié à Vercel, lance les
commandes de vérification de CLAUDE.md, s'arrête devant des changements
non commités et ne déploie que l'aperçu avec npx vercel deploy.
Jamais de --prod, de --temporary ni de promote.

Ouvre .claude/skills/deploy/SKILL.md. L'en-tête ressemble à ceci :

---
name: deploy
description: Déploie Sea Shanty Sounds sur Vercel en version d'aperçu (preview). Ne déploie jamais la production.
disable-model-invocation: true
---

La documentation des skills donne le déploiement comme exemple modèle de ce champ : tu ne veux pas que Claude déploie parce que le code a l'air prêt. Si Claude tente de lancer le skill alors que ton message ne contient pas /deploy, Claude Code bloque l'appel. Sous l'en-tête, les étapes :

1. Vérifie que le dossier .vercel existe (projet relié par vercel link). S'il n'existe pas, arrête-toi : le premier déploiement d'un nouveau projet sur Vercel va toujours en production, donc c'est le capitaine qui relie et déploie.
2. Lance toutes les commandes de la section "Commandes de vérification" de CLAUDE.md. Si l'une échoue, arrête-toi et montre le résultat.
3. Lance git status --short. S'il y a des changements non commités, arrête-toi et demande.
4. Déploie l'aperçu avec une seule commande : npx vercel deploy. Sans --prod, sans --environment, sans --temporary, sans vercel promote.
5. Montre l'adresse de l'aperçu tirée du résultat de la commande et la liste de ce qu'il faut vérifier dans le navigateur : le lecteur, les pochettes d'albums, la recherche.

Le dossier .vercel est créé par vercel link. Dans un projet non relié, npx vercel deploy --dry a répondu chez nous Error: Project is not linked. avec le conseil de lancer d'abord vercel link. L'interdiction de --temporary a aussi sa raison : selon la documentation de Vercel, ce drapeau déploie sans compte et toujours en production, et Vercel le recommande entre autres quand c'est un agent qui déploie.

Les ceintures de sécurité : la règle ask

Le skill surveille ce que Claude fait sur ta demande. Une règle de .claude/settings.json surveille chaque commande, même lancée hors du skill :

{
  "permissions": {
    "deny": ["Read(./.env)", "Read(./.env.*)", "Read(!.env.example)"],
    "ask": ["Bash(vercel*)", "Bash(npx vercel*)", "Bash(git push *)"]
  }
}

deny, tu le connais depuis les leçons 8_4 et 8_5. ask demande à Claude Code de te demander ton accord à chaque commande correspondante, et la documentation des permissions dit qu'une telle question apparaît aussi en mode auto. L'absence d'espace avant l'astérisque est voulue : Bash(npx vercel*) attrape aussi npx vercel@latest deploy. Deux règles sont nécessaires, car npx ne fait pas partie des enveloppes que Claude Code retire avant la comparaison. La troisième surveille Git : quand Vercel est relié au dépôt, un push sur main est un déploiement de production, et le classificateur du mode auto laisse passer par défaut un push vers n'importe quelle branche de ton dépôt. La règle compare le texte de la commande, elle n'est donc pas une frontière de sécurité : un sh -c avec la même commande lui échappe.

Le mode auto et la production

Selon la documentation, le classificateur du mode auto bloque par défaut, entre autres, les déploiements de production et les migrations. C'est la dernière ligne de défense, pas la première. Une limite énoncée dans la conversation peut disparaître lors de la compaction de la conversation, et la documentation conseille elle-même une règle deny quand tu as besoin d'une garantie. C'est pourquoi la production n'est pas une étape de Claude, mais la tienne.

La production, c'est toi qui la promeus

/deploy se termine par l'adresse de l'aperçu. Tu l'ouvres dans le navigateur et tu cliques ce que cliquera l'équipage : Lecture, les pochettes, la recherche. Ce n'est qu'ensuite que, dans le tableau de bord de Vercel, tu ouvres Deployments, le menu à trois points du déploiement choisi et Promote to Production. La documentation prévient que la promotion d'un aperçu reconstruit l'application avec les variables de production. La même promotion, vercel promote <adresse> la fait dans ton propre terminal, en dehors de la session de Claude. Selon la documentation, Vercel construit les nouveaux projets sur le dernier Node.js LTS qu'il propose (état en novembre 2026 : 26.x). Quand tu testes en local sur une autre version, fixe-la dans le champ engines de package.json.

Le plan de repli

Avant de promouvoir, tu sais où tu reviendras. Instant Rollback dans le tableau de bord (la vignette du déploiement de production sur la page du projet) ou vercel rollback rebranche les domaines sur un déploiement antérieur sans reconstruire, donc les variables restent celles qu'avait ce déploiement. Après le retour en arrière, Vercel désactive l'attribution automatique des domaines de production : les nouveaux push sur main n'arrivent pas sur le site tant que tu n'as pas promu un déploiement.

La revue du capitaine

  1. Le skill. L'en-tête de /deploy contient disable-model-invocation: true, et les étapes ne contiennent ni --prod, ni --temporary, ni promote.
  2. Les secrets. Cherche NEXT_PUBLIC_ dans le projet : les résultats ne doivent être que des adresses publiques. git status montre .env.example, et pas .env.local.
  3. Les images. next.config.ts a remotePatterns, pas domains, et le build n'affiche aucun avertissement.
  4. La question d'accord. Demande à Claude npx vercel --version : Claude Code doit demander ton accord. L'erreur typique de l'agent est un déploiement "pour vérifier" avec vercel --prod ou --temporary ; la règle ask l'arrête avant qu'il parte.

Étape suivante

Demande un commit, par exemple "Pochettes, .env.example, skill /deploy et règles ask". Fais le premier déploiement toi-même, car il sera de toute façon en production : importe le dépôt dans le tableau de bord de Vercel ou lance npx vercel login et npx vercel dans ton propre terminal. Chaque suivant commence par /deploy et finit par ton clic. Dans l'éditeur ci-dessous t'attend une simulation de cette traversée : déploie l'aperçu, vérifie-le, promeus-le, puis casse la version et reviens en arrière d'un seul bouton.

Retiens : le capitaine lève l'ancre de sa propre main, même avec le meilleur équipage, et avant de quitter le port il sait dans quel abri il se réfugiera quand la tempête se lèvera.

Code de cette leçon : App.jsx
// Traversée de déploiement en simulation : aperçu, promotion, retour en arrière et un agent qui veut "juste vérifier"
import { useState } from 'react';

const ENV = {
  Preview: 'https://test.example.test/audio',
  Production: 'https://szanty.example.test/audio',
};

export default function App() {
  const [deployments, setDeployments] = useState([]);
  const [current, setCurrent] = useState(null); // id du déploiement sur le domaine de production
  const [autoAssign, setAutoAssign] = useState(true);
  const [version, setVersion] = useState(1);
  const [brokenCode, setBrokenCode] = useState(false);
  const [hiddenBug, setHiddenBug] = useState(false);
  const [autoMode, setAutoMode] = useState(true);
  const [askRule, setAskRule] = useState(true);
  const [prompt, setPrompt] = useState(null);
  const [log, setLog] = useState([]);

  const linked = deployments.length > 0;
  const live = deployments.find((d) => d.id === current);

  function say(line) {
    setLog((l) => [line, ...l].slice(0, 8));
  }

  function addDeployment(target, broken) {
    const d = { id: `dpl_${deployments.length + 1}`, target, version, broken, checked: false };
    setDeployments((list) => [d, ...list]);
    setVersion((v) => v + 1);
    return d;
  }

  // Capitaine : vercel link et premier déploiement (toujours en production)
  function firstDeploy() {
    const d = addDeployment('Production', false);
    setCurrent(d.id);
    say(`${d.id}: le premier déploiement d'un nouveau projet est allé en production`);
  }

  // /deploy : commandes de vérification, puis seulement l'aperçu
  function runDeploySkill() {
    if (!linked) {
      say("/deploy : pas de dossier .vercel, je m'arrête. Relie le projet et fais le premier déploiement toi-même.");
      return;
    }
    if (brokenCode) {
      say("/deploy : npm run test -- --run : 2 failed. Je m'arrête, je ne déploie rien.");
      return;
    }
    const d = addDeployment('Preview', hiddenBug);
    say(`/deploy : tests, lint, types et build verts. Aperçu ${d.id} prêt.`);
  }

  function checkPreview(preview) {
    setDeployments((list) => list.map((d) => (d.id === preview.id ? { ...d, checked: true } : d)));
    say(preview.broken
      ? `${preview.id}: dans le navigateur, les pochettes ne se chargent pas, alors que les tests étaient verts`
      : `${preview.id}: dans le navigateur, ça joue, les pochettes et la recherche fonctionnent`);
  }

  // Promote to Production : nouveau build avec les variables de production
  function promote(preview) {
    const d = addDeployment('Production', preview.broken);
    setCurrent(d.id);
    setAutoAssign(true);
    say(`Promote to Production: ${preview.id} reconstruit en ${d.id} avec les variables Production`);
  }

  function shipBrokenToProduction() {
    const d = addDeployment('Production', true);
    setCurrent(d.id);
    say(`${d.id}: une version avec un bug que personne n'a vérifiée est entrée en production`);
  }

  // Instant Rollback : les domaines reviennent au déploiement de production précédent, sans reconstruire
  function rollback() {
    const production = deployments.filter((d) => d.target === 'Production');
    const previous = production[production.findIndex((d) => d.id === current) + 1];
    if (!previous) {
      say("Instant Rollback : il n'y a pas de déploiement de production antérieur.");
      return;
    }
    setCurrent(previous.id);
    setAutoAssign(false);
    say(`Instant Rollback : le domaine pointe vers ${previous.id}. Attribution automatique des domaines désactivée.`);
  }

  // L'agent veut lancer un déploiement de production "pour vérifier"
  function agentProdDeploy() {
    const command = 'npx vercel deploy --prod';
    if (askRule) {
      setPrompt(command);
      say(`Règle ask : Claude Code demande l'accord pour ${command}`);
    } else if (autoMode) {
      say(`Mode auto : le classificateur a bloqué ${command} (déploiement de production)`);
    } else {
      setPrompt(command);
      say(`Mode Manual : Claude Code demande l'accord pour ${command}`);
    }
  }

  function answerPrompt(allow) {
    if (allow) {
      shipBrokenToProduction();
    } else {
      say("Tu as refusé. La production ne change pas.");
    }
    setPrompt(null);
  }

  return (
    <div className="min-h-screen bg-gray-950 p-4 text-white">
      <div className="mx-auto max-w-xl space-y-4">
        <div className="rounded-xl bg-gray-900 p-3 text-sm">
          <p className="text-gray-400">Domaine de production</p>
          {live ? (
            <p className={live.broken ? 'text-red-400' : 'text-green-400'}>
              {live.id} (v{live.version}) {live.broken ? 'casse le lecteur' : 'joue correctement'}
            </p>
          ) : (
            <p className="text-gray-500">Rien n&apos;a encore pris la mer.</p>
          )}
          <p className="mt-1 text-xs text-gray-400">
            Attribution automatique des domaines : {autoAssign ? 'activée' : 'désactivée après le retour en arrière'}
          </p>
        </div>

        <div className="flex flex-wrap gap-2 text-sm">
          <button type="button" onClick={firstDeploy} disabled={linked} className="rounded bg-gray-700 px-3 py-1 disabled:opacity-40">
            Capitaine : vercel link et premier déploiement
          </button>
          <button type="button" onClick={runDeploySkill} className="rounded bg-white px-3 py-1 font-semibold text-black">
            /deploy
          </button>
          <button type="button" onClick={rollback} disabled={!linked} className="rounded bg-gray-700 px-3 py-1 disabled:opacity-40">
            Instant Rollback
          </button>
          <button type="button" onClick={agentProdDeploy} className="rounded bg-red-800 px-3 py-1">
            Claude : je déploie la production pour vérifier
          </button>
        </div>

        <div className="space-y-1 text-sm">
          <label className="flex items-center gap-2">
            <input type="checkbox" checked={brokenCode} onChange={(e) => setBrokenCode(e.target.checked)} />
            Code avec un bug (tests rouges)
          </label>
          <label className="flex items-center gap-2">
            <input type="checkbox" checked={hiddenBug} onChange={(e) => setHiddenBug(e.target.checked)} />
            Bug que les tests n&apos;attrapent pas (visible seulement dans le navigateur)
          </label>
          <label className="flex items-center gap-2">
            <input type="checkbox" checked={askRule} onChange={(e) => setAskRule(e.target.checked)} />
            Règle ask : Bash(npx vercel*)
          </label>
          <label className="flex items-center gap-2">
            <input type="checkbox" checked={autoMode} onChange={(e) => setAutoMode(e.target.checked)} />
            Mode auto (sans lui : Manual)
          </label>
        </div>

        {prompt && (
          <div className="rounded-xl bg-amber-900 p-3 text-sm">
            <p>Claude veut lancer : <code>{prompt}</code></p>
            <div className="mt-2 flex gap-2">
              <button type="button" onClick={() => answerPrompt(false)} className="rounded bg-white px-3 py-1 text-black">Refuser</button>
              <button type="button" onClick={() => answerPrompt(true)} className="rounded bg-gray-700 px-3 py-1">Autoriser</button>
            </div>
          </div>
        )}

        <ul className="space-y-2">
          {deployments.map((d) => (
            <li key={d.id} className="rounded-xl bg-gray-900 p-3 text-sm">
              <p>
                <strong>{d.id}</strong> v{d.version} {d.target === 'Preview' ? 'Aperçu' : 'Production'}
                {d.id === current && <span className="ml-2 text-green-400">sur le domaine</span>}
              </p>
              <p className="text-xs text-gray-400">NEXT_PUBLIC_AUDIO_BASE_URL = {ENV[d.target]}</p>
              {d.target === 'Preview' && (
                <div className="mt-2 flex gap-2">
                  <button type="button" onClick={() => checkPreview(d)} disabled={d.checked} className="rounded bg-gray-700 px-2 py-1 disabled:opacity-40">
                    {d.checked ? 'Vérifié' : 'Vérifier dans le navigateur'}
                  </button>
                  <button type="button" onClick={() => promote(d)} disabled={!d.checked} className="rounded bg-green-700 px-2 py-1 disabled:opacity-40">
                    Promote to Production
                  </button>
                </div>
              )}
            </li>
          ))}
        </ul>

        <div className="rounded-xl bg-black p-3 font-mono text-xs text-green-400">
          <p className="text-gray-400">Journal de bord (le plus récent en haut) :</p>
          {log.map((line, i) => <p key={i}>{line}</p>)}
        </div>
      </div>
    </div>
  );
}

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. Le projet Sea Shanty Sounds a déjà un premier déploiement sur Vercel. Qu'est-ce qui crée un déploiement d'aperçu ?

  2. 2. Où va la valeur de production de NEXT_PUBLIC_AUDIO_BASE_URL, et que contient le dépôt ?

Voici 2 des 3 questions de cette leçon. Réponds aux autres dans le jeu.

Tâches pratiques dans le jeu

  • Clique dans l'ordre

    Clique pour construire la règle ask qui demande ton accord à chaque commande npx vercel :

  • Tri vertical

    La production a un bug. Ordonne les étapes du repli :

  1. QuestionAperçu ou production
  2. QuestionVariables d'environnement sur Vercel
  3. Clique dans l'ordreLa règle ask pour Vercel
  4. Remets dans l'ordrePlan de repli après un mauvais déploiement
  5. QuestionImages d'un serveur externe dans next.config.ts

Articles utiles