Jak poprawnie przygotować plik AGENTS.md w projekcie

Czym jest AGENTS.md

AGENTS.md to zwykły plik w formacie Markdown znajdujący się w katalogu głównym repozytorium, który instruuje agenta programistycznego, jak pracować nad danym projektem. Oficjalna strona opisuje go jako „README dla agentów: dedykowane, przewidywalne miejsce na dostarczenie kontekstu i instrukcji, które pomogą agentom AI w pracy nad projektem”. Standard jest zarządzany przez Agentic AI Foundation pod egidą Linux Foundation i jest obsługiwany przez ponad dwudziestu agentów, w tym Codex, Cursor, Jules, Devin oraz GitHub Copilot (stan na lipiec 2026).

Istnienie tej konwencji wynika z przyczyn praktycznych. Nowy członek zespołu czyta plik README, zgaduje polecenie budowania i pyta kogoś, gdy jego domysł jest błędny. Agent nie może zapytać. Zgaduje, uruchamia npm test w projekcie korzystającym z pnpm test, odczytuje błąd i próbuje czegoś innego. Za każdy z tych tokenów ponosisz koszt. Zapisanie poprawnego polecenia raz eliminuje całą klasę tego typu błędów.

Nie ma wymaganych pól. Strona jest w tej kwestii jednoznaczna: „AGENTS.md to po prostu standardowy Markdown. Używaj dowolnych nagłówków; agent po prostu analizuje dostarczony tekst”. To cała specyfikacja. Wartość nie tkwi w formacie. Tkwi w fakcie, że plik znajduje się w ścieżce, którą każde narzędzie już sprawdza.

Lokalizacja plików i zasady pierwszeństwa

Pierwszy plik należy umieścić w katalogu głównym repozytorium. W przypadku monorepo można dodać kolejne pliki wewnątrz każdego podprojektu. Zasada jest prosta: agenty automatycznie odczytują najbliższy plik w drzewie katalogów, więc to on ma pierwszeństwo. Konflikt między dwoma plikami rozstrzygany jest na korzyść pliku, który jest aktualnie edytowany, a wszelkie instrukcje wpisane bezpośrednio w czacie nadpisują oba te pliki.

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

Zagnieżdżanie jest korzystne, ponieważ stanowi jedyny sposób na zdefiniowanie reguł, które są prawdziwe dla jednego folderu, a fałszywe dla kolejnego. Reguła typu "każdy endpoint waliduje swoje dane wejściowe" powinna znajdować się obok endpointów. W pliku głównym byłaby ładowana przy każdym niezwiązanym z tym zadaniu, nie przynosząc żadnych korzyści. Jeśli plik główny rozrósł się do sekcji przypisanych do poszczególnych usług, podział na strukturę zagnieżdżoną jest właściwym rozwiązaniem; określa on, które reguły należy przenieść niżej, a które powinny pozostać na najwyższym poziomie.

Co powinno znaleźć się w pliku AGENTS.md

Należy zapisać informacje, których agent nie jest w stanie ustalić na podstawie analizy kodu. Na początku należy umieścić dokładne polecenia budowania, testowania i lintowania w formie gotowej do wklejenia do terminala. Należy dodać polecenie uruchamiania pojedynczego testu, ponieważ agent, który potrafi uruchomić tylko cały zestaw, będzie wykonywał go czterdzieści razy. Należy wymienić konwencje odbiegające od domyślnych ustawień narzędzi, gdyż agent zna wartości domyślne i potrzebuje informacji tylko o wprowadzonych odstępstwach. Należy dodać format wiadomości commitów oraz zasady dotyczące pull requestów, jeśli takie istnieją.

Instrukcje muszą być na tyle konkretne, aby można było zweryfikować ich wykonanie. "Używaj wcięć 2-spacyjnych" to użyteczna instrukcja, ponieważ można sprawdzić, czy została zastosowana. "Formatuj kod poprawnie" taką nie jest, ponieważ nie da się tego obiektywnie zweryfikować. To samo dotyczy lokalizacji: "Handlery API znajdują się w src/api/handlers/" jest lepsze niż "utrzymuj porządek w plikach".

Warto również uwzględnić zasady negatywne. "Nigdy nie edytuj plików w dist/, są one generowane przez npm run build" zapobiega konkretnemu błędowi, a ponieważ wskazuje przyczynę, agent może samodzielnie wywnioskować podobne przypadki, których nie opisano. W tym miejscu powinny znaleźć się również zasady dotyczące zakresu zmian, ponieważ agent pozostawiony sam sobie będzie modyfikował więcej, niż zlecono: jedna powszechnie kopiowana umiejętność polega wyłącznie na wymuszaniu najmniejszej działającej zmiany.

Czego nigdy nie umieszczać w pliku

