Kurs vibe coding z Claude Code · Moduł 2: Projekt Next.js z Claude Code
Pamięć projektu: AGENTS.md, CLAUDE.md i /init
W tej lekcji12
Ahoj! Mapa leży w SPEC.md. Zanim załoga ruszy do budowy, zawiesisz w kajucie regulamin okrętu: plik z zasadami, które Claude Code przeczyta na początku każdej sesji, także za miesiąc.
Problem: każda sesja zaczyna od zera
Po /clear albo jutro rano, w nowej sesji, Claude nie pamięta rozmowy. Nie wie, że Cache Components wyłączyłeś świadomie w lekcji 1_2, że po każdej zmianie chcesz zobaczyć wynik npm run build i że serwer deweloperski trzymasz w osobnym terminalu. Znów to tłumaczysz albo, gorzej, zapominasz. Wtedy Claude może zrobić coś rozsądnego ze swojego punktu widzenia, na przykład włączyć Cache Components, bo kreator proponuje je w ustawieniach zalecanych. Kod widzi, ale Twojej decyzji nie.
Na to jest pamięć projektu: pliki z instrukcjami, które Claude Code wczytuje na starcie każdej rozmowy. Piszesz je zwykłym tekstem, a trzymasz w repozytorium razem z kodem.
Co już masz: AGENTS.md
Kreator z lekcji 1_2 zostawił w projekcie plik AGENTS.md z instrukcjami dla agentów kodujących. Otwórz go w Cursorze. Cała jego treść siedzi między dwoma znacznikami:
<!-- BEGIN:nextjs-agent-rules -->
## This is NOT the Next.js you know
(ostrzeżenie i wskazówka, gdzie szukać dokumentacji)
<!-- END:nextjs-agent-rules --><!-- i --> otwierają i zamykają komentarz, którego nie widać po wyrenderowaniu pliku, a te dwa znaczniki oznaczają fragment należący do Next.js. W środku jest ostrzeżenie, że ta wersja Next.js może różnić się od tego, czego model nauczył się wcześniej, i polecenie, żeby przed pisaniem kodu czytać przewodnik z folderu node_modules/next/dist/docs/. Dokumentacja Next.js wyjaśnia, że w tym folderze leży dokumentacja dopasowana do zainstalowanej wersji, a next dev odtwarza blok i zmienia tylko tekst między znacznikami, resztę pliku zostawiając w spokoju.
Claude Code czyta AGENTS.md jako instrukcje projektu wtedy, gdy w folderze roboczym i folderach nad nim nie ma pliku CLAUDE.md ani CLAUDE.local.md. Na starcie sesji zobaczysz wtedy linię podobną do tej:
no CLAUDE.md found; AGENTS.md loaded: .../krakens-call/AGENTS.mdTo dowód, że ostrzeżenie Next.js trafia do każdej rozmowy. Jest też pułapka: gdy w projekcie pojawi się CLAUDE.md, Claude przestanie czytać AGENTS.md sam z siebie.
Import: jedna linia z @
Rozwiązaniem jest import. Linia z @ i ścieżką w pliku CLAUDE.md wczytuje wskazany plik razem z nim, a zaimportowany plik może importować kolejne, najwyżej cztery poziomy w głąb. Tu wystarczy jedna linia:
@AGENTS.mdPostaw ją na samej górze CLAUDE.md. Claude przeczyta wtedy najpierw zaimportowany plik, a potem Twoje zasady, i nic nie trzeba kopiować. Sam AGENTS.md się nie zmienia, więc Next.js dalej może odświeżać swój blok.
/init: pierwszy szkic
Komenda /init generuje startowy CLAUDE.md: Claude analizuje projekt i zapisuje komendy budowania, testów i konwencje, które znalazł. Gdy CLAUDE.md już istnieje, /init go nie nadpisuje, tylko proponuje poprawki. Wpisz w sesji w folderze krakens-call:
/initClaude poprosi o zgodę na zapis CLAUDE.md. Dobre praktyki Claude Code mówią wprost, że dalej praca polega głównie na usuwaniu linii. Przeczytaj plik w Cursorze i zaznacz w myślach wszystko, co Claude znalazłby w repozytorium sam: listę folderów, opis App Routera, wersje paczek z package.json.
Polecenie: zostaw to, czego nie widać w kodzie
Szkic skrócisz jednym poleceniem. Powiedz w nim, co ma zostać, co ma wylecieć i czego Claude nie znajdzie w żadnym pliku:
Polecenie dla Claude Code:
Skróć @CLAUDE.md do trzech części: komendy sprawdzające, pułapki
i decyzje. Na samej górze dodaj linię importu @AGENTS.md. Usuń opis
folderów i architektury, bo przeczytasz je z repozytorium. Pisz
zwykłymi zdaniami, bez wielkich liter. Do pułapek dopisz, że Cache
Components są wyłączone celowo, a do decyzji, że serwer npm run dev
uruchamiam sam w osobnym terminalu.Polecenie mówi, co zostaje, co wylatuje i dlaczego. Dwie ostatnie informacje to wiedza, której w kodzie nie ma: brak linii cacheComponents w next.config.ts nie mówi, że to decyzja, a nie przeoczenie.
Co napisał Claude: krótki CLAUDE.md
Otwórz CLAUDE.md w Cursorze. Twój będzie miał inne słowa, ale podobny kształt. Na górze stoją import i komendy:
@AGENTS.md
# Komendy sprawdzające
- Typy: npx tsc --noEmit
- Lint: npm run lint
- Build: npm run build, po każdym kroku planuTo same komendy, bez zdań w rodzaju "zawsze sprawdzaj typy". Dokumentacja tłumaczy, że Claude potrzebuje komendy, żeby sam sprawdzać swoją pracę w trakcie. Ta część niczego nie wymusza: podaje narzędzia, a o dowód nadal prosisz w poleceniu.
Pod komendami są pułapki i decyzje, czyli wiedza, której Claude nie wyczyta z plików projektu:
# Pułapki
- Cache Components są wyłączone celowo (w next.config.ts nie ma cacheComponents). Nie włączaj ich.
- Tailwind 4: konfiguracja w app/globals.css, bez pliku tailwind.config.js.
- Błędy typów naprawiaj u źródła, bez any i @ts-ignore.
# Decyzje
- Serwer npm run dev uruchamiam sam w osobnym terminalu, Ty go nie uruchamiasz.
- Plan strony głównej jest w pliku SPEC.md.Każda linia to coś, czego nie widać w kodzie, albo coś, co poprawiałeś już w tej lokacji: składnia Tailwinda 3 z lekcji 1_3 i wyciszanie typów z lekcji 1_4. SPEC.md stoi tu bez @, więc to wzmianka, a nie import: plan nie ładuje się do każdej rozmowy, a Claude otworzy go, gdy będzie potrzebny.
Czego nie wpisywać
Dobre praktyki Claude Code wymieniają rzeczy, które dziś tylko przeszkadzają:
- opis architektury i układu plików: Claude czyta repozytorium sam;
- WIELKIE LITERY i słowo WAŻNE: obecne modele wykonują zwykłe zdanie, a nadmiar nacisku sprawia, że regułę stosują przesadnie; jeśli linia ginie, plik jest za długi;
- wszystko "na wszelki wypadek": każda linia zabiera odrobinę uwagi Claude przy każdym zadaniu, potrzebna czy nie.
Dokumentacja pamięci zaleca jeszcze długość: poniżej 200 linii na plik. Rada kapitana: żadnych haseł ani kluczy, bo CLAUDE.md trafia do repozytorium razem z kodem.
Prośba, nie prawo
CLAUDE.md czyta model i sam decyduje, co z nim zrobić. Dokumentacja nazywa takie instrukcje kontekstem, a nie wymuszoną konfiguracją: Claude stosuje się do nich prawie zawsze, ale bez gwarancji. Zasadę, która nie może mieć wyjątków, egzekwuje sam program Claude Code, na przykład przez hook, czyli skrypt uruchamiany automatycznie przy wybranym zdarzeniu. Hooki poznasz w dalszych lokacjach. Na razie zapamiętaj podział: CLAUDE.md na wskazówki, hook na prawo bez wyjątków.
Notatki tylko dla Ciebie
Uwagi, których nie chcesz w repozytorium, na przykład "tłumacz mi każdą komendę Gita przed uruchomieniem", zapisz w pliku CLAUDE.local.md w głównym folderze projektu. Claude czyta go zaraz po CLAUDE.md. Plik nie może trafić do Gita, a .gitignore z kreatora go nie zna, więc poproś Claude o dopisanie do .gitignore jednej linii:
CLAUDE.local.mdOd teraz Git pomija Twoje notatki, a w Source Control nie zobaczysz tego pliku. Uwaga: CLAUDE.local.md też wyłącza samodzielne czytanie AGENTS.md, ale u nas załatwia to import na górze CLAUDE.md.
Dwa narzędzia na koniec. Gdy powiesz "zapamiętaj, że...", Claude zapisze to w auto memory, czyli w swoich notatkach na Twoim komputerze, poza projektem. Żeby coś trafiło do CLAUDE.md, powiedz wprost: "dopisz to do CLAUDE.md". Komenda /memory pokazuje listę plików pamięci, otwiera wybrany w edytorze i włącza albo wyłącza auto memory.
Sprawdzian: nowa sesja
Pamięć sprawdza się w rozmowie, która nie słyszała poprzedniej. Wyjdź z sesji komendą /exit i uruchom claude od nowa, bo pliki pamięci wczytują się na starcie sesji. Potem zapytaj:
Jakimi komendami sprawdzisz ten projekt po zmianie i czego nie wolno
Ci zmieniać w next.config.ts?Dobra odpowiedź wymienia trzy komendy z CLAUDE.md i Cache Components. Jeśli Claude zgaduje, uruchom /context all i sprawdź listę Memory files: CLAUDE.md musi na niej być. Brak pliku na liście oznacza, że Claude go nie widzi.
Przegląd kapitana
Zanim zrobisz commit, sprawdź w Source Control:
- Import: pierwsza linia
CLAUDE.mdto@AGENTS.md. - Długość: kilkanaście linii, daleko od 200.
- Test kodu: przy każdej linii pytasz, czy Claude znalazłby to w repozytorium; jeśli tak, linia wylatuje.
- Sekrety i balast: w diffie nie ma kluczy ani
CLAUDE.local.md, a.gitignorema nową linię.
Typowy błąd agenta przy tym zadaniu: przy skracaniu zostawia opis folderów "dla porządku" albo dopisuje reguły wielkimi literami. Wyłapiesz to w diffie, zanim zatwierdzisz zmianę.
Następny krok
Poproś o commit CLAUDE.md i .gitignore z opisem w rodzaju "CLAUDE.md: komendy sprawdzające i pułapki projektu". Plik będzie rósł powoli: dokumentacja radzi dopisywać linię wtedy, gdy Claude drugi raz popełnia ten sam błąd. W następnej lekcji zbudujesz landing page według planu, a w edytorze poniżej obejrzysz przykładowy CLAUDE.md, CLAUDE.local.md i fragment .gitignore.
Pamiętaj: CLAUDE.md to regulamin okrętu, który każda nowa załoga czyta przed wypłynięciem.
Kod do tej lekcji: CLAUDE.md
@AGENTS.md
# Komendy sprawdzające
- Typy: npx tsc --noEmit
- Lint: npm run lint
- Build: npm run build, po każdym kroku planu
# Pułapki
- Cache Components są wyłączone celowo (w next.config.ts nie ma cacheComponents). Nie włączaj ich.
- Tailwind 4: konfiguracja w app/globals.css, bez pliku tailwind.config.js.
- Błędy typów naprawiaj u źródła, bez any i @ts-ignore.
# Decyzje
- Serwer npm run dev uruchamiam sam w osobnym terminalu, Ty go nie uruchamiasz.
- Plan strony głównej jest w pliku SPEC.md.
Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. W projekcie jest AGENTS.md z kreatora, a nie ma CLAUDE.md ani CLAUDE.local.md. Co Claude Code wczyta na starcie sesji?
2. Co najbardziej warto wpisać do CLAUDE.md projektu Kraken's Call?
3. Gdzie zapiszesz własne instrukcje do projektu, których nie chcesz wysyłać do repozytorium?
Zadania praktyczne w grze
- Układanie w pionie
Ułóż kroki zakładania pamięci projektu w Kraken's Call: