Context engineering dla agentów kodujących: dokumentacja projektu, z której agent wznawia pracę za 7K tokenów

TL;DR: Agent kodujący nie ma między sesjami żadnej pamięci poza tym, co zapiszesz, więc dokumentacja projektu jest jego pamięcią długoterminową. Optymalizować trzeba to, ile agent musi przeczytać, zanim będzie wiedział, co czytać dalej. Zmierzyłem to: wznowienie prawdziwego wątku pracy z jednolinijkowego promptu kosztowało około 6 700 tokenów przy uporządkowanym drzewie dokumentacji, wobec 39 500 tokenów przy czytaniu tych samych trzech plików w całości. To spadek o 83%. Zasady, które mnie tam doprowadziły, są proste: plik-hub poniżej 200 linii, blok wejściowy poniżej 100 linii na początku każdego pliku z wątkiem, podział plików według tego, jak się je czyta, a nie według rozmiaru, oraz instrukcje zapisane jako "co robić plus jedno zdanie dlaczego", z długim uzasadnieniem zarchiwizowanym gdzie indziej. Liczba linii okazała się złą miarą dla dokumentacji.

Problem: drzewo dokumentacji, którego żadna sesja nie przeczyta

Jeden z moich produktów, narzędzie do mierzenia widoczności w AI, zgromadził przez miesiące budowania go z agentami kodującymi pokaźne drzewo dokumentacji: 189 plików markdown, około 64 000 linii, mniej więcej 1,5 miliona tokenów. Są tam plany, research, pomiary, decyzje, runbooki i bieżący stan kilkunastu równoległych wątków pracy. Żadna sesja nie jest w stanie tego załadować i żadna nie powinna próbować.

A jednak każda nowa sesja musi podjąć pracę tam, gdzie skończyła poprzednia. Kiedy kończę długą sesję, zostawiam wskazówkę w rodzaju "kontynuuj od tego pliku, sekcja ze stanem wątku" i zaczynam od nowa, bo to na długie sesje idą tokeny. Działa to tylko wtedy, gdy nowa sesja potrafi tanio się zorientować. Potrzebowałem więc odpowiedzi na konkretne pytanie: ile kosztuje agenta powrót do wątku i co w strukturze dokumentacji decyduje o tym koszcie?

To jest context engineering: decydowanie, jakie informacje trafiają do okna kontekstu modelu, w jakiej formie i w którym momencie. Pisanie promptu to jego niewielka część. Większość polega na porządkowaniu materiału, który agent wciąga sam. Dla agenta kodującego dokumentacja projektu jest jego pamięcią, jedynym stanem, który przetrwa z jednej sesji do następnej, więc jej kształt to decyzja z zakresu context engineeringu, niezależnie od tego, czy tak ją traktujesz.

Ile linii może mieć plik markdown, zanim agent się w nim zgubi?

Tak brzmiało pytanie na początku. W kodzie aplikacji pracuję już z miękkim limitem 800 linii na plik i oczywistym ruchem było przyłożenie tej samej liczby do dokumentacji. Pomiar pokazał, że to złe podejście.

Dałem nowej sesji jednolinijkowy prompt wskazujący wątek w obszarze marketingu i policzyłem, co przeczytała, zanim zaczęła właściwą pracę:

Te same trzy pliki przeczytane w całości to byłoby około 39 500 tokenów. Struktura obniżyła koszt wejścia w wątek o 83%. Sam plik z wątkiem ma 864 linie, czyli więcej niż mój próg dla kodu, i nie miało to żadnego znaczenia, bo nikt nie czyta go w całości. O realnym koszcie pliku z dokumentacją decyduje to, ile trzeba przeczytać, zanim wiadomo, co czytać dalej. Całkowita długość liczy się tylko w rzadkich przypadkach, gdy naprawdę trzeba przeczytać wszystko.

Jakie opcje rozważałem

Zanim zdecydowałem się na strukturę, porównałem trzy podejścia.

