AGENTS.md w Codex: Jak nauczyć AI standardów twojego kodu

Każdy zespół ma swoje zasady. Testy przed commitem. Określony styl nazewnictwa. Zakaz używania pewnych bibliotek. Problem w tym, że AI o nich nie wie — chyba że mu powiesz. AGENTS.md to sposób na nauczenie Codex zasad twojego projektu.

1. Czym jest AGENTS.md?
2. Hierarchia plików: od globalnych do lokalnych
3. Working agreements: testy, linting, konwencje
4. Review guidelines: co Codex ma sprawdzać
5. Override: tymczasowe nadpisanie reguł
6. Praktyczne wskazówki

Czym jest AGENTS.md?

AGENTS.md to plik Markdown, który Codex czyta przed każdą operacją. Zawiera instrukcje, które Codex traktuje jako obowiązujące reguły projektu — podobnie jak README, ale dla AI.

Gdy uruchamiasz Codex w dowolnym repozytorium, przeszukuje ono hierarchię katalogów w poszukiwaniu plików AGENTS.md i składa je w jeden zestaw instrukcji. To oznacza, że możesz mieć globalne reguły dla wszystkich projektów i specyficzne reguły dla konkretnych folderów.

Hierarchia plików: od globalnych do lokalnych

Codex buduje łańcuch instrukcji z wielu źródeł. Kolejność ma znaczenie — pliki bliżej bieżącego katalogu nadpisują wcześniejsze.

Przykład struktury:

~/.codex/
  AGENTS.md              # Globalne preferencje

/my-project/
  AGENTS.md              # Reguły repozytorium
  services/
    payments/
      AGENTS.md          # Reguły dla płatności
      AGENTS.override.md # Tymczasowe nadpisanie

Gdy pracujesz w /my-project/services/payments, Codex załaduje wszystkie trzy pliki AGENTS.md i połączy je w jeden zestaw instrukcji.

Working agreements: testy, linting, konwencje

Najczęstsze zastosowanie AGENTS.md to definiowanie working agreements — zasad pracy obowiązujących w projekcie.

Przykład globalnego pliku ~/.codex/AGENTS.md:

# Working agreements

- Zawsze uruchamiaj npm test po modyfikacji plików JavaScript
- Preferuj pnpm przy instalacji zależności
- Pytaj o potwierdzenie przed dodaniem nowej produkcyjnej zależności
- Nie commituj bezpośrednio do main — twórz feature branches

Przykład pliku repo /project/AGENTS.md:

# Repository expectations

- Uruchom npm run lint przed otwarciem pull request
- Dokumentuj publiczne API w docs/ gdy zmieniasz zachowanie
- Testy jednostkowe dla każdej nowej funkcji publicznej
- Format commitów: type(scope): description

Codex będzie stosował te reguły automatycznie. Gdy poproszisz o implementację funkcji, sam uruchomi testy. Gdy przygotuje PR, sprawdzi lint.

Review guidelines: co Codex ma sprawdzać

Sekcja Review guidelines określa, na co Codex powinien zwracać uwagę podczas automatycznego code review. To kluczowe dla integracji z GitHubem.

## Review guidelines

- Nie loguj danych osobowych (PII) w żadnym miejscu
- Sprawdź czy middleware autoryzacji opakowuje każdy endpoint
- Każdy nowy endpoint musi mieć rate limiting
- Traktuj literówki w dokumentacji jako P1
- Sprawdź czy error handling pokrywa wszystkie przypadki

Codex stosuje guidance z najbliższego AGENTS.md do każdego zmienionego pliku. Możesz umieszczać coraz bardziej szczegółowe instrukcje głębiej w drzewie katalogów.

Override: tymczasowe nadpisanie reguł

Czasami potrzebujesz tymczasowo zmienić zachowanie Codex bez edytowania głównego pliku. Do tego służy AGENTS.override.md.

Gdy Codex znajdzie AGENTS.override.md w danym katalogu, używa go zamiast AGENTS.md na tym poziomie. To przydatne gdy:

• Testujesz nowe reguły przed wdrożeniem do zespołu
• Potrzebujesz tymczasowego wyjątku dla konkretnej pracy
• Masz osobiste preferencje różne od zespołowych

Typowy workflow:

1. Stwórz ~/.codex/AGENTS.override.md z eksperymentalnymi regułami
2. Przetestuj przez kilka dni
3. Gdy działają, przenieś do AGENTS.md
4. Usuń override

Praktyczne wskazówki

Trzymaj AGENTS.md krótkim. Domyślny limit to 32 KB dla wszystkich połączonych plików. Gdy przekroczysz limit, Codex obetnie instrukcje. Pisz zwięźle.

Używaj fallback filenames dla istniejących projektów. Jeśli zespół już używa pliku TEAM_GUIDE.md, dodaj go do konfiguracji:

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

Testuj ładowanie instrukcji. Uruchom:

codex --ask-for-approval never "Podsumuj aktywne instrukcje."

Codex wylistuje wszystkie załadowane pliki instrukcji w kolejności priorytetów.

Debuguj problemy. Jeśli Codex ignoruje instrukcje:

• Sprawdź czy plik nie jest pusty (Codex pomija puste pliki)
• Szukaj AGENTS.override.md wyżej w hierarchii
• Zweryfikuj że jesteś w oczekiwanym workspace: codex status

Pełny opis konfiguracji Codex znajdziesz w wprowadzeniu do OpenAI Codex. Jeśli interesuje cię bezpieczeństwo, sprawdź sandbox i polityki w Codex.