Nigdy nie umieszczaj sekretów w tych plikach. Plik jest zatwierdzany w git, ładowany do kontekstu na początku każdej sesji i wysyłany do dostawcy modelu przy każdym żądaniu. Klucz API w pliku AGENTS.md staje się kluczem API w historii repozytorium oraz w logach stron trzecich. Zamiast wklejać sekret, wskaż go: „hasło do bazy danych znajduje się w .env, który jest ignorowany przez git; zapytaj przed jego odczytaniem”. Szersze zasady postępowania opisano w utrzymywanie poświadczeń poza zasięgiem agenta.

Pomiń wszystko, co agent może wywnioskować samodzielnie. Wklejona lista plików katalogu, kopia listy zależności czy przegląd architektury powtarzający nazwy folderów: wszystko to staje się nieaktualne tydzień po napisaniu, a w międzyczasie zajmuje miejsce w kontekście każdej sesji. Zachowaj informacje o pułapkach i powodach ich istnienia. Pomiń inwentaryzację. Powody warto oddzielić, ponieważ agent, który nie rozumie, dlaczego struktura ma nietypowy kształt, może go po cichu zrefaktoryzować, co uzasadnia utrzymywanie pliku DESIGN.md obok tego.

CLAUDE.md jako instancja Claude Code dla tego samego zamysłu

Claude Code odczytuje CLAUDE.md i nie odczytuje samodzielnie AGENTS.md. Plik projektu znajduje się w ./CLAUDE.md lub ./.claude/CLAUDE.md, osobiste preferencje dla każdego projektu umieszcza się w ~/.claude/CLAUDE.md, a organizacja może wdrożyć plik dla całej maszyny w /etc/claude-code/CLAUDE.md w systemach Linux. Wykryte pliki są łączone w kolejności od głównego katalogu systemu plików aż do katalogu roboczego, więc plik znajdujący się najbliżej miejsca uruchomienia sesji jest odczytywany jako ostatni. Każda sesja rozpoczęta w tym katalogu ładuje ten sam stos, co umożliwia równoległe uruchamianie dwóch sesji na jednej maszynie, a sesje te mogą przekazywać sobie zadania w trakcie pracy.

Jeśli repozytorium posiada już plik AGENTS.md, nie należy utrzymywać drugiej kopii. Należy go zaimportować, a następnie dodać tylko elementy specyficzne dla Claude:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Dowiązanie symboliczne (symlink) sprawdza się, gdy nie ma potrzeby dodawania niczego więcej:

ln -s AGENTS.md CLAUDE.md

Polecenie nie zwraca żadnych komunikatów w przypadku powodzenia. W następnej sesji należy uruchomić /context i potwierdzić, że CLAUDE.md pojawia się w sekcji Memory files. Jeśli plik nie znajduje się na tej liście, oznacza to, że nie został załadowany, więc zawarte w nim instrukcje nie zostały zastosowane. Aby wygenerować pierwszy szkic zamiast pisać go samodzielnie, należy uruchomić /init: narzędzie przeanalizuje bazę kodu i utworzy plik początkowy, a jeśli plik CLAUDE.md już istnieje, zaproponuje ulepszenia zamiast nadpisywania.

Należy utrzymywać długość każdego pliku poniżej około 200 linii. Dłuższe pliki zajmują więcej miejsca w oknie kontekstowym, co obniża skuteczność modelu. Aby sprawdzić, co jeszcze zajmuje to miejsce, warto zapoznać się z analizą tego, co faktycznie wypełnia okno kontekstowe agenta.

Jeden punkt wymaga podkreślenia. Plik AGENTS.md stanowi wytyczne, a nie system uprawnień. Treść jest przekazywana jako zwykły kontekst, więc model odczytuje ją i zazwyczaj stosuje się do niej, jednak nic nie blokuje działań sprzecznych z tymi zapisami. Gdy napisana reguła jest pomijana bez wyraźnego powodu, przed ponownym redagowaniem treści należy przeanalizować przyczyny pomijania instrukcji. W przypadku reguł, które muszą być przestrzegane bezwzględnie, takich jak „nigdy nie wypychaj zmian do main”, należy użyć hooka lub ustawień uprawnień, ponieważ są one wykonywane jako kod i nie zależą od decyzji modelu o posłuszeństwie.

Narzędzia automatyzujące tworzenie tych plików

Dwa projekty z listy trendów GitHub z dnia 30 lipca 2026 roku wskazują kierunek rozwoju tej konwencji.

agent0ai/dox (1 368 gwiazdek na dzień lipca 2026) to framework służący do utrzymywania aktualnego drzewa plików AGENTS.md. Projekt nie dostarcza żadnego pakietu ani środowiska uruchomieniowego. Instalacja polega na skopiowaniu zawartości pliku AGENTS.md projektu do własnego głównego pliku AGENTS.md. W przypadku istniejącego projektu należy wydać agentowi polecenie:

Initialize DOX tree for this project now.

Następnie agent tworzy podrzędne pliki AGENTS.md wraz z ich indeksami, przeszukuje drzewo przed wprowadzeniem jakichkolwiek zmian i aktualizuje odpowiednią dokumentację po zatwierdzeniu zmian. Założenie stojące za tym rozwiązaniem jest takie, że dokumentacja utrzymywana przez agenta jako efekt uboczny jego pracy pozostaje zgodna ze stanem faktycznym, podczas gdy dokumentacja aktualizowana ręcznie przez człowieka – nie.

