Jak sprawić, żeby Claude Code pamiętał twój projekt z sesji na sesję

Rzecz, która mnie realnie męczyła

Narzędzia AI, z którymi dziś pracuję, są naprawdę dobre. Buduję w nich różne projekty, czasem w Codex, najczęściej w Claude Code. Aplikacje, strony, materiały, całe systemy pracy. I przez długi czas miałem jeden problem, który wracał każdego dnia.

Za każdym razem, kiedy zaczynałem nową sesję, czyli otwierałem nowe okno rozmowy, musiałem tłumaczyć wszystko od nowa. O co chodzi w tym projekcie. Na czym on polega. Co już zrobiliśmy poprzednim razem. Gdzie leżą pliki, które są ważne. Co jest następnym krokiem. Nad czym mamy dzisiaj usiąść.

Za każdym. Razem. Od nowa.

To jest frustrujące w sposób, który trudno docenić, dopóki się tego nie robi codziennie. Model jest genialny w środku sesji, pamięta wszystko, o czym rozmawialiśmy przez ostatnią godzinę. A potem zamykam okno, wracam nazajutrz i rozmawiam z kimś, kto nigdy o tym projekcie nie słyszał.

Wiem, że Claude Code ma swoje auto memory. Że sam zapisuje sobie różne rzeczy. Ale to nie jest to. To nie o to mi chodziło. Gdzieś tam odkłada wybrane notatki, sam decydując, co jest jego zdaniem warte zapamiętania. Mnie zależało na czymś prostszym i pewniejszym: żebym nie musiał ciągle tłumaczyć projektu na nowo.

Dlaczego auto memory tego nie załatwia

Zajrzałem najpierw do oficjalnej dokumentacji, zamiast zgadywać. I okazało się, że to, co mnie irytowało, nie jest usterką. Tak to jest zaprojektowane.

Auto memory zapisuje notatki wtedy, kiedy model sam uzna, że przydadzą się w przyszłości. Nie zapisuje czegoś w każdej sesji. Sam wybiera, co jego zdaniem jest ważne. To znaczy, że nie masz jak mu powiedzieć, co konkretnie ma zapamiętać. Losowość jest tu mechanizmem, nie wypadkiem.

Do tego auto memory trzyma jedną wspólną pamięć na całe repozytorium, nie na projekt. Jeśli w jednym miejscu masz kilka projektów, ich notatki lądują w jednym worku, bez rozdzielenia. Dokładnie ten efekt, który mnie męczył: sterta przypadkowych wspomnień zamiast spójnej informacji o konkretnym projekcie.

200linii

I jeszcze jedno. Na starcie sesji ładuje się tylko wycinek tej pamięci, pierwsze 200 linii. Nawet gdyby notatki były dobre, nie masz gwarancji, że akurat te o twoim projekcie znajdą się w załadowanym kawałku.

Sedno sprawy

Auto memory odpowiada na pytanie „co model zauważył w tym repozytorium". Nie odpowiada na pytanie „gdzie skończyliśmy pracę nad projektem X". A to drugie pytanie potrzebuje pliku, który model ma polecone przeczytać i ma gwarancję, że go otworzy. Obu tych rzeczy w auto memory brakuje. Obie łatwo zdobyć zwykłym plikiem tekstowym i jedną regułą.

Rozwiązanie: jeden plik pamięci na projekt

Pomysł jest prosty. Każdy projekt, nad którym pracujesz, dostaje swój własny plik current-state.md, leżący w folderze tego projektu. To jest taka notatka nad czym się pracuje, co zrobiłeś, co warto, aby twój AI Agent wiedział jak zacznie na nowo. Kończysz daną sesję, zapisujesz to wszystko i już. W kolejnej sesji już wiadomo o co chodzi. Nie zaczynasz od zera.

Plik jest krótki, do jakichś sześćdziesięciu linii, i zawsze ma ten sam układ. Poniżej masz to opisane co Agent AI zobaczy jak zaczniesz pracować dalej:

# Current state: <nazwa projektu>

Czym to jest: dwa, trzy zdania o projekcie i jego celu.

Ostatnia sesja: data, co realnie zostało zrobione, w kilku linijkach.

Podjęte decyzje: ustalenia, które są zamknięte i których nie otwieramy na nowo.

Gdzie co leży: wskazania na najważniejsze pliki i foldery tego projektu.

Następne kroki: konkretne zadania w kolejce, najważniejsze na górze.

Otwarte pytania: cokolwiek czeka na moją decyzję.

Co warto powiedzieć, to, że ten plik jest nadpisywany za każdym razem. Każda aktualizacja przepisuje „ostatnią sesję" i „następne kroki" od nowa, zamiast doklejać kolejne podsumowania. Takie rozwiązanie powoduje, że AI Agent ma wszystko na bieżąco, a nie całą historię działania.

Jak to wygląda w folderach

Reguła oraz skill są zapisane na poziomie użytkownika, w folderze ~/.claude/, żeby działały w każdym projekcie. To folder, w którym Claude Code trzyma twoje globalne ustawienia. Można to wrzucić do danego projektu, ale po co? Tak musiałbyś za każdym razem dodawać te dwa pliki.

