Wzorce AGENTS.md: co naprawdę zmienia zachowanie agenta

Mój pierwszy plik AGENTS.md był wklejonym na 200 linii przewodnikiem stylu naszego zespołu. Znalazły się w nim konwencje nazewnicze, listy kontrolne do przeglądów kodu, procedury wdrożeniowe i zasady architektoniczne. Agent zignorował większość z tego. Nie dlatego, że instrukcje były błędne, lecz dlatego, że była to dokumentacja, a nie instrukcja operacyjna.

Plik AGENTS.md powinien zawierać instrukcje oparte na poleceniach, z dokładnymi wywołaniami, sekcje uporządkowane według zadań (kodowanie, przegląd, wydanie) oraz jawne kryteria „gotowe”, które agent jest w stanie zweryfikować. Należy pisać politykę operacyjną, a nie dokumentację dla ludzi. Trzeba podać konkretne polecenia powłoki, konfiguracje lintera i polecenia testowe, które agent ma uruchomić. Należy unikać akapitów ciągłego tekstu, niejednoznacznych poleceń w rodzaju „zachowaj ostrożność” oraz sprzecznych priorytetów bez jawnej kolejności. AGENTS.md to otwarty standard przyjęty przez ponad 60 000 projektów, który działa w Codex, Cursor, Copilot i innych narzędziach agentowych.

To rozróżnienie waży więcej niż jakikolwiek pojedynczy wzorzec opisany w tym wpisie. AGENTS.md to polityka operacyjna dla agenta AI, a nie plik README dla ludzi. Agent nie musi rozumieć, dlaczego stosuje się konwencjonalne commity. Musi znać dokładne polecenie do uruchomienia i wiedzieć, jak wygląda „gotowe”.

TL;DR

Większość problemów z plikiem AGENTS.md bierze się z pisania dokumentacji dla ludzi zamiast instrukcji operacyjnej dla agenta. Skuteczne pliki są oparte na poleceniach (dokładne wywołania, nie opisy), uporządkowane według zadań (sekcje: kodowanie, przegląd, wydanie) oraz mają zdefiniowane zamknięcie (jawne kryteria „gotowe”). Antywzorce, które są niezawodnie ignorowane: akapity ciągłego tekstu, niejednoznaczne polecenia („zachowaj ostrożność”) i sprzeczne priorytety. AGENTS.md to otwarty standard przyjęty przez ponad 60 000 projektów ¹, który działa w Codex, Cursor, Copilot, Amp, Devin Desktop i wielu innych narzędziach ².

Kontekst: AGENTS.md jest nadzorowany przez Agentic AI Foundation działającą pod egidą Linux Foundation ³, a wśród członków platynowych znajdują się Anthropic, Google, Microsoft i OpenAI. Ten wpis omawia wzorce praktyczne. Konfigurację właściwą dla Codeksa opisuje przewodnik po Codex. Odpowiednik w Claude Code (CLAUDE.md) opisuje przewodnik po Claude Code.

Co bywa ignorowane

Te wzorce niezawodnie nie powodują żadnej obserwowalnej zmiany w zachowaniu agenta. Każdy z nich udało się wskazać dzięki uruchamianiu identycznych zadań z daną instrukcją i bez niej, a następnie porównaniu poprawności wykonania zadań w ponad 10 przebiegach na wzorzec. Analiza ponad 2500 repozytoriów z plikami AGENTS.md przeprowadzona przez GitHub prowadzi do tego samego wniosku: „Większość plików dla agentów zawodzi, ponieważ są zbyt ogólnikowe” ¹¹. Poniższe wzorce nie poprawiły poprawności wykonania w żaden mierzalny sposób.

Akapity ciągłego tekstu bez poleceń

<!-- BAD: Agent skips this -->
We value clean, well-tested code. Our team follows TDD principles
and believes in comprehensive test coverage. Please ensure all
changes are properly tested before submitting.

Agent to czyta, zapamiętuje jako mgliste preferencje i pisze kod bez testów. Nie ma tu żadnej instrukcji do wykonania, żadnego polecenia do uruchomienia, żadnego progu do osiągnięcia ani definicji „poprawnie przetestowane”.

Niejednoznaczne polecenia

<!-- BAD: "Careful" means nothing to an agent -->
- Be careful with database migrations
- Optimize queries where possible
- Handle errors gracefully

