AGENTS.md i CLAUDE.md: jak zbudować pamięć projektu dla AI

Każda nowa sesja z agentem AI zaczyna się podobnie. Otwierasz terminal, wpisujesz zadanie i patrzysz, jak model z entuzjazmem świeżo zatrudnionego pracownika szuka danych, zgaduje, jak uruchomić skrypt, i po swojemu interpretuje słowo „przychód”. Poprawiasz go. Następnego dnia poprawiasz go znowu, tymi samymi słowami. Po tygodniu czujesz się jak bohater „Dnia świstaka”, a role są rozdane dokładnie jak w filmie: Ty pamiętasz wszystko, cała reszta świata zaczyna dzień od zera.

Taka jest konstrukcja tych narzędzi i trudno mieć do nich o to pretensje. Dokumentacja Claude Code mówi wprost, że każda sesja zaczyna się od świeżego okna kontekstu, a wiedzę między sesjami przenoszą pliki. Dlatego w drugim tygodniu kursu, zaraz po temacie wiedzy firmy i źródeł prawdy, zajmujemy się repozytorium jako kontekstem projektu. W tym artykule pokażę, jak zbudować pamięć projektu z trzech zwykłych plików tekstowych: README.md, AGENTS.md i CLAUDE.md. Co do nich wpisać, czego unikać i jak sprawić, żeby po miesiącu nadal mówiły prawdę.

Dlaczego rozmowa jest złą pamięcią

W artykule o briefie zamiast prompta pisałem, że okno rozmowy to najgorsze miejsce na przechowywanie wiedzy. Brief rozwiązuje ten problem dla pojedynczego zadania. Zostaje jednak cała wiedza wspólna dla wszystkich zadań w projekcie: gdzie leżą dane, jak je odświeżyć, które źródło wygrywa przy sprzecznościach, czego nie wolno ruszać. Tę wiedzę też trzeba gdzieś trzymać, a rozmowa nadaje się do tego jeszcze gorzej niż do briefu.

Powodów jest kilka. Rozmowa się kończy, a nowa zaczyna od zera. Rozmowa należy do jednej osoby, więc kolega z zespołu nie skorzysta z Twoich ustaleń. Rozmowy nie da się porządnie zrecenzować, bo nikt rozsądny nie przeczyta stu wiadomości, żeby sprawdzić, czy gdzieś w środku nie padła błędna definicja. Wreszcie rozmowa miesza rzeczy stałe ze zmiennymi. Po kilku godzinach sam nie wiesz, która z Twoich poprawek była jednorazowa, a która powinna obowiązywać zawsze.

Dokumentacja Claude Code daje na to bardzo praktyczną wskazówkę. W opisie pamięci projektu radzi traktować plik CLAUDE.md jako miejsce na wszystko, co inaczej tłumaczyłbyś od nowa. Dopisujesz coś, gdy model drugi raz popełnia ten sam błąd, gdy wpisujesz tę samą poprawkę co w poprzedniej sesji albo gdy nowa osoba w zespole potrzebowałaby tej samej wiedzy, żeby zacząć pracę. Uważam to za najlepszą definicję pamięci projektu, jaką znam: zapisane odpowiedzi na pytania, które padają więcej niż raz.

Claude Code ma również automatyczną pamięć, czyli notatki, które model zapisuje sam na podstawie Twoich poprawek. Wygodny dodatek, choć zasady obowiązujące cały zespół wolę pisać samodzielnie. Wtedy wiem, co w nich jest, i mogę je przejrzeć jak każdy inny dokument.

Trzy pliki, trzech odbiorców

W repozytorium, czyli w folderze projektu, zwykle spotkasz trzy pliki o podobnej treści i różnych czytelnikach. Ich nazwy brzmią technicznie, ale każdy z nich jest zwykłym tekstem w Markdownie.

README.md: wizytówka dla ludzi

README.md istnieje od dekad i jest pierwszym plikiem, który otwiera człowiek trafiający do projektu. Odpowiada na pytania: co to jest, po co istnieje, jak to uruchomić i kogo pytać. Dobry README pisze się dla osoby, która ma pięć minut i zero kontekstu. Agent też go przeczyta, ale README nie powinien puchnąć od instrukcji, które interesują wyłącznie model.

