AGENTS.md: instrukcje dla agentów AI

AGENTS.md to konwencjonalna nazwa pliku Markdown, w którym opisujesz zasady współpracy z agentem AI nad projektem. Zamiast wklejać te same informacje do każdego polecenia, trzymasz je blisko kodu lub materiałów roboczych. Plik może wyjaśniać, czym jest projekt, gdzie znajdują się ważne części systemu, jak uruchomić testy, których plików nie wolno zmieniać i jaki styl ma mieć wynik. Otwarty format AGENTS.md przedstawia go jako przewidywalne miejsce na instrukcje dla agentów programistycznych. Narzędzia obsługują ten wzorzec na różne sposoby, dlatego przed użyciem sprawdź dokumentację wybranego agenta.

Dla eksperta albo solopreneurki sens tego pliku nie kończy się na kodzie. Jeżeli agent pomaga rozwijać stronę, automatyzację, bazę wiedzy lub zestaw promptów, potrzebuje stałego kontekstu biznesowego: odbiorcy, oferty, nazw produktów, zasad tonu głosu, źródeł prawdy i granic bezpieczeństwa. Bez tego będzie improwizował. Dobrze napisany AGENTS.md skraca start zadania i ogranicza sytuację, w której agent poprawnie wykonuje techniczną prośbę, lecz psuje nazwę usługi, prowadzi CTA do złego miejsca albo zmienia produkcję bez weryfikacji.

Najważniejsza zasada brzmi: zapisuj tylko informacje, które są trwałe, konkretne i możliwe do sprawdzenia. Przydatne są: komendy uruchomienia i testów, nazwy katalogów, wymagane zmienne środowiskowe bez sekretów, reguły routingu, format danych, definicja gotowego zadania oraz lista operacji wymagających zgody człowieka. Słabe instrukcje typu „pisz profesjonalnie” albo „nie rób błędów” nie dają agentowi kryterium decyzji. Lepsza reguła mówi: „po zmianie formularza sprawdź odpowiedź API, tag kontaktu i komunikat błędu, a nie wysyłaj kampanii bez jawnego polecenia”.

Praktyczny przykład: masz stronę z formularzem konsultacji i automatyzację, która tworzy lead w CRM. W AGENTS.md zapisz docelowy adres strony, nazwę endpointu, wymagane pola formularza, gdzie trzymana jest definicja CRM oraz test po zmianie. Dodaj też granicę: agent może odczytać statystyki i przygotować draft, ale nie może wysłać maila, usunąć danych ani zmienić aktywnej automatyzacji. Gdy później prosisz o „dodaj pole branża”, agent ma już instrukcję, jak znaleźć implementację, co przetestować i gdzie kończy się jego uprawnienie.

W większym projekcie warto stosować warstwy instrukcji. Główny plik w katalogu projektu opisuje reguły wspólne, a dodatkowy AGENTS.md w podkatalogu może opisywać tylko aplikację, CMS albo integrację. Dokumentacja Codexu opisuje taki model jako łączenie globalnych wytycznych z bardziej lokalnymi nadpisaniami. Nie zakładaj jednak, że każdy agent odczyta pliki identycznie lub że priorytety będą takie same. Po dodaniu pliku wykonaj małe, bezpieczne zadanie i sprawdź log albo wynik, zamiast traktować samą obecność pliku jako gwarancję zachowania.

AGENTS.md nie jest bazą wiedzy dla modelu ani sposobem na przechowanie całej firmy w jednym dokumencie. Zbyt długi plik zwiększa koszt kontekstu, utrudnia znalezienie reguły i szybko się dezaktualizuje. Nie wpisuj do niego kluczy API, haseł, danych klientów ani zmiennych danych operacyjnych. Sekrety powinny trafić do bezpiecznego menedżera sekretów lub środowiska, a aktualne fakty do źródła prawdy, do którego agent sięga w kontrolowany sposób. Plik ma pomagać wybrać właściwy proces, nie kopiować całą dokumentację.

Traktuj instrukcje jak kod operacyjny: wersjonuj je, przeglądaj po ważnych zmianach i usuwaj reguły, które nie są już prawdziwe. Każda instrukcja powinna odpowiadać na jedno z pytań: co jest celem, gdzie są dane, jak zweryfikować wynik lub czego agent nie może robić. Jeśli pojawia się powtarzalny błąd, dopisz konkretny test albo ograniczenie zamiast mnożyć ogólne zakazy. Po kilku tygodniach zobaczysz, które zasady naprawdę zapobiegają poprawkom. To jest lepszy materiał do utrzymania niż ściana promptu tworzona przy każdym nowym zadaniu.