Załadować z góry wszystko, co istotne. Wskazać sesji pełny plan albo cały plik z wątkiem i pozwolić jej czytać. Zaleta: nic nie umknie. Wada: koszt i rozmycie. Sam jeden plik z planem miał około 35 000 tokenów, w większości historii, której bieżący krok nie potrzebował, a kontekst pełen nieaktualnych szczegółów sprawia, że model gorzej radzi sobie z tym, co ważne.

Ograniczyć pliki liczbą linii. Dzielić wszystko, co przekracza ustalony rozmiar. Zaleta: łatwo to egzekwować mechanicznie. Wada: cięcie wypada w przypadkowych miejscach, więc sesja często potrzebuje obu połówek w tej samej turze i płaci za dwa pliki zamiast jednego.

Ułożyć strukturę pod wyszukiwanie. Trzymać w kontekście identyfikatory (ścieżkę pliku i kotwicę sekcji), a treść wciągać dopiero wtedy, gdy jest potrzebna. Anthropic w swoich wskazówkach dotyczących context engineeringu nazywa to pobieraniem just in time, w przeciwieństwie do ładowania z góry. Zaleta: koszt rośnie razem z zadaniem, a nie z archiwum. Wada: wymaga dyscypliny. Każdy plik potrzebuje rzetelnego bloku wejściowego i nagłówków, spośród których da się wybierać, a to trzeba utrzymywać.

Wybrałem trzecie podejście, z kilkoma twardymi limitami, żeby dało się je utrzymać.

Progi, które wyszły z pomiaru

Mierzę cztery rzeczy zamiast jednej:

Dzienniki, do których tylko się dopisuje, takie jak worklog albo dziennik eksperymentów, są cięte przy około 1000 linii. Nie mają bloku wejściowego; ich wartością są najnowsze wpisy, a stare trafiają do archiwum.

Sam blok wejściowy ma stały kształt, żeby sesja mogła mu ufać: cel wątku, co zrobione, co zostało, otwarte decyzje, dokładny następny krok i pliki do otwarcia. Ten sam kształt służy też jako notatka przekazania (handoff), którą piszę na koniec długiej sesji, więc kończenie sesji i jej wznawianie korzystają z jednego formatu.

Dziel według tego, jak plik się czyta, a nie według długości

Gdy plik rzeczywiście trzeba podzielić, o miejscu cięcia decyduje jedno pytanie: czy jakakolwiek sesja potrzebowałaby obu połówek w tej samej turze? Jeśli nie, to są dwa pliki. U mnie sprawdziły się takie linie podziału: kanon i dziennik (jak coś działa kontra co się stało i kiedy), żywe i zamknięte (aktywne wątki kontra archiwum zakończonych) oraz pomiary i decyzje (surowe liczby się przelicza, werdykty się czyta).

Na co uważać? Tu też chodzi o blok wejściowy, a nie o długość. W całym drzewie proporcje różnią się dziesięciokrotnie. Jeden plik z wątkiem ma 82-liniowy blok wejściowy na 864 linie: zdrowo. Inny pozwolił, żeby jego blok "bieżący stan" urósł do 2464 linii w pliku o długości 3383 linii. Blok wejściowy zjadł więc plik i taniej było przeczytać całość, niż ustalać, co jest aktualne. To objaw, który naprawdę boli. Drugi to nagłówki, spośród których nie da się wybrać. Nagłówek w rodzaju "Wynik 7" jest bezużyteczny dla agenta, który przegląda listę sekcji pliku; "Wynik 7: wąskie pytania znaczą więcej niż długie" pozwala mu pominąć resztę.

Co agent kodujący ładuje, zanim cokolwiek wpiszesz?

Koszt wznowienia to jedna połowa. Druga to podłoga, którą każda sesja płaci przed pierwszym słowem o zadaniu. Które mechanizmy ładują się od razu, a które leniwie, opisałem w moim wcześniejszym artykule o architekturze kontekstu w Claude Code, więc tu podaję tylko zmierzony budżet dla tego samego produktu:

To około 14% okna 200K, zanim zacznie się jakakolwiek praca. Dwie pozycje w tej tabeli wymagały działania. Indeks skilli do nich nie należał: 21 skilli za 2700 tokenów to niewiele.