„Ostrożnie” nie jest ograniczeniem. „Tam, gdzie to możliwe” nie jest warunkiem wyzwalającym. „Elegancko” nie jest specyfikacją zachowania. Brzmi to jak wskazówki od człowieka dla człowieka, a nie instrukcja dla agenta. Dla porównania to, co działa: „Uruchom alembic check przed zastosowaniem migracji. Przerwij, jeżeli brakuje ścieżki wycofania”.

Sprzeczne priorytety

<!-- BAD: Which one wins? -->
- Move fast and ship quickly
- Ensure comprehensive test coverage
- Keep the runtime budget under 5 minutes
- Run the full integration test suite before every commit

Wszystkich czterech wymagań naraz agent nie spełni. Gdy instrukcje są ze sobą sprzeczne i brakuje jawnej kolejności priorytetów, model pomija kroki weryfikacji i rzuca się na generowanie kodu. Badanie zaprezentowane na ICLR 2026 (Ambig-SWE) wykazało, że „bez wyraźnego zachęcenia modele niemal nigdy nie wchodzą w interakcję, nawet przy skrajnie niedookreślonych danych wejściowych” – agenci działają dalej w milczeniu, zamiast zadać pytanie doprecyzowujące – natomiast zachęcenie ich do interakcji poprawia wyniki nawet o 74% przy zadaniach niedookreślonych ¹². Sprzeczne instrukcje naprawia się przez ponumerowanie priorytetów: „Priorytet 1: testy przechodzą. Priorytet 2: poniżej 5 minut. Priorytet 3: szybkie wydanie”.

Przewodniki stylu bez egzekwowania

<!-- BAD: No way to verify compliance -->
Follow the Google Python Style Guide for all code.
Use numpy-style docstrings for public functions.

Dopóki nie zostanie podane dokładne polecenie lintera, które egzekwuje dany styl (ruff check --select D albo pylint --rcfile=.pylintrc), agent nie ma mechanizmu pozwalającego zweryfikować własną zgodność. Wzorzec jest tu uniwersalny: instrukcje bez poleceń weryfikujących są sugestiami, a nie regułami.

Co działa

Te wzorce dają spójne, mierzalne zmiany w zachowaniu agenta.

Instrukcje oparte na poleceniach

## Build and Test Commands
- Install: `pip install -r requirements.txt`
- Lint: `ruff check . --fix`
- Format: `ruff format .`
- Test: `pytest -v --tb=short`
- Type check: `mypy app/ --strict`
- Full verify: `ruff check . && ruff format --check . && pytest -v`

Polecenia są jednoznaczne. Agent wie dokładnie, co uruchomić i jakie argumenty przekazać, a powodzenie może sprawdzić po kodzie wyjścia. Każda instrukcja w pliku AGENTS.md powinna odpowiadać na pytanie: „Jakie polecenie dowodzi, że zostało to zrobione poprawnie?”.

Definicje zamknięcia

## Definition of Done
A task is complete when ALL of the following pass:
1. `ruff check .` exits 0
2. `pytest -v` exits 0 with no failures
3. `mypy app/ --strict` exits 0
4. Changed files have been staged and committed
5. Commit message follows conventional format: `type(scope): description`

Jawne definicje zamknięcia eliminują najczęstszy tryb awarii: agent melduje „gotowe” bez weryfikacji. Kiedy „gotowe” jest zdefiniowane jako konkretne kody wyjścia, agent uruchamia każdą kontrolę, zanim zgłosi ukończenie. Bez takiej definicji „gotowe” znaczy „wydaje mi się, że skończyłem”, co bywa częstym źródłem błędów wprowadzanych przez agentów.

Sekcje uporządkowane według zadań

## When Writing Code
- Run `ruff check .` after every file change
- Add type hints to all new functions
- Test command: `pytest tests/ -v -k "test_<module>"`

## When Reviewing Code
- Check for security issues: `bandit -r app/`
- Verify test coverage: `pytest --cov=app --cov-fail-under=80`
- List changed files: `git diff --name-only HEAD~1`

## When Releasing
- Update version in `pyproject.toml`
- Run full suite: `pytest -v && ruff check . && mypy app/`
- Tag: `git tag -a v<version> -m "Release v<version>"`

