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

Wyszukiwarka i polecenia: najpierw zwiad, potem zmiany

7 min czytania
W tej lekcji10

Katalog Sea Shanty Sounds rośnie a nikt nie będzie przewijał setek szant, żeby znaleźć tę o krakenie. Załoga potrzebuje wyszukiwarki z zakładkami i małego okienka "Podobne", które podsunie coś w tym samym klimacie. Projekt ma już za sobą dwie lekcje kodu, więc zanim Claude cokolwiek zmieni, musi wiedzieć, co już jest. Agent, który tego nie sprawdzi, chętnie zakłada drugą kopię danych w nowym pliku albo woła funkcje, których nikt nie napisał.

Czego się nauczysz

  • wysłać subagenta Explore na zwiad, zanim Claude zmieni kod;
  • przeczytać wyszukiwanie z opóźnieniem 300 ms, które sprząta po sobie;
  • sprawdzić, że starsza odpowiedź serwera nie nadpisze nowszej;
  • dopilnować, żeby każda zakładka miała swoją sekcję albo pusty stan.

Zwiad z Explore

Wbudowanego subagenta Explore znasz z lekcji 5_4. Dokumentacja Claude Code opisuje go jako pomocnika do szukania plików i czytania kodu, który ma tylko narzędzia do odczytu (Write i Edit są dla niego zablokowane) i startuje bez Twojego CLAUDE.md, żeby zwiad był szybki i tani. To inne narzędzie niż /btw z lekcji 10_1. Dokumentacja ujmuje to krótko: /btw pytasz o to, co Claude już wie z rozmowy, a subagenta wysyłasz, żeby dowiedział się czegoś nowego.

Polecenie dla Claude Code (zwiad):

Użyj subagenta Explore. Nie zmieniaj żadnych plików. Zanim dodamy
wyszukiwarkę, ustal: gdzie leżą dane katalogu (utwory, albumy,
artyści, playlisty) i które pliki je importują, czy w projekcie jest
już funkcja formatująca czas albo porównująca tekst, jakie typy
opisują utwór, album, artystę i playlistę. Odpowiedz w 5 punktach,
przy każdym ścieżka pliku.

Raport sprawdzasz w Cursorze, zanim cokolwiek zlecisz. Po lekcjach 10_1 i 10_2 dane leżą w jednym pliku, lib/catalog.ts, a importują go trzy strony: app/page.tsx, app/playlisty/page.tsx i app/playlisty/[id]/page.tsx oraz testy. Wyszukaj w projekcie (Cmd+Shift+F na Macu, Ctrl+Shift+F na Windowsie) lib/catalog i porównaj trafienia z raportem. Raport, który pomija plik albo wymienia plik, którego nie ma, odsyłasz z prośbą o poprawkę. Dobry raport wspomni też o formatTime w lib/format.ts, a o funkcji do porównywania tekstu powie, że jej nie ma.

Polecenie: wyszukiwarka

Polecenie dla Claude Code (budowa):

Na podstawie zwiadu dodaj wyszukiwarkę. lib/search.ts: searchCatalog
na danych z @lib/catalog.ts, bez drugiej kopii danych, bez polskich
znaków ("piesn" znajduje "Pieśń"). Route Handler app/api/search,
components/SearchPage.tsx i strona /szukaj: pole z opóźnieniem 300 ms
i zakładki Wszystko, Utwory, Albumy, Artyści, Playlisty.
Będzie gotowe, gdy:
1. przy szybkim wpisaniu "szan" serwer dostaje jedno zapytanie;
2. starsza odpowiedź nie nadpisuje nowszej (test z udawanym fetch);
3. każda zakładka pokazuje swoją sekcję albo napis o braku wyników;
4. lint, typy, testy i build przechodzą. Pokaż komendy i wyniki.

Warunek 2 opisuje klasyczny wyścig. Wpisujesz "hymn", serwer zaczyna szukać, zmieniasz zdanie na "kraken". Jeśli pierwsza odpowiedź przyjdzie później niż druga, na ekranie zostaną wyniki dla "hymn", choć w polu stoi "kraken".

