Dokument przekazania: Pamięć agenta między sesjami

21 marca 2026 roku moja produkcyjna strona obsługiwała ładowania trwające 14 sekund po tym, jak czyszczenie pamięci podręcznej obnażyło wąskie gardło wydajności. Przeanalizowałem przyczynę źródłową w dwóch sesjach, zidentyfikowałem powolną ścieżkę kodu, sporządziłem plan naprawy i ująłem wszystko w dokumencie przekazania.

Dokument przekazania niesie diagnozę przez granice sesji, dzięki czemu wdrażający agent dziedziczy skorygowane rozumienie zamiast ponownie wyprowadzać te same błędne wnioski. W przeciwieństwie do zgłoszeń, które mówią, co należy zrobić, przekazania rejestrują, co zostało wypróbowane, co było błędne i dlaczego wcześniejsze podejścia zawiodły. Przekazanie strony market przetrwało trzy korekty w ciągu czterech dni i pokierowało wdrożeniem, które skróciło czas ładowania strony z 14 sekund do 108 milisekund.

Pierwsza wersja tego przekazania była błędna. Wskazywała niewłaściwą ścieżkę kodu. Przegląd kodu wychwycił, że zmierzone wolne strony były obsługiwane przez market_hub(), a nie przez _fetch_market_data(), jak zakładało przekazanie. Przekazanie zostało poprawione.

Druga wersja proponowała zbędne fragmenty HTMX dla Apple Maps i liczników poziomów. Przegląd wychwycił, że Apple Maps podpisuje adresy URL lokalnie (brak żądania wychodzącego do odroczenia) i że liczniki poziomów powinny pochodzić z pojedynczego zapytania agregującego. Przekazanie zostało poprawione ponownie.

Trzecia wersja proponowała uczynienie endpointu pogodowego asynchronicznym, ale nie precyzowała, że istniejący synchroniczny klient HTTP nadal blokowałby pętlę zdarzeń, nawet za HTMX. Przekazanie zostało poprawione po raz trzeci.

Cztery dni później inna sesja przeczytała trzykrotnie poprawione przekazanie i wdrożyła poprawkę. Austin spadł z 14 290 ms do 108 ms. Wdrożenie objęło właściwą ścieżkę kodu, użyło właściwego podejścia zapytania i pominęło zbędne fragmenty HTMX. Każda korekta z trzech przeglądów była już uwzględniona.

Dokument przekazania niósł diagnozę przez cztery dni i wiele sesji. Bez niego wdrażająca sesja zaczęłaby od zera, poczyniła te same błędne założenia, zaproponowała te same zbędne optymalizacje i wymagała tych samych korekt. Przekazanie skompresowało cztery dni dochodzenia w dokument, który wdrażający agent przeczytał w sekundach. Jest to zarządzanie oknem kontekstu zastosowane do konkretnego problemu: jak przenieść diagnozę przez granice sesji bez utraty korekt, które czynią ją trafną.

Co zawiera przekazanie

Dokument przekazania to nie zgłoszenie. Zgłoszenie mówi, co należy zrobić. Przekazanie mówi, co zostało wypróbowane, czego się nauczono, co było błędne i co zrobić dalej. Różnicą jest pamięć instytucjonalna.

Przekazanie strony market zawierało:

Diagnozę. Pomiary TTFB zimnego renderu dla sześciu stron market, w zakresie od 381 ms (Tokio, mały rynek) do 14 290 ms (Austin, ponad 500 firm). Pomiary udowodniły, że problem skaluje się z liczbą firm, co wskazywało na kształt zapytania jako wąskie gardło.

Przyczyny źródłowe, uszeregowane według priorytetu. Cztery przyczyny źródłowe uporządkowane według wpływu: kształt zapytania (główna), blokujący API pogodowy (drugorzędna), pełne skanowanie tabeli na innej ścieżce kodu (trzeciorzędna) oraz brakujące nagłówki pamięci podręcznej (już częściowo rozwiązane). Każda przyczyna źródłowa zawierała ścieżki plików, numery linii oraz konkretny wzorzec kodu powodujący spowolnienie.

Błędne tropy. Pierwsza wersja celowała w _fetch_market_data() zamiast market_hub(). Przekazanie odnotowało ten błąd i korektę, aby wdrażająca sesja nie wyprowadziła ponownie tego samego błędnego wniosku. Odnotowano również odrzucone fragmenty HTMX i powód ich odrzucenia: Apple Maps nie ma żądania wychodzącego, liczniki poziomów należą do zapytania agregującego.