Pliki uporządkowane według zadań pozwalają agentowi wybrać istotne instrukcje na podstawie tego, co właśnie robi. Płaskie listy zmuszają go do przetwarzania każdej instrukcji niezależnie od kontekstu. Przedrostek „Kiedy…” odwzorowuje wprost sposób, w jaki agent rozumuje o kontekście zadania.

Reguły eskalacji

## When Blocked
- If tests fail after 3 attempts: stop and report the failing test with full output
- If a dependency is missing: check `requirements.txt` first, then ask
- If you encounter merge conflicts: stop and show the conflicting files
- Never: delete files to resolve errors, force push, or skip tests

Bez reguł eskalacji zablokowani agenci sięgają po coraz bardziej twórcze obejścia: usuwają pliki blokad, omijają kontrole albo po cichu ignorują niepowodzenia. Lista „nigdy” jest równie ważna jak ścieżki eskalacji. Jawny zakaz destrukcyjnych sposobów ratowania sytuacji zapobiega najgorszym trybom awarii.

Zakres katalogowy w monorepozytoriach

AGENTS.md obsługuje zakres hierarchiczny jako podstawową funkcję specyfikacji ². Pliki położone bliżej katalogu roboczego mają pierwszeństwo:

/repo/AGENTS.md                        ← Project-wide rules
  └─ /repo/services/AGENTS.md          ← Service defaults
      ├─ /repo/services/api/AGENTS.md  ← API-specific rules
      └─ /repo/services/web/AGENTS.md  ← Frontend-specific rules

Instrukcje z poziomu głównego są łączone z plikami leżącymi głębiej. Codex przechodzi od katalogu głównego projektu do bieżącego katalogu roboczego i łączy każdy plik AGENTS.md napotkany po drodze ⁴; sama specyfikacja definiuje pierwszeństwo pliku najbliższego, inne narzędzia mogą więc rozwiązywać hierarchię inaczej ². Własne repozytorium codex firmy OpenAI stosuje to w praktyce: dostarcza zagnieżdżony plik AGENTS.md poniżej tego z katalogu głównego ⁴.

W Codeksie można dodatkowo użyć pliku AGENTS.override.md na dowolnym poziomie, aby zastąpić (a nie rozszerzyć) instrukcje nadrzędne ⁴. Mechanizm nadpisywania jest właściwy dla Codeksa, inne narzędzia go nie implementują.

<!-- /repo/services/payments/AGENTS.override.md (Codex only) -->
# Payment Service Rules (OVERRIDE)

This service has additional security requirements.
All changes require: `bandit -r . -ll` passing with zero findings.
No dependency updates without explicit approval.
Test with: `pytest -v --tb=long -x` (fail fast, full tracebacks)

Kiedy stosować nadpisanie: przy zamrożeniu wydań, w trybie awaryjnym albo w każdej usłudze o wymaganiach bezpieczeństwa przeważających nad ustawieniami całego projektu.

Zgodność między narzędziami

AGENTS.md został przyjęty przez ponad 60 000 projektów ¹ i jest rozpoznawany przez każde poważne narzędzie do programowania z AI. Oto jak ten sam plik zachowuje się w różnych ekosystemach (tabela zweryfikowana w sierpniu 2026 roku):

Jeżeli zespół korzysta z wielu narzędzi: plik AGENTS.md należy pisać jako źródło kanoniczne. Warto dodać pliki właściwe dla poszczególnych narzędzi (CLAUDE.md, .cursorrules), które importują lub odzwierciedlają odpowiednie sekcje. Nie należy utrzymywać równoległych zestawów instrukcji, które z czasem się rozjadą.

Kolejność pisania: od czego zacząć

Przy pisaniu pliku AGENTS.md od zera sekcje warto dodawać w tej kolejności priorytetów. Każda warstwa opiera się na poprzedniej:

1. Polecenia budowania i testowania – agent potrzebuje ich, zanim zrobi cokolwiek użytecznego
2. Definicja gotowości – zapobiega fałszywym zgłoszeniom w stylu „wydaje mi się, że skończyłem”
3. Reguły eskalacji – zapobiegają destrukcyjnym obejściom, gdy agent utknie
4. Sekcje uporządkowane według zadań – ograniczają przetwarzanie nieistotnych instrukcji przy każdym zadaniu
5. Zakres katalogowy (tylko monorepozytoria) – utrzymuje izolację instrukcji poszczególnych usług