Co napisał Claude: szukanie bez ogonków

Otwórz w Cursorze lib/search.ts. Tekst z pola i tekst z katalogu przechodzą przez tę samą funkcję:

export function normalize(text: string): string {
  return text
    .toLowerCase()
    .replace(/ł/g, "l")
    .normalize("NFD")
    .replace(/[\u0300-\u036f]/g, "");
}

normalize("NFD") rozkłada literę z ogonkiem na literę i osobny znak ogonka, a ostatnia linia usuwa te znaki. Litera "ł" się tak nie rozkłada, dlatego stoi osobno na początku. U nas test zwrócił "piesn lodzi" dla "Pieśń Łodzi". searchCatalog zwraca zawsze wszystkie cztery listy, także puste: dla "szan" jeden utwór, jedną playlistę i dwie puste listy albumów i artystów.

Co napisał Claude: 300 ms i sprzątanie

Otwórz components/SearchPage.tsx. Opóźnienie, po angielsku debounce, to timer, który czeka, aż przestaniesz pisać na 300 ms, i dopiero wtedy pyta serwer:

useEffect(() => {
  if (!q) return;
  const controller = new AbortController();
  const timer = setTimeout(async () => {
    try {
      const res = await fetch(`/api/search?q=${encodeURIComponent(q)}`, { signal: controller.signal });
      if (!res.ok) throw new Error(`HTTP ${res.status}`);
      setResult({ query: q, data: await res.json() });
    } catch {
      if (!controller.signal.aborted) setResult({ query: q, data: null });
    }
  }, 300);
  return () => {
    clearTimeout(timer);
    controller.abort();
  };
}, [q]);

q to tekst z pola bez spacji na końcach, więc spacja dopisana na końcu nie wysyła nowego zapytania. Każda litera zmienia q, a React przed kolejnym uruchomieniem efektu woła sprzątanie poprzedniego. Sprzątanie robi dwie rzeczy na dwa różne momenty. clearTimeout kasuje timer, który jeszcze czeka, więc litery wpisane szybciej niż co 300 ms nie dochodzą do serwera. abort() przerywa zapytanie, które już wyszło: według MDN fetch kończy się wtedy błędem AbortError, a warunek w catch nie traktuje go jak awarii. setResult stoi w funkcji timera, a nie wprost w ciele efektu, więc reguła lintera react-hooks/set-state-in-effect z wcześniejszych lokacji nie ma zastrzeżeń.

Co napisał Claude: wynik pasuje do pytania

Wynik pamięta, o co pytał, a napis "Szukam..." wynika z porównania, bez osobnego stanu ładowania:

const current = q && result?.query === q ? result : null;

Jeśli w polu stoi "kraken", a ostatni wynik dotyczy "hymn", current jest puste i strona pokazuje "Szukam...". data: null w wyniku znaczy, że zapytanie się nie udało, i wtedy pojawia się komunikat z prośbą o ponowną próbę.

Co napisał Claude: zakładki, których nie da się zgubić

Każda sekcja ma swoją funkcję rysującą w jednym obiekcie:

const RENDER: Record<Section, (r: SearchResults) => React.ReactNode> = {
  tracks: (r) => r.tracks.map((t) => <li key={t.id}>{t.title}, {t.artist.name}</li>),
  albums: (r) => r.albums.map((a) => <li key={a.id}>{a.title} ({a.year})</li>),
  artists: (r) => r.artists.map((a) => <li key={a.id}>{a.name}</li>),
  playlists: (r) => r.playlists.map((p) => <li key={p.id}>{p.name}</li>),
};

Section to unia czterech nazw sekcji, a Record wymaga funkcji dla każdej z nich, jak napisy układów duetu w lekcji 9_3. U nas usunięcie linii albums skończyło się błędem TS2741 z treścią Property 'albums' is missing in type. Zakładka Wszystko rysuje cztery sekcje, każda inna jedną. Sekcja z pustą listą pokazuje "Brak wyników w tej kategorii.", więc kliknięcie Albumy przy "szan" daje napis, a nie pustą stronę.

