Kurs vibe coding z Claude Code · Moduł 11: Klon Spotify
Wyszukiwarka i polecenia: najpierw zwiad, potem zmiany
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
- Zakładka bez sekcji. Typowy błąd agenta to dwa warunki
tab === "tracks"itab === "artists"zamiast pięciu, bo przepisał dwa przypadki z pięciu. U nas taka wersja przeszła lint itsc. 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ę. - Wyścig odpowiedzi. Wersja bez
controller.abort()przeszła lint itsc, 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 plikuclearTimeout(iabort(: oba mają stać wreturnefektu. - Jedna kopia danych. Wyszukaj w projekcie
mocki[...]. Agent bez zwiadu potrafi wołaćmockTracksimockAlbums, których nikt nie zdefiniował, albo zostawićtracks: [...]w miejscu danych. Po zwiadzie dane mają jedno źródło,lib/catalog.ts. - 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. Po co wyszukiwarka czeka 300 ms przed zapytaniem do serwera?
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
Zadania po tej lekcji
- PytanieOpóźnienie wyszukiwania
- PytaniePuste kategorie w wynikach
- Kliknij w kolejnościZapytanie z sygnałem przerwania
- Kliknij w kolejnościZbuduj timer opóźnienia
- Ułóż w kolejnościWynik pasuje do pytania
- Zadanie z kodemPraktyka: Search page
- PytanieZwiad z Explore
- PytanieReguła podobnych szant
- Ułóż w kolejnościPrzepływ wyszukiwania z opóźnieniem
- Ułóż w kolejnościFunkcja similarTracks
- Kliknij w kolejnościZbuduj czyszczenie timera
- PytaniePo co abort() w sprzątaniu
- Ułóż w kolejnościPrzerwanie to nie awaria
- Ułóż w kolejnościKolejność pracy nad wyszukiwarką
- Zadanie z kodemPraktyka: Browse categories
- PytanieZakładki, których nie da się zgubić