Agent codziennie ma pierwszy dzień pracy
Pamięć agenta AI przy pracy z kodem to w praktyce wszystko, co agent zastaje w repozytorium: nazwy, struktura, testy i pliki pamięci projektu, nie baza wektorowa dostawiona obok. Agent kodujący zaczyna każde zadanie jak nowy programista pierwszego dnia: nie zna historii, nie zna powodów, nie wie, gdzie są miny. Tyle że nowego programistę wdraża się raz, a agent zwykle zaczyna zadanie z nowym oknem kontekstu i stan projektu musi odtworzyć. Niektóre narzędzia mają już własną pamięć między sesjami; o pamięci agentów pisze się zresztą głównie od strony baz wektorowych i retrievalu. Przy pisaniu kodu sedno leży gdzie indziej: najbardziej przenośnym źródłem kontekstu, które w pełni kontrolujesz i które współdzieli cały zespół, jest repozytorium — nazwy mówiące, co rzeczy robią, struktura podpowiadająca, gdzie szukać, testy pilnujące, czego nie wolno zepsuć. I pliki pamięci projektu — u mnie w konwencji CLAUDE.md, w innych narzędziach AGENTS.md, a w praktyce zwykły plik tekstowy w repo, nie feature żadnego dostawcy. W nim mieszka wiedza, której kod nie powie: jakie decyzje zapadły i dlaczego, czego nie ruszać, które dziwactwa są celowe. Prywatnie nazywam to zasadą Iron Mana: nie ma Iron Mana bez Tony’ego Starka.
Gdzie ta wiedza u mnie mieszka
Zauważyłem to na banalnym sygnale: trzecie zadanie z rzędu tłumaczyłem agentowi tę samą rzecz. Zamiast znowu poprawiać prompt, dopisałem regułę do pliku pamięci przy module. Problem zwykle znika, a kiedy wraca, poprawiam regułę, nie prompt. Od tamtej pory powtarzająca się poprawka w promptach jest dla mnie sygnałem, że wiedza ma złe miejsce.
Podobnie z ustaleniami z dyskusji: decyzje i powody odrzuconych rozwiązań przepisuję z wątków do pliku przy module, którego dotyczą. Napisane raz, czyta zespół i czyta agent. Plik mówi też wprost, czego moduł nie robi i czego nie wolno zmieniać bez rozmowy, bo agent, jak każdy nowy w projekcie, najwięcej szkód robi tam, gdzie nikt nie napisał, czego nie ruszać. Wyników i tak nie przyjmuję bez sprawdzenia, jak opisałem osobno, ale dobra pamięć wyraźnie zmniejsza liczbę rund.
Tak wygląda szkielet takiego pliku u mnie. Pilnuję dwóch rzeczy: ma być krótki, bo agent czyta go w każdej sesji, i aktualny, bo nieaktualna pamięć szkodzi bardziej niż żadna:
# <Moduł> — pamięć projektu
# (krótko i aktualnie: agent czyta ten plik w każdej sesji;
# nieaktualna pamięć szkodzi bardziej niż żadna)
## Do czego służy
2–3 zdania o problemie biznesowym, nie o implementacji.
## Jak się tu pracuje
- dokładne komendy: build, testy, lint, uruchomienie lokalne
- po czym poznać, że działa
## Decyzje, które już zapadły
- <decyzja> — dlaczego; jakie alternatywy odrzucono i czemu
## Granice
- czego ten moduł NIE robi (i gdzie jest to, co robi)
- czego nie zmieniamy bez rozmowy: kontrakty, migracje, publiczne API
- kto konsumuje ten moduł — kogo zepsuje zmiana kontraktu
## Pułapki
- wygląda na błąd, ale jest celowe: …
- wygląda dobrze, ale gryzie: …
## Jak zweryfikować zmianę
- minimalny scenariusz + komendy, które muszą przejść przed PR
Codable Lab · szablon do zabrania
kopiuje szkielet powyżej — wklej jako CLAUDE.md albo AGENTS.md przy module; działa lokalnie, nic nie wysyła
Co z tego wynika, jeśli zamawiasz oprogramowanie
Porządek w kodzie stał się dźwignią. Dobrze opisany i sprawdzalny system pozwala oddać agentom więcej pracy z mniejszą liczbą rund; bezpieczeństwo dalej zapewniają typy, testy, CI i ludzka weryfikacja. Zaniedbany system tę dźwignię odwraca — AI dosypane do spaghetti daje spaghetti, tylko szybciej. Jeśli plan na przyszły rok brzmi „dodamy AI”, pierwsze pytanie nie dotyczy modelu, tylko tego, czy system ma się w czym odnaleźć. Nawracające bugi i dług techniczny wyceniam dziś także przez ten pryzmat.
Ten drugi moduł ze wstępu? Plik pamięci piszę mu w ratach, po każdej wpadce.