Preferencje stylistyczne warto odłożyć do czasu, aż pierwsze cztery punkty zaczną działać. Większość plików AGENTS.md zawodzi, ponieważ zaczyna od wskazówek stylistycznych i nigdy nie dociera do poleceń.

Testowanie pliku AGENTS.md

Warto sprawdzić, czy agent faktycznie czyta i wykonuje zapisane instrukcje:

# Codex: Show the full instruction chain
codex --ask-for-approval never "Summarize your current instructions"

# Codex: Generate a scaffold (slash command inside an active session)
# Type /init at the Codex prompt, not as a shell command
codex  # then type: /init

# Claude Code: Check active instructions
claude --print "What instructions are you following for this project?"

# Verify specific rules are active
codex --ask-for-approval never "What is your definition of done?"

Próba ostateczna: należy poprosić agenta o wyjaśnienie poleceń budowania. Jeżeli nie potrafi odtworzyć ich dosłownie, instrukcje albo nie są czytane, albo są zbyt rozwlekłe, by utrzymać je w kontekście. Długie pliki AGENTS.md są obcinane przez okno kontekstu – każdą sekcję warto utrzymać poniżej 50 linii, a najważniejsze instrukcje umieścić na początku.

Często zadawane pytania

Jak długi powinien być plik AGENTS.md?

Moja reguła kciuka: każda sekcja poniżej 50 linii, a cały plik poniżej 150. Zasada, która za tym stoi, pochodzi ze wskazówek Marmelab dotyczących agent experience – plik powinien pozostać „krótki i na temat”, ponieważ agenci czytają go na początku każdej sesji ¹³; konkretne liczby linii są moje, a nie ich. Codex egzekwuje domyślny limit 32 KiB (project_doc_max_bytes) ⁴. Długie pliki są obcinane przez okno kontekstu, dlatego najważniejsze instrukcje, polecenia i definicje zamknięcia należy umieścić przed preferencjami stylistycznymi.

Czy AGENTS.md zastępuje pliki instrukcji właściwe dla narzędzi?

Nie. AGENTS.md współistnieje z CLAUDE.md, .cursor/rules i innymi plikami właściwymi dla konkretnych narzędzi. Plik AGENTS.md należy pisać jako źródło kanoniczne, a następnie odzwierciedlać odpowiednie sekcje w plikach poszczególnych narzędzi. Wzorce z pliku AGENTS.md (oparte na poleceniach, z definicją zamknięcia) działają w każdym pliku instrukcji, niezależnie od narzędzia.

Co zrobić, gdy agent ignoruje plik AGENTS.md?

Test polega na poproszeniu agenta o wyjaśnienie poleceń budowania. Jeżeli nie potrafi odtworzyć ich dosłownie, plik jest albo zbyt rozwlekły (treść wypadła poza kontekst), albo zbyt ogólnikowy (agent nie wyciąga z niego wykonalnych instrukcji), albo w ogóle nie zostaje wykryty (warto sprawdzić lokalizację pliku i dokumentację narzędzia). Analiza ponad 2500 repozytoriów przeprowadzona przez GitHub wykazała, że większość plików dla agentów zawodzi, ponieważ są zbyt ogólnikowe ¹¹.

Najważniejsze wnioski

Dla pojedynczych programistów:

• Prozę warto zastąpić poleceniami. Każda instrukcja powinna być weryfikowalna przez uruchomienie czegoś.
• Zamknięcie należy zdefiniować jawnie. „Gotowe” oznacza konkretne kody wyjścia, a nie odczucia.
• Plik AGENTS.md warto przetestować, prosząc agenta o jego wyrecytowanie. Czego nie potrafi wyrecytować, tego nie wykona.

Dla zespołów:

• AGENTS.md warto traktować jako jedyne źródło prawdy. Zamiast utrzymywać równoległe kopie, lepiej odzwierciedlać go w plikach poszczególnych narzędzi.
• Porządek należy budować według zadań (kodowanie, przegląd, wydanie), a nie według kategorii (styl, testy, wdrożenie).
• Warto dodać reguły eskalacji. Bez nich zablokowany agent improwizuje w sposób, który się nie spodoba.
• W monorepozytoriach zakres warto ograniczać katalogami. Reguły pojedynczej usługi nie powinny zanieczyszczać instrukcji globalnych.

Źródła