Indeks pamięci jest po cichu obcinany. Claude Code ładuje na starcie indeks pamięci projektu do 200 linii albo 25KB, zależnie od tego, co nastąpi wcześniej, a resztę pomija bez ostrzeżenia. Mój był na 78% tego limitu. Po jego przekroczeniu koniec indeksu po prostu przestałby się ładować, a agent nie wiedziałby, że te wspomnienia istnieją. Dlatego indeks to jedna linia na wpis, jednozdaniowy haczyk wskazujący plik ze szczegółami, nigdy akapit z datami i wyjątkami.

Globalny plik z instrukcjami przekraczał zalecane 200 linii. Ten ma swoją historię. Na początku miesiąca ważył 41KB, około 12-13K tokenów, pięć razy więcej niż wszystkie opisy moich subagentów razem, bo każda reguła niosła długie wyjaśnienie z historią incydentu, który ją wywołał. Dla człowieka to przydatne, a dla każdej pojedynczej sesji to podatek.

Jak pisać instrukcje dla agenta kodującego?

Poprawka tego pliku stała się moim formatem dla każdej reguły: co robić, plus jedno zdanie dlaczego. Pełne uzasadnienie, z historią incydentów i przykładami, trafia do osobnego dokumentu-archiwum, do którego reguła linkuje. Agent dostaje zachowanie i tyle uzasadnienia, żeby zastosować je w przypadkach, których reguła nie przewidziała; archiwum przechowuje historię na dzień, w którym regułę trzeba będzie przemyśleć.

<!-- illustrative shape of one rule -->
## Tests must not fail after a date
Freeze the clock when fixtures pin dates, or compute dates from "now".
Why: a literal date in a fixture plus a real clock in the code breaks weeks later, silently.
Full history: see the rationale archive, section "Tests".

Jedno zdanie wyjaśnienia jest warte swojego miejsca. Gołą regułę agent stosuje dosłownie i źle stosuje na brzegach; reguła z uzasadnieniem zostaje poprawnie uogólniona. Opowieść o incydencie nie zasługuje na miejsce w pliku ładowanym zawsze, bo model nie potrzebuje historii, żeby przestrzegać reguły. Ta przeróbka zmniejszyła plik globalny z około 12-13K tokenów do około 5,6K. Nadal jest o 38 linii dłuższy niż zalecany limit i to jest uczciwy stan rzeczy: format działa, a plik wciąż wymaga kolejnego przejścia.

Ograniczenia i co powiedziałbym komuś, kto zaczyna jutro

To podejście ma swoje koszty. Bloki wejściowe się starzeją, jeśli nikt ich nie aktualizuje, a nieaktualny blok wejściowy jest gorszy niż żaden, bo agent mu ufa. Polegam na tym, że agent zaktualizuje blok na koniec każdego kawałka pracy, a ja zauważę, kiedy blok zaczyna puchnąć. Liczby tokenów to szacunki na podstawie liczby bajtów, z marginesem błędu, który nie zmienia tu żadnej decyzji. Całość zakłada też, że agent najpierw czyta blok wejściowy, zamiast odruchowo otwierać cały plik; niezawodność zapewnia dopiero jawne wskazanie sekcji w prompcie wznawiającym.

• Mierz koszt wznowienia, nie długość pliku. Daj nowej sesji jednolinijkową wskazówkę i policz, co przeczyta, zanim zacznie pracę. To tę liczbę trzeba zbijać.
• Daj każdemu plikowi z wątkiem blok wejściowy poniżej 100 linii o stałym kształcie: cel, zrobione, zostało, decyzje, następny krok, pliki.
• Trzymaj huby poniżej 200 linii. Ładują się za każdym razem; kierują, a nie wyjaśniają.
• Dziel według wzorca dostępu. Jeśli żadna sesja nie potrzebuje obu połówek naraz, to są dwa pliki.
• Pisz nagłówki, spośród których agent może wybierać. Lista sekcji powinna działać jako samodzielny spis treści.
• Pilnuj cichych limitów. Indeks pamięci powyżej limitu nie zgłasza błędu; po prostu zapomina.
• Zapisuj reguły jako to, co robić, plus jedno zdanie dlaczego, a długie uzasadnienie archiwizuj tam, gdzie człowiek je znajdzie.