AGENTS.md: stałe instrukcje dla agentów kodujących

AGENTS.md to plik Markdown z trwałymi wskazówkami dla agentów kodujących pracujących w repozytorium. Według inicjatywy AGENTS.md pełni rolę przewidywalnego miejsca na komendy, konwencje i kontekst projektu, uzupełniając README pisane głównie dla ludzi. Nie jest specyfikacją jednej funkcji ani mechanizmem nadawania uprawnień. W AI SDLC pomaga agentowi rozpocząć pracę w tych samych ramach, w których działa zespół.

Co warto w nim zapisać?

Dobry plik odpowiada na kilka praktycznych pytań: gdzie leży kod, jak uruchomić aplikację i testy, jakie są granice modułów, które dane są wrażliwe, które pliki są generowane oraz co trzeba sprawdzić przed zakończeniem zmiany. Na przykład:

# Zasady pracy w repozytorium

## Sprawdzenie zmiany
- Uruchom test kontraktu API po zmianie endpointu.
- Nie edytuj plików wygenerowanych ręcznie; zmień źródło generatora.
- Zgłoś migrację bazy i plan wycofania w opisie PR.

## Dane i sekrety
- Nie zapisuj tokenów ani danych klientów w testach i logach.

Takie instrukcje powinny być konkretne i możliwe do sprawdzenia. „Pisz dobry kod” nie mówi agentowi, jakie zachowanie jest oczekiwane. „Po zmianie schematu uruchom wskazany test i pokaż wynik” daje kryterium odbioru. Jeśli polecenie wymaga dostępu do prywatnego systemu, opisz sposób pracy bez ujawniania sekretu.

Jak działa zakres instrukcji?

Plik w katalogu głównym obejmuje ogólne zasady repozytorium. W większym monorepo można dodać pliki bliżej poszczególnych pakietów. Dokumentacja AGENTS.md opisuje, że bliższy plik może doprecyzować reguły dla podprojektu, a bezpośrednie polecenie użytkownika ma pierwszeństwo. Rzeczywiste rozpoznawanie i kolejność instrukcji zależą jednak od użytego agenta, dlatego trzeba je przetestować zamiast zakładać identyczne zachowanie każdego narzędzia.

Przykład: główny AGENTS.md wymaga testów przed zakończeniem zadania, a apps/web/AGENTS.md dodaje kontrolę dostępności formularzy. Agent zmieniający formularz powinien zastosować obie reguły. Jeżeli pliki zawierają sprzeczne polecenia, zespół musi je rozstrzygnąć w dokumentacji; agent nie powinien po cichu wybrać wygodniejszej wersji.

Czego AGENTS.md nie zastępuje?

Nie zastępuje specyfikacji funkcji, która mówi, jaki rezultat ma dać konkretna zmiana. Nie zastępuje skilla, który przechowuje powtarzalną procedurę dla klasy zadań. Nie jest też policy engine: zapis „agent nie może usuwać danych” nie blokuje technicznie operacji, jeśli proces ma takie uprawnienie. Granice dostępu trzeba egzekwować przez role, polityki, izolację środowiska i przegląd zmian. W tym miejscu przydaje się porównanie RBAC, ABAC i ReBAC.

W systemie AI-native różnica jest szczególnie ważna. Prompt i plik instrukcji mogą skłonić agenta do ostrożności, ale nie są odpowiednikiem autoryzacji przy wywołaniu narzędzia. Jeżeli agent ma zapisać zmianę w ERP, decyzja o dopuszczeniu tej akcji powinna zapaść w kontrolowanym API.

Jak testować jakość instrukcji?

Wybierz trzy typowe zadania: małą poprawkę, zmianę API i zadanie w podkatalogu z dodatkowymi regułami. Zleć je agentowi i sprawdź, czy odczytał właściwy plik, uruchomił wymagane kontrole oraz odróżnił pliki źródłowe od generowanych. Następnie dodaj zadanie konfliktowe: bezpośrednia prośba użytkownika zmienia rutynowy sposób pracy. Oceń, czy agent jawnie rozpoznał różnicę i zachował granice bezpieczeństwa.

AGENTS.md powinien być żywą dokumentacją. Gdy komenda przestaje działać albo struktura repozytorium się zmienia, zaktualizuj instrukcję razem z kodem. Nie kopiuj do niej długich podręczników: podaj krótki zakres i link do dokumentacji, którą agent ma otworzyć tylko przy odpowiednim zadaniu. Dzięki temu plik pozostaje użyteczny także wtedy, gdy projekt rośnie.