~/.claude/

~/.claude/
├── skills/
│   └── handoff/
│       └── SKILL.md            <-- narzędzie, które zapisuje stan projektu
└── rules/
    └── project-resume.md       <-- reguła, która każe wczytać stan na starcie

Te pliki "pamięci" są zapisywane już w konkretnych twoich projektach. Projekt samodzielny, na przykład aplikacja albo strona www, wyglądałby tak:

moja-aplikacja/

moja-aplikacja/
├── CLAUDE.md                   <-- z linijką importu (pokażę niżej)
├── current-state.md            <-- pamięć TEGO projektu
├── app/
└── ...

A jeśli masz swoje projekty w jednym miejscu, w folderze na kompie, wówczas każdy folder projektu dostaje własny plik:

moje-projekty/

moje-projekty/
├── projekt-a/
│   └── current-state.md        <-- pamięć projektu A
├── projekt-b/
│   └── current-state.md        <-- pamięć projektu B
└── projekt-c/
    └── current-state.md        <-- pamięć projektu C

Zwróć uwagę na podział

Skill i reguła są ustawione jako wspólne dla wszystkich projektów jako globalne ustawienie. Pamięci jest wiele, po jednej na projekt, i one się nie mieszają. Dziesięć projektów to dziesięć osobnych plików current-state.md, każdy pamiętający tylko swój projekt. To jest cały sens tego układu.

Skill handoff

Skill to zapisany proces, który wywołujesz komendą. O tym już pisałem w osobnych artykułach. Ten nazywa się handoff i jego jedyne zadanie to zapisać albo zaktualizować current-state.md danego projektu. Uruchamiam go na koniec sesji, komendą /handoff, albo po prostu mówiąc „kończymy na dziś". Mój Agent AI wie wtedy, co zrobić.

Poniżej cała jego treść, gotowa do wklejenia. Możesz jak chcesz sobie to rozbudować czy poprawić wg potrzeb. Zapisujesz to jako plik SKILL.md w folderze ~/.claude/skills/handoff/:

SKILL.md

---
name: handoff
description: Zamknięcie sesji nad projektem. Przepisuje plik current-state.md danego projektu, tak żeby następna sesja od razu wiedziała, czym jest projekt, co zrobiono, co jest ustalone i co dalej. Użyj, gdy Marek kończy pracę nad projektem, prosi o zapisanie stanu, albo mówi „handoff", „kończymy na dziś", „zapisz stan projektu", „zaktualizuj current-state", „podsumuj sesję na koniec".
argument-hint: "[folder projektu | puste = rozpoznaj z sesji]"
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
---

# Handoff

`current-state.md` to pamięć, którą projekt niesie między sesjami. Następna sesja czyta go na zimno, nie mając nic z dzisiejszej rozmowy. Pisz więc pod tego czytelnika: pod sesję, która nie wie nic poza tym, co jest w tym pliku. Reguła `project-resume.md` gwarantuje, że plik zostanie przeczytany przy wznowieniu. Ten skill sprawia, że warto go czytać.

## Krok 1: znajdź projekt

- Jeśli argument wskazuje folder, to jest ten projekt. Jeśli nie, rozpoznaj go po tym, nad czym szła sesja. Jeśli sesja dotknęła więcej niż jednego projektu, zapytaj, który zamknąć (albo zaproponuj każdy po kolei).
- Plik leży w folderze samego projektu: w korzeniu repozytorium dla projektu samodzielnego, albo w podfolderze projektu wewnątrz większej przestrzeni.
- **Repozytorium samodzielne:** sprawdź, czy główny `CLAUDE.md` zawiera linijkę `@current-state.md`. Jeśli nie, dodaj ją (ten import wczytuje plik automatycznie w każdej sesji). Jeśli nie ma w ogóle pliku `CLAUDE.md`, utwórz go z tą jedną linijką.
- **Folder projektu wewnątrz przestrzeni z wieloma projektami:** nie dodawaj importu w korzeniu (wciągałby stan wszystkich projektów do każdej sesji). Tu plik wczytuje przy wznowieniu reguła `project-resume.md`.

## Krok 2: odtwórz sesję

- Zbierz to, co się działo, z rozmowy, a w repozytorium git z `git status` i `git log --oneline` od początku sesji.
- Przeczytaj istniejący `current-state.md`, jeśli już jest. Przenieś dalej to, co wciąż prawdziwe, przede wszystkim „podjęte decyzje". One przetrwają między sesjami, chyba że Marek którąś otworzył na nowo.

## Krok 3: przepisz plik

Użyj tego stałego układu, w języku, w którym prowadzona była sesja:

```markdown
# Current state: <nazwa projektu>

**Czym to jest:** dwa, trzy zdania o projekcie i jego celu.
**Ostatnia sesja:** RRRR-MM-DD, co realnie zostało zrobione, w kilku linijkach.
**Podjęte decyzje:** ustalenia zamknięte, których się nie otwiera na nowo.
**Gdzie co leży:** wskazania na najważniejsze pliki i foldery tego projektu.
**Następne kroki:** konkretne zadania w kolejce, najważniejsze na górze.
**Otwarte pytania:** cokolwiek czeka na decyzję Marka.
```

Zasady przepisywania:

- **Przetaczaj, nie dopisuj.** „Ostatnia sesja" i „następne kroki" opisują dzisiaj, nie historię. Trwałe skutki przeszłych sesji wchodzą do „podjętych decyzji" albo „gdzie co leży". Reszta świadomie znika.
- Trzymaj całość poniżej sześćdziesięciu linii. Jeśli plik chce rosnąć, znaczy, że gromadzi historię. Tnij.
- Wpisy w „następnych krokach" są na tyle konkretne, że da się od nich ruszyć wprost („napisz sekcję o cenach w pliku X.md"), a nie ogólne („kontynuuj marketing").
- Jeśli Marek chce zachować historię, dopisz stary blok „ostatniej sesji" do pliku `session-log.md` obok. Tego logu nigdy nie wczytuj automatycznie.

Warunek ukończenia: sesja czytająca sam ten plik na zimno potrafi podać cel projektu, jego zamknięte decyzje i ruszyć pierwszy następny krok, nie zadając ani jednego pytania orientacyjnego.

## Krok 4: pokaż wynik

Pokaż pełną treść nowego pliku, a jeśli jakiś istniał wcześniej, krótką notkę, co się zmieniło i co wypadło. Plik jest w tym momencie już zapisany. Poprawki Marka wnoszę wprost do niego.

Reguła (rule): project-resume

Reguła to zapisana na stałe zasada, którą AI Agent czyta na starcie każdej rozmowy. Ta jedna robi drugą połowę roboty: każe Agentowi AI przeczytać current-state.md, zanim cokolwiek zrobi, kiedy proszę o powrót do projektu.

Tutaj ważne do dodania. Reguły właśnie zapisujesz w folderze "rules". One zawsze są ładowane przez Claude Code automatycznie jak zaczynasz nową sesję.

Zapisujesz to jako ~/.claude/rules/project-resume.md:

project-resume.md

# Wznawianie pracy nad projektem

Projekty niosą swój stan z sesji na sesję w pliku current-state.md leżącym w folderze projektu. Ta reguła sprawia, że wznowienie jest pewne, zamiast opierać się na auto memory.

- Kiedy Marek mówi, żeby wznowić, kontynuować albo wrócić do projektu, przeczytaj plik current-state.md z folderu tego projektu, zanim zrobisz cokolwiek innego.
- Jeśli current-state.md nie istnieje, powiedz to, pracuj na podstawie zawartości folderu i zaproponuj utworzenie pliku przez /handoff na koniec sesji.
- Traktuj wpisy „podjęte decyzje" w current-state.md jako zamknięte. Nie otwieraj ich na nowo, chyba że robi to Marek.
- Na koniec sesji nad projektem zaproponuj uruchomienie /handoff, żeby zaktualizować current-state.md. Nie aktualizuj go po cichu w trakcie.

Linijka, która wczytuje stan sama

Zostaje ostatni element, tylko dla projektów samodzielnych. W głównym pliku CLAUDE.md takiego projektu dodajesz jedną linijkę:

CLAUDE.md@current-state.md

To jest import. Sprawia, że stan projektu wczytuje się w całości, sam, w momencie kiedy otwierasz ten folder. Nie musisz nic mówić. Zanim napiszesz pierwsze słowo, agent już wie, gdzie skończyliście.

Dlaczego tylko projekty samodzielne? Bo jeśli w jednym miejscu masz wiele projektów, import w korzeniu wciągałby stan ich wszystkich do każdej sesji. Tam robotę przejmuje reguła project-resume: wczytuje właściwy plik dopiero, kiedy mówię „wróćmy do projektu X".

Jak to teraz wykorzystać na co dzień?

Cały proces to tylko trzy kroki, które musisz zapamiętać.

Pracujesz nad projektem jak zwykle. Na koniec sesji uruchamiasz /handoff albo mówisz „kończymy na dziś". Claude Code spisuje stan do current-state.md. Następnym razem mówisz „wróćmy do projektu X", a przy projekcie samodzielnym wystarczy, że otworzysz jego folder. Stan wczytuje się sam.

Jeden nawyk, na którym stoi całość

Jeśli zamkniesz okno bez /handoff, postęp tej sesji nie zapisze się nigdzie, tak samo jak wyjście z pracy bez spisania notatki zmiany. Reguła project-resume każe agentowi przypominać ci o tym pod koniec sesji, ale to ty naciskasz przycisk. To jest cały koszt tego systemu. Jedna komenda na koniec dnia.

Dołożenie nowego projektu to jeden ruch. Otwierasz jego folder, uruchamiasz /handoff raz. Skill tworzy current-state.md, a przy projekcie samodzielnym dokłada też linijkę importu. Zero konfiguracji ręką.