Wzorce AGENTS.md: co naprawdę zmienia zachowanie agenta

Mój pierwszy plik AGENTS.md był 200-liniowym wklejeniem przewodnika stylistycznego naszego zespołu. Zawierał konwencje nazewnictwa, listy kontrolne przeglądów kodu, procedury wdrożeniowe i zasady architektoniczne. Agent zignorował większość z tego. Nie dlatego, że instrukcje były błędne — dlatego, że były dokumentacją, a nie instrukcjami operacyjnymi.

To rozróżnienie ma większe znaczenie niż jakikolwiek konkretny wzorzec opisany w tym artykule. AGENTS.md to polityka operacyjna dla agenta AI, a nie README dla ludzi. Agent nie musi rozumieć, dlaczego stosowane są konwencjonalne commity. Musi znać dokładne polecenie do uruchomienia i wiedzieć, jak wygląda stan „gotowe”.

TL;DR

Większość problemów z AGENTS.md wynika z pisania dokumentacji dla ludzi zamiast instrukcji operacyjnych dla agentów. Skuteczne pliki są zorientowane na polecenia (dokładne wywołania, nie opisy), zorganizowane według zadań (sekcje: kodowanie, przegląd, wydanie) i mają zdefiniowane kryteria zakończenia (jawne warunki „gotowe”). Antywzorce, które niezawodnie są ignorowane: akapity prozy, niejasne dyrektywy („bądź ostrożny”) i sprzeczne priorytety. AGENTS.md to otwarty standard przyjęty przez ponad 60 000 projektów ¹, działający w Codex, Cursor, Copilot, Amp, Windsurf i innych narzędziach ².

Kontekst: AGENTS.md jest zarządzany przez Agentic AI Foundation w ramach Linux Foundation ³, z platynowymi członkami takimi jak Anthropic, Google, Microsoft i OpenAI. Ten artykuł omawia praktyczne wzorce. Konfigurację specyficzną dla Codex można znaleźć w przewodniku Codex. Odpowiednik dla Claude Code (CLAUDE.md) opisano w przewodniku Claude Code.

Co jest ignorowane

Poniższe wzorce niezawodnie nie powodują żadnej obserwowalnej zmiany w zachowaniu agenta. Zidentyfikowałem każdy z nich, uruchamiając identyczne zadania z instrukcją i bez niej, a następnie porównując dokładność realizacji zadań w ponad 10 uruchomieniach na wzorzec. Analiza GitHub obejmująca ponad 2500 repozytoriów z plikami AGENTS.md doszła do tego samego wniosku: „Większość plików agentów zawodzi, ponieważ są zbyt ogólnikowe — nie z powodu ograniczeń technicznych” ¹¹. Poniższe wzorce nie poprawiły dokładności w żaden mierzalny sposób.

Akapity prozy 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 czyta to, reprezentuje jako ogólnikową preferencję i przystępuje do pisania kodu bez testów. Nie ma instrukcji do wykonania — żadnego polecenia do uruchomienia, żadnego progu do spełnienia, żadnej definicji „odpowiednio przetestowane”.

Niejasne dyrektywy

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

„Ostrożnie” to nie ograniczenie. „Gdzie to możliwe” to nie warunek wyzwalający. „Elegancko” to nie specyfikacja zachowania. Brzmią jak wskazówki między ludźmi, nie instrukcje dla agenta. Dla porównania, oto co działa: „Uruchom alembic check przed zastosowaniem migracji. Przerwij, jeśli brakuje ścieżki cofania.”

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

Agent nie jest w stanie spełnić wszystkich czterech warunków jednocześnie. Gdy instrukcje są sprzeczne i nie mają jawnej kolejności priorytetów, model pomija kroki weryfikacji i przechodzi bezpośrednio do generowania kodu. Badania z ICLR 2026 (AMBIG-SWE) wykazały, że agenty „domyślnie wybierają zachowanie nieinteraktywne bez wyraźnej zachęty” — kontynuują w ciszy zamiast zadawać pytania wyjaśniające, co obniżyło wskaźnik rozwiązywalności z 48,8% do 28% ¹². Sprzeczne instrukcje można naprawić, numerując priorytety: „Priorytet 1: Testy przechodzą. Priorytet 2: Poniżej 5 minut. Priorytet 3: Szybkie dostarczanie.”