HUMAN.md, ta sama sztuczka zastosowana wobec Ciebie

Intuition-Lab/personal-model (1 260 gwiazdek według stanu na lipiec 2026) stosuje ten wzorzec do osoby, a nie do repozytorium. Projekt traktuje plik HUMAN.md jako wynik działania systemu, a nie jako plik tworzony ręcznie: „żywy model tego, co jest obecnie istotne, jak zazwyczaj podejmujesz decyzje i na czym skupiasz swoją uwagę”. Narzędzie działa lokalnie w systemie macOS 13 lub nowszym, rejestruje aktywność po udzieleniu uprawnień w systemie macOS i udostępnia wynik agentom za pośrednictwem protokołu MCP (model context protocol). Krótka ścieżka instalacji:

uv tool install personal-model
persome onboard
persome model open --after 30

Nie potrzebujesz niczego z powyższych, aby uzyskać większość korzyści. Ręcznie napisany plik HUMAN.md ma około dwudziestu linii: Twoja rola, strefa czasowa, stos technologiczny, z którego faktycznie korzystasz, decyzje, które już podjąłeś i których nie chcesz ponownie omawiać, oraz poziom szczegółowości odpowiedzi, jakiego oczekujesz. Oszczędza to wielokrotnego wyjaśniania tych samych kwestii, podobnie jak plik projektu, tyle że na wyższym poziomie abstrakcji.

Jedno ostrzeżenie. Plik HUMAN.md jest profilem osoby, więc z definicji zawiera dane wrażliwe. Nie umieszczaj go w publicznym repozytorium. Przechowuj go w ~/.claude/CLAUDE.md lub w pliku CLAUDE.local.md dodanym do .gitignore w katalogu głównym projektu, który jest ładowany wraz z plikiem podlegającym kontroli wersji i traktowany w ten sam sposób.

Szablon startowy do skopiowania

Treść jest celowo zwięzła. Należy usunąć sekcje nieistotne i powstrzymać się od dodawania elementów, których nie można utrzymać w aktualności.

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

Należy zapisać treść, a następnie poprawić ją w miejscu. Sygnałem do dodania wiersza jest dwukrotne wpisanie tej samej poprawki na czacie. Ta zasada utrzymuje użyteczność pliku i zapobiega jego rozrostowi do dokumentacji, której nikt nie czyta, w tym maszyny. Po ustabilizowaniu plik wędruje wraz z repozytorium, co ma kluczowe znaczenie, gdy agent działa poza lokalnym laptopem: uruchamianie agenta programistycznego na własnym serwerze opisuje tę konfigurację.

FAQ

Czy AGENTS.md to ten sam plik co CLAUDE.md?

To ta sama koncepcja pod dwiema nazwami. Claude Code odczytuje CLAUDE.md i ignoruje AGENTS.md, chyba że zostaną one połączone. Należy utrzymać jeden plik jako źródło prawdy i powiązać z nim drugi, używając linii o treści @AGENTS.md na początku pliku CLAUDE.md lub za pomocą ln -s AGENTS.md CLAUDE.md. Dwie pełne kopie utrzymywane oddzielnie przestaną być spójne w ciągu miesiąca.

Czy utworzenie AGENTS.md gwarantuje, że agent będzie się do niego stosował?

Nie. Treść jest dostarczana jako kontekst, więc model ją odczytuje i zazwyczaj przestrzega, jednak nic nie blokuje działań sprzecznych z tymi wytycznymi. Niejasne instrukcje są realizowane najmniej niezawodnie, a dwa pliki zawierające sprzeczne wskazówki sprawiają, że agent wybiera jedną z nich w sposób arbitralny. W przypadku reguły, która musi być zawsze przestrzegana, należy użyć hooka lub reguły uprawnień, które są wymuszane przez klienta niezależnie od decyzji modelu.

Czy plik AGENTS.md powinien być dodawany do git?

Tak, w przypadku wszelkich informacji dotyczących projektu: poleceń budowania, struktury, konwencji. Na tym polega cel tego pliku, ponieważ agenci współpracowników rozpoczynają pracę z tym samym kontekstem co Twój. Wszystko, co jest osobiste lub specyficzne dla jednej maszyny, powinno znajdować się w oddzielnym pliku ignorowanym przez git, a dane uwierzytelniające nie powinny znajdować się w żadnym z nich.

Czym jest HUMAN.md i czy jest mi potrzebny?

HUMAN.md to czytelny dla maszyny profil osoby, a nie projektu. Zawiera on Twoją rolę, ograniczenia oraz podjęte już decyzje, dzięki czemu nie są one ponownie omawiane w każdej sesji. Nie potrzeba żadnych narzędzi, aby zacząć: dwadzieścia ręcznie napisanych linii w pliku instrukcji użytkownika zapewnia większość korzyści. Należy traktować go jako dane osobowe i nie umieszczać w żadnym repozytorium, które jest wypychane (push) na serwer.