Plan wdrożenia. Pięć kroków z przykładami SQL, kryteriami akceptacji i instrukcjami weryfikacji. Krok 1: zastąpić paginację po stronie Python zapytaniem do bazy danych. Krok 2: dodać fragment HTMX pogody z klientem asynchronicznym. Krok 3: buforować drugorzędną ścieżkę kodu. Krok 4: dodać nagłówki pamięci podręcznej brzegowej. Krok 5: ponownie zmierzyć te same sześć adresów URL.

Wpis zarządzanie oknem kontekstu wyjaśnia, dlaczego ten poziom szczegółowości ma znaczenie: każda niejednoznaczność w przekazaniu to decyzja, którą wdrażający agent musi ponownie wyprowadzić, zużywając budżet kontekstu i ryzykując ten sam błędny wniosek.

Miny kontekstowe. Współdzielony kontekst szablonu obejmuje uwierzytelnione wyszukiwanie salda monet na każdej stronie, w tym na stronach, które nigdy go nie renderują. Przekazanie odnotowało to jako kwestię poprawności pamięci podręcznej: s-maxage bez właściwych nagłówków Vary mógłby serwować nieaktualne dane uwierzytelniania anonimowym użytkownikom.

Dlaczego zgłoszenia zawodzą

Zgłoszenie dla tej samej pracy mówiłoby: „Strony market są wolne. Zoptymalizuj zapytanie market hub”. Wdrażająca sesja musiałaby:

1. Odkryć, która ścieżka kodu obsługuje strony market (nieoczywiste bez przeczytania routera)
2. Sprofilować ścieżkę kodu, aby znaleźć wąskie gardło
3. Rozważyć różne podejścia optymalizacyjne
4. Wdrożyć jedno z nich
5. Odkryć, że podejście ma efekt uboczny (poprawność pamięci podręcznej z danymi uwierzytelniania)
6. Skorygować podejście

Kroki 1–3 zostały już wykonane w sesjach dochodzeniowych. Przekazanie przenosi tę pracę do przodu. Zgłoszenie ją odrzuca.

Trybem awarii nie jest lenistwo. Trybem awarii jest utrata kontekstu na granicach sesji. Sesja agenta AI rozpoczyna się z czystym oknem kontekstu. Nie pamięta, co odkryła poprzednia sesja. Jest to ten sam problem, który kontekst to architektura adresuje na poziomie systemowym: to, co umieszczasz w oknie kontekstu, decyduje o jakości wyniku. Zgłoszenie zapewnia cel. Przekazanie zapewnia cel oraz nagromadzone zrozumienie potrzebne, by osiągnąć go poprawnie.

Historia poprawek ma znaczenie

Historia poprawek przekazania jest tak samo cenna jak jego bieżąca treść. Przekazanie strony market odnotowało trzy poprawki ze znacznikami czasu i powodami:

• Utworzono: 2026-03-21T17:24 (pierwotne dochodzenie)
• Poprawiono: 2026-03-21T18:20 (korekty z przeglądu kodu: błędna ścieżka kodu, zbędny HTMX)
• Poprawiono: 2026-03-25T06:30 (wdrożenie zakończone, poprawka zapytania wdrożona)

Historia poprawek mówi wdrażającej sesji: „ta diagnoza została zakwestionowana i skorygowana. Bieżąca wersja uwzględnia te korekty”. Przekazanie bez poprawek może być błędne. Przekazanie z trzema poprawkami zostało poddane próbie warunków skrajnych.

Błędne tropy są częścią wartości. Przekazanie, które mówi „rozważaliśmy i odrzuciliśmy fragment HTMX /_map, ponieważ Apple Maps podpisuje adresy URL lokalnie”, oszczędza wdrażającej sesji proponowania tej samej optymalizacji, jej oceny i odrzucenia. Przekazanie wcześniej wprowadza odrzucenie.

Kiedy pisać przekazanie

Nie każde zadanie wymaga przekazania. Naprawa błędu, która zajmuje jedną sesję, nie wymaga trwałości międzysesyjnej. Przekazanie jest wartościowe, gdy:

Dochodzenie jest kosztowne. Profilowanie wąskiego gardła wydajności, śledzenie luki bezpieczeństwa, debugowanie interakcji wielosystemowej. Jeśli dochodzenie wymagało znacznego wysiłku, przekazanie zachowuje ten wysiłek.

Wdrożenie nastąpi w innej sesji. Jeśli kończy się dochodzenie dziś, ale wdrożenie ma nastąpić jutro, przekazanie wypełnia tę lukę. Bez niego jutrzejsza sesja zaczyna od zera.

Diagnoza nie jest oczywista. Jeśli właściwa naprawa wymaga zrozumienia, dlaczego trzy pozornie rozsądne alternatywy są błędne, przekazanie zachowuje to zrozumienie. System złożonego kontekstu wyjaśnia, jak przekazania wpisują się w szersze gromadzenie wiedzy projektowej. Zgłoszenie mówiące „popraw zapytanie” nie wyjaśnia, dlaczego zapytanie wymaga konkretnej poprawki.

Wiele osób (lub agentów) może nad tym pracować. Przekazanie to dokument wspólnego zrozumienia. Każda sesja, która je czyta, dziedziczy pełny kontekst dochodzenia.

Przekazania jako złożony kontekst

Przekazanie to depozyt w systemie złożonego kontekstu. Każde przekazanie zachowuje czas diagnozy i przekształca go w artefakt wielokrotnego użytku. Wdrażająca sesja wypłaca diagnozę przy niemal zerowym koszcie.

Z czasem przekazania kumulują się w historię dochodzeń. Przekazanie strony market odwołuje się do incydentu czyszczenia pamięci podręcznej, pomiarów nightcheck, destrukcyjnego zabezpieczenia API oraz systemu przeglądu kodu. Każdy z nich sam w sobie jest produktem wcześniejszych sesji. Przekazanie łączy je w narrację, którą może podążyć nowa sesja.

Przekazanie nie zastępuje rozumienia. Wdrażająca sesja nadal musi przeczytać kod, napisać poprawkę i zweryfikować wynik. Przekazanie zastępuje ponowne odkrywanie. Sesja nie musi odkrywać tego, co już jest znane. Architektura agenta Ralph wykorzystuje przekazania jako podstawowy mechanizm trwałości międzysesyjnej dla swojej nocnej pętli wykonawczej. Centrum inżynierii AI dokumentuje, jak przekazania wpisują się w szerszą infrastrukturę hooków, umiejętności i systemów pamięci, które sprawiają, że rozwój wspomagany agentami kumuluje się w czasie.

FAQ

Jak długie powinno być przekazanie?

Wystarczająco długie, by uchwycić diagnozę, błędne tropy i plan wdrożenia. Wystarczająco krótkie, by agent mógł je przeczytać przy jednym ładowaniu kontekstu. Przekazanie strony market miało 103 linie. Większość przekazań ma od 50 do 150 linii.

Gdzie przechowuje się przekazania?

W katalogu pamięci projektu: ~/.claude/projects/{project}/memory/handoff-{topic}.md. System pamięci ładuje odpowiednie pliki na podstawie opisów we frontmatterze, więc przekazania są wykrywalne przez przyszłe sesje bez jawnego odwołania.

Czy przekazania zastępują dokumentację?

Nie. Dokumentacja opisuje, jak działa system. Przekazanie opisuje, czego nauczono się o konkretnym problemie i co z tym zrobić. Dokumentacja jest trwała. Przekazanie jest konsumowane przez wdrażającą sesję, a następnie staje się kontekstem historycznym.

Co, jeśli przekazanie staje się nieaktualne?

Pole statusu przekazania to śledzi. Aktywne przekazania są oznaczone jako PLANNED lub IN PROGRESS. Zakończone przekazania są oznaczone jako RESOLVED z hashem commita wdrożenia. Nieaktualne przekazania są widoczne jako kontekst historyczny, ale nie są możliwe do działania.

Źródła

Artykuł czerpie z przekazania dotyczącego wydajności strony market (handoff-market-page-perf.md), które pokierowało poprawką kształtu zapytania wdrożoną 25 marca 2026 roku. Przekazanie przetrwało trzy cykle poprawek w ciągu czterech dni i wpłynęło na wdrożenie, które osiągnęło 132-krotną poprawę wydajności. Wymienione w Złożony kontekst.