Przewodniki stylistyczne 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 lintujące wymuszające styl (ruff check --select D lub pylint --rcfile=.pylintrc), agent nie ma mechanizmu weryfikacji własnej zgodności. Wzorzec jest uniwersalny: instrukcje bez poleceń weryfikujących to sugestie, nie reguły.

Co działa

Poniższe wzorce powodują spójne, mierzalne zmiany w zachowaniu agenta.

Instrukcje zorientowane na polecenia

## 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ć, jakie argumenty przekazać, i może zweryfikować sukces sprawdzając kod wyjścia. Każda instrukcja w pliku AGENTS.md powinna odpowiadać na pytanie: „Jakie polecenie dowodzi, że to zostało wykonane poprawnie?”

Definicje zakończenia

## 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 zakończenia eliminują najczęstszy tryb awarii: agent raportuje „gotowe” bez weryfikacji. Gdy „gotowe” jest zdefiniowane jako konkretne kody wyjścia, agent uruchamia każde sprawdzenie przed zgłoszeniem ukończenia. Bez tej definicji „gotowe” oznacza „wydaje mi się, że skończyłem” — częste źródło błędów wprowadzanych przez agenta.

Sekcje zorganizowane 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 zorganizowane według zadań pozwalają agentowi wybierać istotne instrukcje w zależności od aktualnie wykonywanej czynności. Płaskie listy zmuszają agenta do parsowania każdej instrukcji niezależnie od kontekstu. Prefiks „When…” mapuje się bezpośrednio na 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 agenty domyślnie uciekają się do coraz bardziej kreatywnych obejść, gdy zostaną zablokowane — usuwanie plików blokady, pomijanie sprawdzeń lub ciche ignorowanie błędów. Lista „Never” jest równie ważna jak ścieżki eskalacji. Jawne zakazanie destrukcyjnych wzorców naprawczych zapobiega najgorszym trybom awarii.

Zakres katalogowy dla monorepo

AGENTS.md wspiera hierarchiczny zakres jako podstawową funkcję specyfikacji ². Pliki bliżej katalogu roboczego mają wyższy priorytet:

/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 głębszymi plikami. Narzędzia przechodzą od korzenia projektu do bieżącego katalogu roboczego, łącząc każdy plik AGENTS.md napotkany po drodze ⁴. Własne repozytorium Codex firmy OpenAI używa 88 oddzielnych plików AGENTS.md w swoim monorepo — po jednym na usługę i pakiet ⁴.

W Codex można również użyć AGENTS.override.md na dowolnym poziomie, aby zastąpić (a nie rozszerzyć) instrukcje nadrzędne ⁴. Mechanizm nadpisywania jest specyficzny dla Codex — 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 używać nadpisywania: zamrożenia wydań, tryb incydentu lub dowolna usługa z wymaganiami bezpieczeństwa, które zastępują domyślne ustawienia projektu.

Kompatybilność między narzędziami

AGENTS.md jest przyjęty przez ponad 60 000 projektów ¹ i rozpoznawany przez każde główne narzędzie do kodowania z AI. Oto jak ten sam plik zachowuje się w różnych ekosystemach:

Jeśli zespół używa wielu narzędzi: AGENTS.md powinien być kanonicznym źródłem. Pliki specyficzne dla narzędzi (CLAUDE.md, .cursorrules) powinny importować lub odzwierciedlać odpowiednie sekcje. Nie należy utrzymywać równoległych zestawów instrukcji, które z czasem się rozjeżdżają.

Kolejność pisania: co dodać najpierw

Pisząc AGENTS.md od zera, sekcje należy dodawać w następującej kolejności priorytetów. Każda warstwa buduje na poprzedniej:

1. Polecenia budowania i testowania — agent potrzebuje ich, zanim będzie mógł zrobić cokolwiek użytecznego
2. Definicja zakończenia — zapobiega fałszywym ukończeniom typu „wydaje mi się, że skończyłem”
3. Reguły eskalacji — zapobiega destrukcyjnym obejściom, gdy agent utknie
4. Sekcje zorganizowane według zadań — redukuje parsowanie nieistotnych instrukcji dla danego zadania
5. Zakres katalogowy (tylko monorepo) — izoluje instrukcje poszczególnych usług

Preferencje stylistyczne należy pominąć, dopóki pierwsze cztery punkty nie działają. Większość plików AGENTS.md zawodzi, ponieważ zaczyna się od wskazówek stylistycznych i nigdy nie dochodzi do poleceń.

Testowanie pliku AGENTS.md

Weryfikacja, czy agent faktycznie czyta i stosuje się do instrukcji:

# 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?"

Test decydujący: Należy poprosić agenta o wyjaśnienie poleceń budowania. Jeśli nie potrafi ich odtworzyć dosłownie, instrukcje nie są odczytywane lub są zbyt rozwlekłe, by zmieścić się w oknie kontekstu. Długie pliki AGENTS.md są obcinane przez okna kontekstu — każda sekcja powinna mieć mniej niż 50 linii, a najważniejsze instrukcje powinny znajdować się na początku.

FAQ

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

Każda sekcja powinna mieć mniej niż 50 linii, a cały plik nie powinien przekraczać 150 linii ¹³. Codex narzuca domyślny limit 32 KiB (project_doc_max_bytes) ⁴. Długie pliki są obcinane przez okna kontekstu, dlatego najważniejsze instrukcje — polecenia i definicje zakończenia — powinny znajdować się na początku, przed preferencjami stylistycznymi.

Czy AGENTS.md zastępuje pliki instrukcji specyficzne dla narzędzi?

Nie. AGENTS.md działa równolegle z CLAUDE.md, .cursor/rules i innymi plikami specyficznymi dla narzędzi. AGENTS.md powinien być kanonicznym źródłem, a odpowiednie sekcje należy odzwierciedlać w plikach specyficznych dla narzędzi. Wzorce z AGENTS.md (zorientowane na polecenia, z zdefiniowanymi kryteriami zakończenia) działają w każdym pliku instrukcji niezależnie od narzędzia.

Co zrobić, gdy agent ignoruje AGENTS.md?

Należy przetestować, prosząc agenta o wyjaśnienie poleceń budowania. Jeśli nie potrafi ich odtworzyć dosłownie, plik jest albo zbyt rozwlekły (treść wypychana poza okno kontekstu), zbyt ogólnikowy (agent nie może wyodrębnić instrukcji do wykonania) lub nie jest wykrywany (należy sprawdzić lokalizację pliku i dokumentację narzędzia). Analiza GitHub obejmująca 2500 repozytoriów wykazała, że to ogólnikowość — nie ograniczenia techniczne — powoduje większość niepowodzeń ¹¹.

Kluczowe wnioski

Dla indywidualnych programistów:

• Prozę należy zastąpić poleceniami. Każda instrukcja powinna być weryfikowalna przez uruchomienie czegoś.
• Zakończenie należy zdefiniować jawnie. „Gotowe” oznacza konkretne kody wyjścia, nie wrażenia.
• AGENTS.md należy testować, prosząc agenta o jego odtworzenie. Czego agent nie potrafi odtworzyć, tego nie będzie przestrzegać.

Dla zespołów:

• AGENTS.md powinien być jedynym źródłem prawdy. Należy odzwierciedlać go w plikach specyficznych dla narzędzi, a nie utrzymywać równoległych kopii.
• Organizacja powinna być według zadań (kodowanie, przegląd, wydanie), a nie według kategorii (styl, testowanie, wdrożenie).
• Reguły eskalacji są niezbędne. Bez nich zablokowane agenty improwizują w sposób, który nie spodoba się nikomu.
• Zakres należy definiować per katalog w monorepo. Reguły specyficzne dla usługi nie powinny zanieczyszczać globalnych instrukcji.

Źródła