AGENTS.md: README dla agentów

AGENTS.md to otwarta konwencja, którą jej twórcy opisują jako „README dla agentów”. Pomysł jest prosty: instrukcje, które zaśmiecałyby README dla ludzi, trafiają do osobnego pliku w przewidywalnym miejscu. Format jest zwykłym Markdownem bez wymaganych pól, z dowolnymi nagłówkami.

Strona projektu wymienia długą listę narzędzi, które go obsługują, między innymi Codex od OpenAI, Cursor, Gemini CLI, agenta GitHub Copilot i VS Code. Opiekę nad formatem przejęła Agentic AI Foundation działająca w ramach Linux Foundation, co dobrze wróży jego trwałości. W praktyce oznacza to, że plik napisany raz przeczyta większość narzędzi, z którymi zetkniesz się w pracy.

CLAUDE.md: plik, który Claude Code czyta na starcie

CLAUDE.md pełni tę samą funkcję w Claude Code. Narzędzie wczytuje go na początku każdej sesji jako stałe instrukcje projektu. Nowsze wersje Claude Code potrafią przeczytać sam AGENTS.md, jeśli w projekcie nie ma żadnego pliku CLAUDE.md. Gdy są oba, domyślnie czytany jest wyłącznie CLAUDE.md, więc o ich zgodność trzeba zadbać samemu.

Jak utrzymać je w zgodzie

Dwa pliki o podobnej treści to przepis na rozjazd. Ktoś poprawi definicję klienta w jednym, zapomni o drugim i przez miesiąc dwa narzędzia będą liczyć dwie różne rzeczy. Są trzy sposoby, żeby temu zapobiec.

Pierwszy, który polecam w nowych projektach, to import. Claude Code rozumie w pliku CLAUDE.md składnię @ścieżka, która wczytuje treść innego pliku. Wystarczy więc, że CLAUDE.md zawiera linijkę @AGENTS.md, a pod nią ewentualne instrukcje przeznaczone wyłącznie dla Claude. Jedno źródło, zero kopiowania.

Drugi sposób to dowiązanie symboliczne, czyli plik wskazujący na inny plik. Działa, ale dokumentacja Claude Code sama odradza je, jeśli ktokolwiek w zespole pracuje na Windowsie: utworzenie dowiązania wymaga tam dodatkowych uprawnień, a Git potrafi zamienić je w zwykły plik z jedną linijką.

Trzeci to dwa identyczne pliki i reguła, że zmieniasz oba naraz. Tak robimy w repozytorium strony kursu: AGENTS.md i CLAUDE.md są celowo identyczne i opisują workflow pracy agentowej, od sprawdzenia otwartych zmian, przez zadanie w Linearze, po zasady, kiedy agent może samodzielnie scalić zmianę z główną wersją strony. Instrukcja o zachowaniu zgodności obu plików jest zapisana w nich samych, co ma w sobie coś z rekurencji, ale działa. Rozwiązanie wymaga jednak dyscypliny, więc jeśli zaczynasz od zera, wybierz import.

Trzy warstwy kontekstu

Zanim przejdę do treści pliku, jedno uporządkowanie, które pomaga zdecydować, co gdzie zapisać. Kontekst, który dostaje model, ma trzy warstwy o różnej trwałości.

Na górze jest rozmowa. Żyje kilka minut albo kilka godzin i zawiera bieżące polecenia, pytania oraz poprawki. Znika razem z sesją i dobrze, bo większość tego, co się w niej dzieje, jest jednorazowa.

W środku jest brief zadania. Żyje tyle, ile zadanie: dzień, tydzień, czasem miesiąc. Zawiera cel, dane, ograniczenia, kryterium poprawności i format wyniku dla jednej konkretnej analizy.

Na dole są stałe instrukcje projektu, czyli AGENTS.md i CLAUDE.md. Żyją tyle, ile projekt. Zawierają to, co obowiązuje przy każdym zadaniu: jak uruchomić i sprawdzić pracę, gdzie są dane, które definicje obowiązują i czego robić nie wolno.

