Kurs vibe coding z Claude Code · Moduł 2: Projekt Next.js z Claude Code

Pamięć projektu: AGENTS.md, CLAUDE.md i /init

7 min czytania ·
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.md

To 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.md

Postaw 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:

/init

Claude 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 planu

To 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.md

Od 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:

  1. Import: pierwsza linia CLAUDE.md to @AGENTS.md.
  2. Długość: kilkanaście linii, daleko od 200.
  3. Test kodu: przy każdej linii pytasz, czy Claude znalazłby to w repozytorium; jeśli tak, linia wylatuje.
  4. Sekrety i balast: w diffie nie ma kluczy ani CLAUDE.local.md, a .gitignore ma 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. 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. 2. Co najbardziej warto wpisać do CLAUDE.md projektu Kraken's Call?

  3. 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:

  1. PytanieQuiz: AGENTS.md bez CLAUDE.md
  2. PytanieQuiz: Co wpisać do CLAUDE.md
  3. Ułóż w kolejnościSortowanie: Pamięć projektu krok po kroku
  4. PytanieQuiz: Notatki poza repozytorium

Przydatne artykuły