Co napisał Claude: podobne szanty

Pod odtwarzaczem stoi okienko "Podobne". Nasz klon nie udaje algorytmów dużych serwisów: polecenia to jedna jawna reguła w lib/recommend.ts, którą da się przetestować:

export function similarTracks(track: Track, catalog: Track[], limit = 3): Track[] {
  return catalog
    .filter((t) => t.genre === track.genre && t.id !== track.id)
    .slice(0, limit);
}

Reguła brzmi: utwory tego samego gatunku, bez tego, który gra, najwyżej trzy. Kolejność ma znaczenie: najpierw filter, potem slice, bo odwrotnie z katalogu wzięłyby się trzy pierwsze utwory dowolnego gatunku. U nas "Pieśń krakena" jest jedyną balladą, więc test dostał pustą listę, a okienko pokazało "Brak innych utworów w gatunku ballada.".

Przegląd kapitana

  1. Zakładka bez sekcji. Typowy błąd agenta to dwa warunki tab === "tracks" i tab === "artists" zamiast pięciu, bo przepisał dwa przypadki z pięciu. U nas taka wersja przeszła lint i tsc. Test z warunku 3 oblał: Unable to find an accessible element with the role "region" and name "Albumy". Wpisz "szan" i kliknij każdą zakładkę.
  2. Wyścig odpowiedzi. Wersja bez controller.abort() przeszła lint i tsc, a test z warunku 2 zgłosił Unable to find an element with the text: Pieśń krakena, Czarna Mary: spóźniona odpowiedź dla "hymn" nadpisała wynik dla "kraken", a strona utknęła na napisie "Szukam...". Wyszukaj w pliku clearTimeout( i abort(: oba mają stać w return efektu.
  3. Jedna kopia danych. Wyszukaj w projekcie mock i [...]. Agent bez zwiadu potrafi wołać mockTracks i mockAlbums, których nikt nie zdefiniował, albo zostawić tracks: [...] w miejscu danych. Po zwiadzie dane mają jedno źródło, lib/catalog.ts.
  4. Dowód w przeglądarce. Otwórz /szukaj, w narzędziach deweloperskich zakładkę Network i wpisz szybko "szan". U nas poszło jedno zapytanie, q=szan.

Następny krok

Przed commitem uruchom /code-review z lekcji 2_9: recenzent w świeżym subagencie nie widział, jak powstawał efekt, więc spojrzy na niego bez Waszego rozumowania. Każde znalezisko sprawdzasz jak hipotezę, zanim poprosisz o poprawkę wąskim poleceniem. Wyszukiwarka i okienko "Podobne" nie dzielą plików, więc na większym okręcie mogłyby powstać równolegle w dwóch worktree, jak w lekcji 9_2. Gdy recenzja i testy się zgadzają, poproś o commit, na przykład "Wyszukiwarka i podobne szanty".

W edytorze poniżej czeka wyszukiwarka z udawanym serwerem, który na krótsze zapytania odpowiada wolniej. Wpisz "pi", odczekaj pół sekundy, dopisz "eśń" i patrz na dziennik zapytań. Potem włącz błąd agenta bez abort() i powtórz to samo, a na koniec błąd z dwiema sekcjami zamiast czterech i kliknij zakładkę Albumy.

Zapamiętaj: kapitan najpierw wysyła zwiadowcę na ląd, a dopiero potem desant, a katalog bez zakładki "Albumy" to mapa bez wyspy, na którą właśnie płyniesz.

Kod do tej lekcji: App.jsx
// Wyszukiwarka w miniaturze: udawany serwer odpowiada wolniej na krótsze zapytania
import { useEffect, useState } from 'react';

const catalog = {
  tracks: [
    { id: 't1', title: 'Hymn piratów', artist: 'Kapitan Redbeard' },
    { id: 't2', title: 'Werble bitewne', artist: 'Czarna Mary' },
    { id: 't3', title: 'Szanta o wyspie', artist: 'Kapitan Redbeard' },
    { id: 't4', title: 'Pieśń krakena', artist: 'Czarna Mary' },
  ],
  albums: [
    { id: 'al1', title: 'Pieśni z pokładu', year: 1718 },
    { id: 'al2', title: 'Burza nad Tortugą', year: 1721 },
  ],
  artists: [
    { id: 'a1', name: 'Kapitan Redbeard' },
    { id: 'a2', name: 'Czarna Mary' },
  ],
  playlists: [{ id: 'p1', name: 'Szanty na wachtę' }],
};

const normalize = (text) => text.toLowerCase().replace(/ł/g, 'l').normalize('NFD').replace(/[\u0300-\u036f]/g, '');

function searchCatalog(query) {
  const q = normalize(query);
  const has = (text) => normalize(text).includes(q);
  return {
    tracks: catalog.tracks.filter((t) => has(t.title) || has(t.artist)),
    albums: catalog.albums.filter((a) => has(a.title)),
    artists: catalog.artists.filter((a) => has(a.name)),
    playlists: catalog.playlists.filter((p) => has(p.name)),
  };
}

// Udawany fetch: im krótsze zapytanie, tym dłużej czeka (1 litera: 1,5 s), i słucha sygnału abort
function fakeFetch(q, signal) {
  const delay = Math.max(200, 1750 - 250 * q.length);
  return new Promise((resolve, reject) => {
    const id = setTimeout(() => resolve(searchCatalog(q)), delay);
    signal.addEventListener('abort', () => {
      clearTimeout(id);
      reject(new DOMException('aborted', 'AbortError'));
    });
  });
}

const TABS = ['all', 'tracks', 'albums', 'artists', 'playlists'];
const SECTIONS = ['tracks', 'albums', 'artists', 'playlists'];
const LABELS = { all: 'Wszystko', tracks: 'Utwory', albums: 'Albumy', artists: 'Artyści', playlists: 'Playlisty' };
const RENDER = {
  tracks: (r) => r.tracks.map((t) => <li key={t.id}>{t.title}, {t.artist}</li>),
  albums: (r) => r.albums.map((a) => <li key={a.id}>{a.title} ({a.year})</li>),
  artists: (r) => r.artists.map((a) => <li key={a.id}>{a.name}</li>),
  playlists: (r) => r.playlists.map((p) => <li key={p.id}>{p.name}</li>),
};

export default function App() {
  const [query, setQuery] = useState('');
  const [tab, setTab] = useState('all');
  const [result, setResult] = useState(null);
  const [log, setLog] = useState([]);
  const [noAbort, setNoAbort] = useState(false);
  const [twoSections, setTwoSections] = useState(false);
  const q = query.trim();
  const note = (line) => setLog((l) => [line, ...l].slice(0, 10));

  useEffect(() => {
    if (!q) return;
    const controller = new AbortController();
    const timer = setTimeout(async () => {
      note(`wysłane: ${q}`);
      try {
        const data = await fakeFetch(q, controller.signal);
        note(`odpowiedź: ${q}`);
        setResult({ query: q, data });
      } catch {
        if (controller.signal.aborted) note(`przerwane: ${q}`);
      }
    }, 300);
    return () => {
      clearTimeout(timer);
      if (!noAbort) controller.abort(); // błąd agenta: bez abort() stare zapytanie dalej leci
    };
  }, [q, noAbort]);

  // Bez błędu agenta wynik musi pasować do pytania; z błędem pokazujemy ostatni, który przyszedł
  const current = noAbort ? result : q && result?.query === q ? result : null;
  const data = current?.data;
  const visible = twoSections
    ? SECTIONS.filter((s) => (s === 'tracks' || s === 'artists') && (tab === 'all' || tab === s))
    : tab === 'all' ? SECTIONS : [tab];

  return (
    <div className="min-h-screen bg-gray-950 p-4 text-white">
      <div className="mx-auto max-w-xl space-y-3">
        <input value={query} onChange={(e) => setQuery(e.target.value)} placeholder="Wpisz pi, odczekaj, dopisz eśń" className="w-full rounded-full bg-gray-800 px-4 py-2" />
        <div className="flex flex-wrap gap-2">
          {TABS.map((t) => (
            <button key={t} type="button" onClick={() => setTab(t)} className={`rounded-full px-3 py-1 text-sm ${tab === t ? 'bg-white text-black' : 'bg-gray-800'}`}>
              {LABELS[t]}
            </button>
          ))}
        </div>
        {q && !current && <p className="text-gray-400">Szukam...</p>}
        {current && <p className="text-xs text-gray-400">Wyniki dla: „{current.query}”, w polu: „{q}”</p>}
        {data && visible.map((s) => (
          <section key={s}>
            <h2 className="font-semibold">{LABELS[s]}</h2>
            {data[s].length === 0 ? <p className="text-sm text-gray-400">Brak wyników w tej kategorii.</p> : <ul className="text-sm">{RENDER[s](data)}</ul>}
          </section>
        ))}
        {data && visible.length === 0 && <p className="text-sm text-red-400">Pusta strona: ta zakładka nie ma sekcji.</p>}
        <div className="space-y-1 text-sm">
          <label className="flex items-center gap-2"><input type="checkbox" checked={noAbort} onChange={(e) => setNoAbort(e.target.checked)} /> Błąd agenta: bez abort()</label>
          <label className="flex items-center gap-2"><input type="checkbox" checked={twoSections} onChange={(e) => setTwoSections(e.target.checked)} /> Błąd agenta: tylko Utwory i Artyści</label>
        </div>
        <div className="rounded-xl bg-black p-3 font-mono text-xs text-green-400">
          <p className="text-gray-400">Dziennik zapytań (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. Po co wyszukiwarka czeka 300 ms przed zapytaniem do serwera?

  2. 2. Co zwraca searchCatalog("szan") dla kategorii, w której nic nie pasuje?

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

Zadania praktyczne w grze

  • Klikanie w kolejności

    Kliknij elementy, aby zbudować zapytanie do wyszukiwarki, które da się przerwać:

  • Klikanie w kolejności

    Kliknij elementy, aby zbudować opóźnione wyszukiwanie:

  • Układanie w poziomie

    Ułóż w jednej linii wybór wyniku, który pasuje do tekstu w polu:

  • Edytor kodu

    Search interface

  • Układanie w pionie

    Uporządkuj, co dzieje się, gdy dopisujesz literę w polu wyszukiwania:

  • Układanie w pionie

    Uporządkuj linie funkcji similarTracks:

  • Klikanie w kolejności

    Kliknij elementy, aby zbudować sprzątanie, które kasuje czekający timer:

  • Układanie w poziomie

    Ułóż w jednej linii obsługę błędu, która pomija przerwane zapytania:

  • Układanie w pionie

    Uporządkuj kroki pracy nad wyszukiwarką z lekcji:

  • Edytor kodu

    Music discovery interface

  1. PytanieOpóźnienie wyszukiwania
  2. PytaniePuste kategorie w wynikach
  3. Kliknij w kolejnościZapytanie z sygnałem przerwania
  4. Kliknij w kolejnościZbuduj timer opóźnienia
  5. Ułóż w kolejnościWynik pasuje do pytania
  6. Zadanie z kodemPraktyka: Search page
  7. PytanieZwiad z Explore
  8. PytanieReguła podobnych szant
  9. Ułóż w kolejnościPrzepływ wyszukiwania z opóźnieniem
  10. Ułóż w kolejnościFunkcja similarTracks
  11. Kliknij w kolejnościZbuduj czyszczenie timera
  12. PytaniePo co abort() w sprzątaniu
  13. Ułóż w kolejnościPrzerwanie to nie awaria
  14. Ułóż w kolejnościKolejność pracy nad wyszukiwarką
  15. Zadanie z kodemPraktyka: Browse categories
  16. PytanieZakładki, których nie da się zgubić

Przydatne artykuły