Reguła przenoszenia między warstwami jest prosta. Jeśli coś z rozmowy przydaje się drugi raz w tym samym zadaniu, trafia do briefu. Jeśli coś z briefu przydaje się w drugim zadaniu, trafia do stałych instrukcji. Dzięki temu najniższa warstwa rośnie powoli i zawiera wiedzę, która przeszła już próbę praktyki.

Co wpisać do AGENTS.md

Poniżej lista, której używam jako szkieletu. Strona agents.md proponuje podobne sekcje (przegląd projektu, polecenia do budowania i testów, styl kodu, testy, bezpieczeństwo), a ja przestawiam je pod kątem projektów analitycznych.

Cel projektu w dwóch zdaniach

Po co istnieje ten projekt i dla kogo. Na przykład: „Cotygodniowy raport sprzedaży dla zarządu, odświeżany w poniedziałki rano”. Agent, który zna cel, lepiej rozstrzyga drobne wątpliwości, których nie przewidziałeś w instrukcjach.

Mapa projektu

Gdzie leżą dane wejściowe, gdzie wyniki, gdzie skrypty, gdzie dokumentacja. Wystarczy kilka linijek, wyłącznie o rzeczach nieoczywistych. Opisywanie każdego pliku po kolei to strata miejsca, bo agent sam potrafi przejrzeć folder.

Polecenia do uruchomienia i sprawdzenia

Najcenniejsza część pliku. Jak odświeżyć dane, jak uruchomić analizę, jak sprawdzić wynik. Na liście rzeczy wartych zapisania poradnik dobrych praktyk Claude Code stawia na pierwszym miejscu polecenia, których model sam nie zgadnie. Dodałbym do tego polecenie kontrolne: skrypt albo zapytanie, które potwierdza, że wynik jest poprawny. Agent z poleceniem kontrolnym sprawdza swoją pracę sam. Agent bez niego ogłasza sukces w chwili, gdy wynik „wygląda na gotowy”.

Definicje i źródła prawdy

Co znaczy „klient”, „przychód” i „aktywny użytkownik” oraz które źródło wygrywa, gdy dwa systemy podają różne liczby. W projektach analitycznych ta sekcja bywa ważniejsza niż wszystkie polecenia razem wzięte. Kasia rozkłada ten temat na czynniki pierwsze w artykule o definicjach KPI i źródłach prawdy. Jeśli słownik pojęć jest długi, trzymaj go w osobnym pliku i podaj w AGENTS.md odnośnik.

Zasady bezpieczeństwa

Jakich danych nie wolno wysyłać do zewnętrznych narzędzi, gdzie leżą sekrety (w pliku .env, który nie trafia do repozytorium), z jakimi uprawnieniami agent łączy się z bazą i których plików nie modyfikuje. Krótko i konkretnie.

Workflow

Jak wygląda praca od zadania do wyniku: gdzie zapisujesz zadania, jak nazywasz wersje, kto zatwierdza zmiany i kiedy agent ma się zatrzymać, żeby zapytać. W repozytorium strony kursu ta sekcja jest najdłuższa, bo nad repozytorium pracują agenci i dwoje autorów.

Czego tam nie wpisywać

Lista rzeczy zbędnych jest równie ważna jak lista obowiązkowych, bo każda linijka kosztuje. Plik wczytuje się przy każdej sesji i zajmuje miejsce w kontekście modelu, niezależnie od tego, czy przy danym zadaniu się przydaje.

• Sekrety. Hasła, klucze API, dane dostępowe do bazy. Plik trafia do repozytorium, a czyta go każdy agent i każda osoba z dostępem. Sekrety mieszkają w .env albo w menedżerze sekretów.
• Wiedza, którą agent wyczyta z kodu. Dobre praktyki Claude Code wymieniają ją wprost wśród rzeczy do pominięcia, razem z opisem projektu plik po pliku.
• Historia zmian. Od tego jest Git. Informacja, że w marcu zmieniła się definicja, pasuje do opisu zmiany. Instrukcjom wystarczy definicja aktualna.
• Rzeczy, które często się zmieniają. Dzisiejszy priorytet, numer bieżącego sprintu, osoba na dyżurze. Zanim zdążysz je zaktualizować, będą nieprawdziwe.
• Ogólniki. „Pisz czysty kod”, „bądź dokładny”, „myśl krok po kroku”. Model zna te rady na pamięć i niczego nowego się z nich nie dowie.
• Wykłady. Długie wyjaśnienia i samouczki. Jeśli coś wymaga dokumentacji, podlinkuj ją.

Ile to jest „krótko”? Dokumentacja Claude Code zaleca, żeby pojedynczy plik CLAUDE.md miał mniej niż 200 linijek, bo dłuższe pliki zużywają więcej kontekstu i obniżają skuteczność instrukcji. Codex ma twardszą granicę: domyślnie przestaje doklejać instrukcje, gdy ich łączny rozmiar przekroczy 32 KiB. Ja stosuję test z poradnika dobrych praktyk. Przy każdej linijce pytam, czy jej usunięcie sprawiłoby, że model popełni błąd. Jeśli odpowiedź brzmi „raczej nie”, linijka wylatuje.

Jedna obserwacja na koniec tej listy: wielkie litery i słowo „WAŻNE” działają wyłącznie wtedy, gdy są rzadkie. Poradnik Claude Code radzi wyróżnić w ten sposób pojedynczą instrukcję, którą model uparcie pomija. Jeśli wyróżnisz dziesięć, żadna się nie wyróżnia. Pamiętasz prompt z dopiskiem „PAMIĘTAJ, ŻE…” z artykułu o briefie? Objaw ten sam, stadium bardziej zaawansowane.

Przykład: AGENTS.md dla małego projektu analitycznego

Zobaczmy, jak to wygląda razem. Poniżej plik dla fikcyjnego, ale bardzo typowego projektu: cotygodniowego raportu sprzedaży.

# Raport sprzedaży tygodniowej

Raport dla zarządu, odświeżany w poniedziałki do 9:00.
Odbiorca czyta podsumowanie i jeden wykres, szczegóły są w załączniku.

## Struktura
- `dane/surowe/`: eksporty z systemu sprzedaży, tylko do odczytu
- `dane/robocze/`: pliki pośrednie, można je usuwać i odtwarzać
- `sql/`: zapytania, jedno zadanie na plik
- `raport/`: wynik (HTML i CSV)
- `docs/slownik.md`: definicje pojęć i źródła prawdy

## Polecenia
- Odświeżenie danych: `python odswiez.py`
- Raport: `python raport.py --tydzien ostatni`
- Kontrola: `python kontrola.py` (suma sprzedaży zgodna
  z raportem finansowym z dokładnością do 1 zł)

## Definicje
- Klient: osoba z co najmniej jednym opłaconym zamówieniem.
- Przychód: wartość netto opłaconych zamówień, po zwrotach.
- Pełne definicje: `docs/slownik.md`. Przy sprzecznościach
  wygrywa system finansowy.

## Bezpieczeństwo
- Baza danych: użytkownik tylko do odczytu, dane dostępowe w `.env`.
- Danych osobowych klientów nie wysyłamy do zewnętrznych narzędzi.
- Pliki w `dane/surowe/` zostają w stanie oryginalnym.

## Workflow
- Każda zmiana w osobnej gałęzi z numerem zadania.
- Przed zakończeniem zadania uruchom kontrolę i pokaż jej wynik.
- Zmianę definicji wskaźnika zatwierdza właściciel raportu.

Plik ma około trzydziestu linijek i mieści się na jednym ekranie. Zwróć uwagę na trzy rzeczy. Polecenie kontrolne ma wpisane kryterium, czyli zgodność z raportem finansowym, więc agent wie, kiedy praca jest skończona. Definicje są krótkie, a pełny słownik leży osobno i agent sięga po niego wtedy, gdy go potrzebuje. Sekcja bezpieczeństwa mówi, gdzie są sekrety, i sama żadnego sekretu nie zawiera.

Czego tu brakuje? Opisu każdego skryptu, historii projektu, listy osób w zespole i porad w rodzaju „pracuj starannie”. Brakuje ich celowo.

Hierarchia: plik globalny, projektowy i lokalny

Jeden plik na projekt wystarcza na start, ale narzędzia obsługują więcej poziomów i warto wiedzieć, jak się one składają.

Claude Code rozróżnia kilka zakresów. Plik w katalogu użytkownika (~/.claude/CLAUDE.md) obowiązuje we wszystkich Twoich projektach i nadaje się na osobiste preferencje, na przykład język odpowiedzi. Plik w folderze projektu trafia do repozytorium i obowiązuje cały zespół. Plik CLAUDE.local.md służy do prywatnych ustawień w jednym projekcie i dopisuje się go do .gitignore, żeby nie trafił do wspólnej wersji. Organizacje mogą dodatkowo rozesłać plik zarządzany centralnie, z firmowymi zasadami. Pliki z folderów nadrzędnych Claude Code wczytuje przy starcie, a pliki z podfolderów dopiero wtedy, gdy zaczyna pracować na plikach w danym podfolderze. Wszystkie znalezione pliki są sklejane w jeden kontekst, a treść najbliższa folderowi roboczemu trafia na koniec.

Codex działa podobnie. Plik globalny trzyma w swoim katalogu domowym (domyślnie ~/.codex), a w projekcie przechodzi od głównego folderu do bieżącego i z każdego poziomu bierze najwyżej jeden plik. Instrukcje bliższe miejscu pracy trafiają później, więc mają pierwszeństwo przed ogólniejszymi. Strona agents.md formułuje tę zasadę najkrócej: wygrywa najbliższy plik w drzewie folderów, a polecenie wpisane wprost w rozmowie wygrywa ze wszystkim.

Praktyczna rada: preferencje osobiste trzymaj w pliku globalnym, zasady zespołu w pliku projektu, a wyjątki dla jednej części projektu (na przykład folderu z zapytaniami SQL) w pliku w tym folderze. I pilnuj, żeby poziomy sobie nie przeczyły. Dokumentacja Claude Code ostrzega, że przy dwóch sprzecznych instrukcjach model może wybrać którąkolwiek z nich. Sprzeczność w instrukcjach działa jak rzut monetą, z tą różnicą, że nawet nie wiesz, że rzucasz.

Instrukcja działa jak rada doświadczonego kolegi

Jedna rzecz, którą warto zrozumieć, zanim zaczniesz wpisywać do pliku zakazy. Claude Code traktuje CLAUDE.md jako kontekst. Dokumentacja wprost zaznacza, że takie instrukcje kształtują zachowanie modelu, ale niczego nie blokują. Model zwykle ich słucha, ale „zwykle” to za mało, gdy stawką jest baza produkcyjna.

Dlatego twarde granice ustawia się gdzie indziej. W Claude Code służą do tego uprawnienia oraz hooki, czyli skrypty uruchamiane automatycznie w określonych momentach pracy. W projektach analitycznych najważniejszą granicą jest dostęp do danych: jeśli agent ma nie zmieniać bazy, dostaje użytkownika z prawem wyłącznie do odczytu. Instrukcja w AGENTS.md tłumaczy zasadę, a uprawnienia bazy jej pilnują. Więcej o pracy z bazą danych pisze Kasia w artykule od pytania biznesowego do SQL z AI, a w kursie wracamy do tego w czwartym tygodniu, przy bezpiecznym podłączaniu bazy.

Utrzymanie: plik żyje jak kod

Pierwszą wersję pliku łatwo napisać. Claude Code ma nawet polecenie /init, które przegląda projekt i proponuje szkic CLAUDE.md z poleceniami i konwencjami, jakie udało mu się znaleźć. Trudniejsze jest to, co dzieje się po miesiącu.

Pliki z instrukcjami starzeją się szybciej, niż się wydaje. Zmienia się struktura folderów, ktoś zmienia nazwę skryptu, definicja przychodu dostaje wyjątek. Każda taka zmiana, której zabrakło w instrukcjach, sprawia, że agent zaczyna pracować na nieaktualnej mapie. Gorzej, robi to z pełnym przekonaniem.

Kilka zasad, które się u mnie sprawdzają:

1. Kto zauważa, ten poprawia. Jeśli drugi raz tłumaczysz agentowi to samo, dopisz linijkę od razu, zanim zapomnisz. Możesz poprosić agenta, żeby sam zaproponował poprawkę, ale zatwierdzasz ją Ty.
2. Zmiana instrukcji przechodzi przegląd. Plik z instrukcjami zmienia zachowanie wszystkich agentów w projekcie, więc zasługuje na tę samą kontrolę co kod. W repozytorium oznacza to, że poprawka trafia do historii zmian i ktoś ją ogląda przed zatwierdzeniem.
3. Regularne cięcie. Raz na jakiś czas przeczytaj plik od początku do końca i usuń to, co się zdezaktualizowało albo co model robi dobrze bez instrukcji. Poradnik Claude Code radzi traktować ten plik jak kod: przeglądać go, gdy coś idzie źle, regularnie przycinać i sprawdzać, czy zmiana rzeczywiście zmienia zachowanie modelu.
4. Notatki dla ludzi osobno. Uwagi przeznaczone dla osób utrzymujących plik możesz zostawić w komentarzu HTML. Claude Code wycina takie komentarze przed wczytaniem pliku, więc nie zużywają kontekstu.

Skills i MCP: co się nie mieści w AGENTS.md

Prędzej czy później plik zaczyna puchnąć od procedur. Przygotowanie raportu miesięcznego w dwunastu krokach. Aktualizacja słownika danych w ośmiu. Każda z nich przydaje się raz w miesiącu, a wczytuje się przy każdej sesji.

Na to są Skills, którymi zajmujemy się w trzecim temacie drugiego tygodnia. Skill to osobny plik z procedurą powtarzalnego zadania. Claude Code przy starcie wczytuje sam krótki opis każdego skilla, a pełną treść dopiero wtedy, gdy zadanie jej wymaga. Skills opierają się na otwartym standardzie Agent Skills, więc tę samą procedurę mogą wykorzystać różne narzędzia. Podział jest więc czytelny: AGENTS.md zawiera fakty i zasady potrzebne zawsze, skill zawiera procedurę potrzebną czasem.

Czwarty temat tego samego tygodnia to MCP, czyli sposób podłączania AI do narzędzi takich jak repozytorium, Notion czy Linear. Szczegóły zostawiam na inny artykuł. Dla pliku z instrukcjami ważne jest jedno: warto w nim zapisać, z których narzędzi agent korzysta do odczytu, a które zmiany wymagają Twojej zgody. A jeśli zastanawiasz się, czy do Twojego zadania w ogóle potrzebny jest agent, zajrzyj do tekstu o tym, jak wybrać między modelem, czatem i agentem.

Plan na pierwszy tydzień

Do startu wystarczy folder z jedną analizą, którą robisz regularnie. Rozpisałem to na pięć dni, po kwadransie dziennie.

1. Poniedziałek: README. Trzy akapity: co to za projekt, skąd są dane, jak go uruchomić. Pisz dla kolegi, który zastąpi Cię podczas urlopu.
2. Wtorek: AGENTS.md. Sześć nagłówków z tego artykułu, najwyżej jeden ekran tekstu. Zacznij od poleceń i definicji, bo dają najwięcej.
3. Środa: CLAUDE.md. Jedna linijka @AGENTS.md, jeśli pracujesz w Claude Code. Poleceniem /context sprawdź, czy plik się wczytał.
4. Czwartek: notatnik poprawek. Pracuj normalnie i zapisuj każdą poprawkę, którą wpisujesz agentowi. Te, które powtarzają się dwa razy, trafiają do pliku.
5. Piątek: cięcie. Przeczytaj AGENTS.md i przy każdej linijce zadaj pytanie z poradnika: czy bez niej model popełni błąd?

Pamięć, która zostaje w firmie

Na koniec efekt uboczny, który cenię najbardziej. Dobrze utrzymany AGENTS.md szybko staje się najlepszą dokumentacją projektu, jaką kiedykolwiek miałeś. Pisany dla agenta, więc konkretny i bez ozdobników. Z poleceniami, które naprawdę działają, bo agent uruchamia je codziennie i od razu widać, gdy któreś przestaje działać. Nowa osoba w zespole czyta go w dziesięć minut i od pierwszego dnia wie, gdzie są dane, jak sprawdzić wynik i kogo zapytać o definicję.

W kursie drugi tydzień zaczyna się od wiedzy firmy i źródeł prawdy, a kończy organizacją pracy w Linearze. Repozytorium jako kontekst projektu leży pośrodku i spina oba końce: wiedza firmy trafia do plików, a zadania odwołują się do tych plików. Od tego momentu agent przestaje zaczynać każdy dzień od zera. Ty też.