Co to jest Agents.md?
Autor: Redakcja Domeny.ForSale Opublikowano
W skrócie: AGENTS.md to plik tekstowy z instrukcjami dla agentów AI pracujących nad projektem, najczęściej nad kodem. Opisuje między innymi sposób uruchamiania testów, organizację projektu i zasady wprowadzania zmian. Sam niczego nie uruchamia: jego działanie zależy od tego, czy używane narzędzie odczytuje ten plik i jak interpretuje zawarte w nim wskazówki.
Do czego służy plik AGENTS.md
Agent AI to narzędzie, które nie tylko odpowiada na pytania, ale może też wykonywać zadania, na przykład przeglądać pliki, edytować kod i uruchamiać polecenia. Potrzebuje przy tym kontekstu konkretnego projektu. Bez niego może wybrać niewłaściwy sposób instalacji zależności albo zmodyfikować pliki, których zespół nie edytuje ręcznie.
AGENTS.md pozwala zapisać taki kontekst w repozytorium, czyli miejscu przechowywania kodu i historii jego zmian. Plik korzysta z Markdown — prostego formatu tekstowego obsługującego nagłówki, listy i bloki kodu. Można go edytować w zwykłym edytorze i przeglądać razem z pozostałymi zmianami projektu.
To konwencja przekazywania instrukcji, a nie program, model AI ani mechanizm nadawania uprawnień. Zapis „nie zmieniaj konfiguracji produkcyjnej” jest wskazówką dla agenta, lecz nie blokuje technicznie dostępu do tej konfiguracji.
AGENTS.md a README — różne zadania dokumentacji
README.md zwykle przedstawia projekt człowiekowi: wyjaśnia jego przeznaczenie, instalację i podstawowe użycie. AGENTS.md skupia się na tym, jak agent ma wykonywać pracę w danym repozytorium. Oba pliki mogą się uzupełniać, zamiast powielać tę samą dokumentację.
Przykładowo README biblioteki może pokazywać, jak wykorzystać ją we własnej aplikacji. Instrukcje dla agenta mogą natomiast określać, że po zmianie publicznego interfejsu trzeba zaktualizować przykłady i uruchomić określony zestaw testów.
Nie należy też mylić AGENTS.md z llms.txt, plikiem proponowanym jako sposób udostępniania modelom językowym informacji o treściach witryny. AGENTS.md dotyczy przede wszystkim pracy nad projektem, a nie prezentowania zawartości strony. Jego obecność nie jest deklaracją widoczności strony w wyszukiwarkach ani usługach AI.
Gdzie umieścić plik i czy każde narzędzie go odczyta
Typowym miejscem jest główny katalog repozytorium. Przy tworzeniu pliku użyj nazwy AGENTS.md, wielkimi literami: na systemach rozróżniających wielkość liter Agents.md może być innym plikiem. Nie zakładaj, że narzędzie rozpozna dowolny wariant nazwy.
W większych projektach można spotkać dodatkowe pliki AGENTS.md w podkatalogach, na przykład osobno dla interfejsu użytkownika i części serwerowej. Pozwala to oddzielić reguły dotyczące różnych technologii. Zakres obowiązywania instrukcji i sposób rozstrzygania sprzeczności zależą jednak od narzędzia, więc nie należy przyjmować jednej hierarchii dla wszystkich agentów.
Przed wdrożeniem sprawdź w oficjalnej dokumentacji używanego agenta:
- czy obsługuje
AGENTS.mdi wymaga dodatkowej konfiguracji; - w jakich katalogach szuka instrukcji;
- czy odczytuje pliki z podkatalogów;
- jak łączy je z poleceniem użytkownika i innymi instrukcjami.
Samo dodanie pliku do repozytorium nie oznacza, że każda funkcja AI w edytorze zacznie go używać.
Co zapisać w instrukcjach dla agenta
Najbardziej przydatne są informacje, które ograniczają zgadywanie: rzeczywiste polecenia, lokalizacja ważnych plików oraz granice zleconej zmiany. Ogólne zalecenie „pisz dobry kod” nie mówi agentowi, jak zweryfikować wynik.
Przykładowy plik dla projektu JavaScript używającego npm może wyglądać tak. Polecenia mają sens tylko wtedy, gdy odpowiadają konfiguracji danego repozytorium:
## Praca nad projektem
## Uruchamianie i weryfikacja
- Instaluj zależności poleceniem `npm ci`.
- Uruchamiaj testy poleceniem `npm test`.
- Sprawdzaj reguły kodu poleceniem `npm run lint`.
- Jeśli nie możesz wykonać kontroli, podaj przyczynę.
## Organizacja plików
- Kod aplikacji znajduje się w `src/`.
- Nie edytuj ręcznie katalogu `generated/`.
## Zakres zmian
- Nie dodawaj zależności bez potwierdzenia użytkownika.
- Przy naprawie błędu dodaj test, który go odtwarza.
- Nie łącz naprawy z niezwiązanym porządkowaniem kodu.
W projekcie z kilkoma aplikacjami dopisz katalog, z którego trzeba uruchamiać każde polecenie. Jeśli testy wymagają dodatkowej usługi, opisz wymaganie i bezpieczny sposób przygotowania środowiska. Nie umieszczaj w instrukcjach haseł, tokenów ani innych sekretów.
Jak sprawdzić skuteczność i utrzymać aktualność
Dobrym sprawdzianem jest małe zadanie, na przykład poprawienie walidacji pojedynczego pola formularza. Obserwuj, czy agent korzysta z właściwych poleceń, omija pliki generowane automatycznie i informuje o niewykonanych testach. Jeśli narzędzie pokazuje wczytane instrukcje, sprawdź również tę informację.
Gdy agent popełni błąd, ustal najpierw, czy przeczytał plik. Dopisywanie kolejnych zakazów nie pomoże, jeśli problemem jest brak obsługi albo niewłaściwa lokalizacja. Jeśli instrukcja została odczytana, zastąp niejasny zapis konkretną czynnością lub warunkiem.
Traktuj AGENTS.md jak część utrzymywanej dokumentacji: aktualizuj go po zmianie poleceń, struktury katalogów i procesu testowania. Ograniczenia dostępu egzekwuj uprawnieniami oraz konfiguracją środowiska, nie samymi zdaniami w pliku. Na początek zapisz działające polecenia weryfikacji i najważniejsze ograniczenia, a następnie sprawdź je na jednym niewielkim zadaniu.
Zobacz też: Co to jest GitHub?
Przeczytaj także
