Kurs vibe coding z Claude Code · Moduł 11: Klon Spotify

Wdrożenie: podgląd robi Claude, produkcję zatwierdzasz Ty

8 min czytania
W tej lekcji13

Sea Shanty Sounds działa na Twoim komputerze ale załoga chce słuchać szant w porcie, na telefonach. Trzeba wypłynąć: zbudować aplikację na serwerze i dać jej adres w internecie. To jest wdrożenie, po angielsku deployment. Claude Code zrobi je w minutę i właśnie to jest niebezpieczne. Agent pracuje szybciej, niż czytasz, a wdrożenie produkcyjne widzą od razu wszyscy użytkownicy.

Czego się nauczysz

  • odróżnić wdrożenie podglądu od produkcyjnego i wiedzieć, kiedy powstaje które;
  • trzymać wartości zmiennych na platformie, a w repozytorium tylko .env.example;
  • wpuścić obrazy z zewnętrznego serwera przez images.remotePatterns w next.config.ts;
  • zapisać skill /deploy, który uruchamiasz tylko Ty i który wdraża tylko podgląd;
  • dodać regułę ask dla komend wdrożeniowych i wiedzieć, co z produkcją robi tryb auto;
  • promować podgląd na produkcję własną ręką i mieć plan odwrotu.

Co może pójść źle

Trzy rzeczy toną najczęściej. Sekret ląduje w repozytorium albo w kodzie wysyłanym do przeglądarki. Nowa wersja psuje stronę wszystkim naraz. Agent wdraża coś, o czym nie wiesz, bo "chciał sprawdzić, czy działa". Każda z nich dostaje w tej lekcji swój zamek.

Podgląd i produkcja

W kursie wdrażamy na Vercel. Jego dokumentacja opisuje trzy środowiska: lokalne, podgląd (Preview) i produkcję (Production). Podgląd to wersja do sprawdzenia pod osobnym adresem, która nie rusza strony głównej. Powstaje, gdy wypchniesz gałąź inną niż produkcyjna, otworzysz pull request albo uruchomisz vercel bez flagi --prod. Produkcja powstaje z gałęzi produkcyjnej, zwykle main, albo z vercel --prod. Jest jeden wyjątek, o którym agent chętnie zapomina: pierwsze wdrożenie nowego projektu jest zawsze produkcyjne, także bez --prod i z innej gałęzi.

Polecenie: przygotuj, nie wdrażaj

Polecenie dla Claude Code:

Przygotuj Sea Shanty Sounds do wdrożenia na Vercel. Nie wdrażaj.
1. Okładki albumów z images.unsplash.com w odtwarzaczu przez
   next/image, a w next.config.ts images.remotePatterns tylko dla
   tego hosta.
2. Adres folderu z nagraniami z NEXT_PUBLIC_AUDIO_BASE_URL, lokalnie
   domyślnie /audio.
3. .env.example z nazwami zmiennych, które czyta kod, bez wartości.
   Sprawdź, że Git go nie ignoruje.
Na koniec komendy sprawdzające z CLAUDE.md i git status --short.

"Nie wdrażaj" stoi na początku celowo. Według dokumentacji trybu auto granica, którą wypowiesz w rozmowie, działa dla klasyfikatora jak zakaz, dopóki jej nie zdejmiesz.

Co napisał Claude: zmienna zamiast adresu

Sea Shanty Sounds nie ma dziś ani jednego sekretu. Ma za to wartość, która różni się między środowiskami: adres folderu z nagraniami. Otwórz w Cursorze lib/catalog.ts:

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

?? bierze prawą stronę, gdy lewa nie istnieje, więc lokalnie nagrania dalej idą z public/audio. Przedrostek NEXT_PUBLIC_ znasz z lekcji 8_4: Next.js wpisuje taką wartość do kodu dla przeglądarki w chwili budowania. Zbudowaliśmy projekt z ustawioną zmienną i w pliku z .next/static/chunks stanęło let o="https://szanty.example.test/audio". Dla publicznego adresu to w porządku, dla klucza nigdy. Obok kodu Claude zapisał .env.example:

# Adres folderu z nagraniami. Lokalnie puste: aplikacja bierze /audio z public/.
# Na Vercelu ustaw osobno dla Preview i Production.
NEXT_PUBLIC_AUDIO_BASE_URL=

Plik pokazuje nazwy, nigdy wartości. Pułapkę z lekcji 8_5 Claude obszedł sam: dopisał do .gitignore linię !.env.example, a git status --short pokazał nowy plik.

Wartości wpisujesz na platformie. Według dokumentacji Vercela w projekcie wybierasz w bocznym menu Environment Variables, podajesz nazwę, zaznaczasz środowiska (Production, Preview, Development) i typ: Config zostaje czytelny dla uprawnionych osób, a Secret po zapisaniu da się tylko nadpisać. Zmiana działa wyłącznie dla nowych wdrożeń, więc po niej trzeba wdrożyć jeszcze raz.

Co napisał Claude: obrazy z zewnętrznego serwera

Odtwarzacz pokazuje okładkę przez komponent Image z lekcji 3_1, a adres okładki stoi w danych albumu. next/image przepuszcza zdjęcie przez optymalizator na Twoim serwerze, więc Next.js musi wiedzieć, z jakich hostów wolno je pobierać. Otwórz next.config.ts:

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

Wpis wpuszcza tylko https, tylko ten host, dowolną ścieżkę (/**) i adresy bez parametrów (search: ""). Sprawdziliśmy to po npm run build i npm start: okładka z images.unsplash.com wróciła z optymalizatora z kodem 200, a ten sam adres z ?w=1280, adres po http i zdjęcie z innego hosta dostały 400 z komunikatem "url" parameter is not allowed. Bez tego wpisu npm run dev oddał stronę z błędem 500 i komunikatem hostname "images.unsplash.com" is not configured under images.

Typowy błąd agenta to opcja ze starych poradników, images: { domains: ["images.unsplash.com"] }. U nas npx tsc --noEmit i npm run lint nic nie powiedziały, a build przeszedł z ostrzeżeniem, że images.domains jest przestarzałe na rzecz images.remotePatterns. Dokumentacja Next.js wyjaśnia, że domains nie umie ograniczyć protokołu, portu ani ścieżki. Ostrzeżenie w buildzie czytasz tak samo uważnie jak błąd.

Skill /deploy: tylko Ty podnosisz kotwicę

Skille poznałeś w lekcji 6_1, a pole disable-model-invocation było tam przy formularzu. Tutaj jest najważniejsze.

Polecenie dla Claude Code:

Zapisz skill /deploy w .claude/skills/deploy/. Tylko ja mogę go
uruchomić. Skill sprawdza, że projekt jest połączony z Vercelem,
uruchamia komendy sprawdzające z CLAUDE.md, zatrzymuje się przy
niezacommitowanych zmianach i wdraża wyłącznie podgląd przez
npx vercel deploy. Żadnego --prod, --temporary ani promote.

Otwórz .claude/skills/deploy/SKILL.md. Nagłówek wygląda tak:

---
name: deploy
description: Wdraża Sea Shanty Sounds na Vercel jako wersję podglądu (preview). Nigdy nie wdraża produkcji.
disable-model-invocation: true
---

Dokumentacja skilli podaje wdrożenie jako modelowy przykład tego pola: nie chcesz, żeby Claude wdrażał dlatego, że kod wygląda na gotowy. Jeśli Claude spróbuje uruchomić skill, choć w Twojej wiadomości nie ma /deploy, Claude Code zablokuje wywołanie. Pod nagłówkiem stoją kroki:

1. Sprawdź, czy istnieje katalog .vercel (projekt połączony przez vercel link). Jeśli go nie ma, zatrzymaj się: pierwsze wdrożenie nowego projektu na Vercelu zawsze trafia na produkcję, więc łączy i wdraża je kapitan.
2. Uruchom wszystkie komendy z sekcji "Komendy sprawdzające" w CLAUDE.md. Jeśli któraś nie przechodzi, zatrzymaj się i pokaż wynik.
3. Uruchom git status --short. Jeśli są niezacommitowane zmiany, zatrzymaj się i zapytaj.
4. Wdróż podgląd jedną komendą: npx vercel deploy. Bez --prod, bez --environment, bez --temporary, bez vercel promote.
5. Pokaż adres podglądu z wyniku komendy i listę rzeczy do sprawdzenia w przeglądarce: odtwarzacz, okładki albumów, wyszukiwarka.

Katalog .vercel tworzy vercel link. W niepołączonym projekcie npx vercel deploy --dry odpowiedział u nas Error: Project is not linked. i radą, żeby najpierw uruchomić vercel link. Zakaz --temporary też ma powód: według dokumentacji Vercela ta flaga wdraża bez konta i zawsze na produkcję, a Vercel poleca ją między innymi wtedy, gdy wdraża agent.

Pasy bezpieczeństwa: reguła ask

Skill pilnuje, co Claude zrobi na Twoje polecenie. Reguła w .claude/settings.json pilnuje każdej komendy, także wydanej poza skillem:

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

deny znasz z lekcji 8_4 i 8_5. ask każe Claude Code zapytać Cię o zgodę przy każdej pasującej komendzie, a dokumentacja uprawnień mówi, że takie pytanie pojawia się także w trybie auto. Brak spacji przed gwiazdką jest celowy: Bash(npx vercel*) łapie też npx vercel@latest deploy. Dwie reguły są potrzebne, bo npx nie należy do nakładek, które Claude Code zdejmuje przed dopasowaniem. Trzecia pilnuje Gita: gdy Vercel jest połączony z repozytorium, push na main to wdrożenie produkcyjne, a klasyfikator trybu auto domyślnie przepuszcza push na każdą gałąź Twojego repozytorium. Reguła dopasowuje tekst komendy, więc nie jest granicą bezpieczeństwa: sh -c z tą samą komendą jej nie dotyczy.

Tryb auto i produkcja

Według dokumentacji klasyfikator trybu auto domyślnie blokuje między innymi wdrożenia produkcyjne i migracje. To ostatnia linia obrony, nie pierwsza. Granica wypowiedziana w rozmowie może zniknąć przy kompakcji rozmowy, a dokumentacja sama radzi regułę deny, gdy potrzebujesz gwarancji. Dlatego produkcja nie jest krokiem Claude, tylko Twoim.

Produkcję promujesz Ty

/deploy kończy się adresem podglądu. Otwierasz go w przeglądarce i klikasz to, co kliknie załoga: Graj, okładki, wyszukiwarkę. Dopiero potem w panelu Vercela otwierasz Deployments, przy wybranym wdrożeniu menu z trzema kropkami i Promote to Production. Dokumentacja ostrzega, że promocja podglądu buduje aplikację od nowa ze zmiennymi produkcji. Tę samą promocję zrobi vercel promote <adres> we własnym terminalu, poza sesją Claude. Według dokumentacji Vercel buduje nowe projekty na najnowszym Node.js LTS, jakie oferuje (stan na listopad 2026: 26.x). Gdy testujesz lokalnie na innej wersji, przypnij ją w polu engines w package.json.

Plan odwrotu

Zanim promujesz, wiesz, dokąd zawrócisz. Instant Rollback w panelu (kafelek wdrożenia produkcyjnego na stronie projektu) albo vercel rollback przepina domeny na wcześniejsze wdrożenie bez budowania od nowa, więc zmienne zostają takie, jakie miało tamto wdrożenie. Po cofnięciu Vercel wyłącza automatyczne przypisywanie domen produkcyjnych: nowe pushe na main nie trafią na stronę, dopóki nie promujesz któregoś wdrożenia.

Przegląd kapitana

  1. Skill. W nagłówku /deploy stoi disable-model-invocation: true, a w krokach nie ma --prod, --temporary ani promote.
  2. Sekrety. Wyszukaj w projekcie NEXT_PUBLIC_: trafienia to tylko publiczne adresy. git status pokazuje .env.example, a .env.local nie.
  3. Obrazy. next.config.ts ma remotePatterns, nie domains, a build nie wypisuje ostrzeżeń.
  4. Pytanie o zgodę. Poproś Claude o npx vercel --version: Claude Code ma zapytać o zgodę. Typowy błąd agenta to wdrożenie "dla sprawdzenia" przez vercel --prod albo --temporary; reguła ask zatrzymuje je, zanim ruszą.

Następny krok

Poproś o commit, na przykład "Okładki, .env.example, skill /deploy i reguły ask". Pierwsze wdrożenie zrób sam, bo i tak będzie produkcyjne: zaimportuj repozytorium w panelu Vercela albo uruchom npx vercel login i npx vercel we własnym terminalu. Każde kolejne zaczyna /deploy, a kończy Twoje kliknięcie. W edytorze poniżej czeka symulacja tego rejsu: wdróż podgląd, sprawdź go, promuj, a potem zepsuj wersję i cofnij ją jednym przyciskiem.

Pamiętaj: kapitan podnosi kotwicę własną ręką, choćby załoga była najlepsza, i przed wyjściem z portu wie, do którego zawinie, gdy zerwie się sztorm.

Kod do tej lekcji: App.jsx
// Rejs wdrożenia w symulacji: podgląd, promocja, cofnięcie i agent, który chce "tylko sprawdzić"
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 wdrożenia na domenie produkcyjnej
  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;
  }

  // Kapitan: vercel link i pierwsze wdrożenie (zawsze produkcyjne)
  function firstDeploy() {
    const d = addDeployment('Production', false);
    setCurrent(d.id);
    say(`${d.id}: pierwsze wdrożenie nowego projektu trafiło na produkcję`);
  }

  // /deploy: komendy sprawdzające, potem tylko podgląd
  function runDeploySkill() {
    if (!linked) {
      say('/deploy: brak katalogu .vercel, zatrzymuję się. Połącz projekt i wdróż pierwszy raz sam.');
      return;
    }
    if (brokenCode) {
      say('/deploy: npm run test -- --run: 2 failed. Zatrzymuję się, nic nie wdrażam.');
      return;
    }
    const d = addDeployment('Preview', hiddenBug);
    say(`/deploy: testy, lint, typy i build zielone. Podgląd ${d.id} gotowy.`);
  }

  function checkPreview(preview) {
    setDeployments((list) => list.map((d) => (d.id === preview.id ? { ...d, checked: true } : d)));
    say(preview.broken
      ? `${preview.id}: w przeglądarce okładki się nie ładują, choć testy były zielone`
      : `${preview.id}: w przeglądarce gra, okładki i wyszukiwarka działają`);
  }

  // Promote to Production: nowy build ze zmiennymi produkcji
  function promote(preview) {
    const d = addDeployment('Production', preview.broken);
    setCurrent(d.id);
    setAutoAssign(true);
    say(`Promote to Production: ${preview.id} zbudowany od nowa jako ${d.id} ze zmiennymi Production`);
  }

  function shipBrokenToProduction() {
    const d = addDeployment('Production', true);
    setCurrent(d.id);
    say(`${d.id}: na produkcję weszła wersja z błędem, której nikt nie sprawdził`);
  }

  // Instant Rollback: domeny wracają na poprzednie wdrożenie produkcyjne, bez budowania
  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: nie ma wcześniejszego wdrożenia produkcyjnego.');
      return;
    }
    setCurrent(previous.id);
    setAutoAssign(false);
    say(`Instant Rollback: domena wskazuje ${previous.id}. Automatyczne przypisywanie domen wyłączone.`);
  }

  // Agent chce "dla sprawdzenia" uruchomić wdrożenie produkcyjne
  function agentProdDeploy() {
    const command = 'npx vercel deploy --prod';
    if (askRule) {
      setPrompt(command);
      say(`Reguła ask: Claude Code pyta o zgodę na ${command}`);
    } else if (autoMode) {
      say(`Tryb auto: klasyfikator zablokował ${command} (wdrożenie produkcyjne)`);
    } else {
      setPrompt(command);
      say(`Tryb Manual: Claude Code pyta o zgodę na ${command}`);
    }
  }

  function answerPrompt(allow) {
    if (allow) {
      shipBrokenToProduction();
    } else {
      say('Odmówiłeś. Produkcja bez zmian.');
    }
    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">Domena produkcyjna</p>
          {live ? (
            <p className={live.broken ? 'text-red-400' : 'text-green-400'}>
              {live.id} (v{live.version}) {live.broken ? 'psuje odtwarzacz' : 'gra poprawnie'}
            </p>
          ) : (
            <p className="text-gray-500">Jeszcze nic nie wypłynęło.</p>
          )}
          <p className="mt-1 text-xs text-gray-400">
            Automatyczne przypisywanie domen: {autoAssign ? 'włączone' : 'wyłączone po cofnięciu'}
          </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">
            Kapitan: vercel link i pierwsze wdrożenie
          </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: wdrożę produkcję dla sprawdzenia
          </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)} />
            Kod z błędem (testy czerwone)
          </label>
          <label className="flex items-center gap-2">
            <input type="checkbox" checked={hiddenBug} onChange={(e) => setHiddenBug(e.target.checked)} />
            Błąd, którego testy nie łapią (widać go dopiero w przeglądarce)
          </label>
          <label className="flex items-center gap-2">
            <input type="checkbox" checked={askRule} onChange={(e) => setAskRule(e.target.checked)} />
            Reguła ask: Bash(npx vercel*)
          </label>
          <label className="flex items-center gap-2">
            <input type="checkbox" checked={autoMode} onChange={(e) => setAutoMode(e.target.checked)} />
            Tryb auto (bez niego: Manual)
          </label>
        </div>

        {prompt && (
          <div className="rounded-xl bg-amber-900 p-3 text-sm">
            <p>Claude chce uruchomić: <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">Odmów</button>
              <button type="button" onClick={() => answerPrompt(true)} className="rounded bg-gray-700 px-3 py-1">Zezwól</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' ? 'Podgląd' : 'Produkcja'}
                {d.id === current && <span className="ml-2 text-green-400">na domenie</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 ? 'Sprawdzony' : 'Sprawdź w przeglądarce'}
                  </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">Dziennik rejsu (najnowsze na górze):</p>
          {log.map((line, i) => <p key={i}>{line}</p>)}
        </div>
      </div>
    </div>
  );
}

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Projekt Sea Shanty Sounds ma już pierwsze wdrożenie na Vercelu. Co tworzy wdrożenie podglądu?

  2. 2. Gdzie trafia produkcyjna wartość NEXT_PUBLIC_AUDIO_BASE_URL, a co jedzie w repozytorium?

To 2 z 3 pytań do tej lekcji. Pozostałe rozwiążesz w grze.

Zadania praktyczne w grze

  • Klikanie w kolejności

    Kliknij elementy, aby zbudować regułę ask, która pyta o zgodę przy każdej komendzie npx vercel:

  • Układanie w pionie

    Na produkcji wyszedł błąd. Uporządkuj kroki odwrotu:

  1. PytaniePodgląd czy produkcja
  2. PytanieZmienne środowiskowe na Vercelu
  3. Kliknij w kolejnościReguła ask dla Vercela
  4. Ułóż w kolejnościPlan odwrotu po złym wdrożeniu
  5. PytanieObrazy z zewnętrznego serwera w next.config.ts

Przydatne artykuły