--- title: "AGENTS.md: stałe instrukcje dla agentów kodujących" url: "https://majchrzycki.com/blog/agents-md-instrukcje-agentow-ai-sdlc" description: "Jak napisać AGENTS.md, by agent znał architekturę, komendy i granice zmian? Przykład, hierarchia instrukcji, bezpieczeństwo i odbiór w AI SDLC." --- # AGENTS.md: stałe instrukcje dla agentów kodujących 9 sierpnia 2026· Aktualizacja: 28 września 2026·2 min czytania·Krzysztof Majchrzycki Temat: [AI SDLC](https://majchrzycki.com/blog/filar/ai-sdlc) **`AGENTS.md` to plik Markdown z trwałymi wskazówkami dla agentów kodujących pracujących w repozytorium.** Według [inicjatywy AGENTS.md](https://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](https://majchrzycki.com/blog/filar/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](https://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](https://majchrzycki.com/blog/github-spec-kit-specyfikacja-ai-sdlc), która mówi, jaki rezultat ma dać konkretna zmiana. Nie zastępuje [skilla](https://majchrzycki.com/blog/skills-md-skill-md-umiejetnosci-agentow), 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](https://majchrzycki.com/blog/rbac-abac-rebac-uprawnienia-agentow-ai). 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. - Agenci AI ## Przełóż temat na projekt w Twojej firmie Zobacz zakres współpracy: od rozpoznania procesu i danych po projekt rozwiązania AI. [Zobacz współpracę](https://majchrzycki.com/wspolpraca) ## Czytaj dalej - [SKILLS.md czy SKILL.md? Umiejętności agentów AI](https://majchrzycki.com/blog/skills-md-skill-md-umiejetnosci-agentow) - [Pluginy agentów AI: Claude, ChatGPT, Codex i Copilot](https://majchrzycki.com/blog/pluginy-agentow-claude-chatgpt-codex-copilot) - [GitHub Spec Kit: specyfikacja przed kodowaniem z AI](https://majchrzycki.com/blog/github-spec-kit-specyfikacja-ai-sdlc) - [Excalidraw: szkic architektury AI, który uruchamia rozmowę](https://majchrzycki.com/blog/excalidraw-diagramy-systemow-ai-i-ontologii)