AGENTS.md: Konfiguruj instrukcje repozytorium
Na tej stronie
Lekcja zaktualizowana 3 listopada 2026 na podstawie strony Custom instructions with AGENTS.md: Codex odczytuje wyłącznie pliki
AGENTS.mdznajdujące się między katalogiem głównym projektu a bieżącym katalogiem roboczym (oraz plik globalny w~/.codex). Plik w podkatalogu poza tą ścieżką nie zostanie wczytany, wbrew temu, co sugerowała poprzednia wersja. Źródło: AGENTS.md.
Opanowanie pliku konfiguracyjnego Codex
Poznałeś AGENTS.md w Lekcji 3. Tutaj zagłębiamy się w zaawansowane wzorce – różnicę między plikiem dekoracyjnym (trzy linijki napisane na start i zapomniane) a takim, który faktycznie steruje zachowaniem agenta w żywym projekcie.
Hierarchia AGENTS.md
Codex odczytuje te pliki hierarchicznie, od ogółu do szczegółu: najpierw plik globalny w folderze Codex (~/.codex/AGENTS.md lub AGENTS.override.md, jeśli istnieje), a następnie, począwszy od katalogu głównego projektu, pliki w katalogach przechodzonych w dół do bieżącego katalogu roboczego. W dobrze zorganizowanym projekcie drzewo wygląda tak:
mon-projet/
AGENTS.md → Zasady globalne (niski priorytet)
src/
AGENTS.md → Zasady dla całego kodu źródłowego
api/
AGENTS.md → Zasady specyficzne dla API
routes/
AGENTS.md → Zasady dla tras (routes)
components/
AGENTS.md → Zasady dla komponentów React
tests/
AGENTS.md → Zasady dla testów
Zasady sumują się: Codex łączy pliki od katalogu głównego w dół do bieżącego katalogu, przy czym te najbliższe temu katalogowi, czytane jako ostatnie, nadpisują ogólne instrukcje. Jeden punkt bywa często źle rozumiany: odczytywane są tylko katalogi leżące na ścieżce między katalogiem głównym a bieżącym katalogiem. Jeśli Twój plik główny zabrania używania any, a tests/AGENTS.md pozwala na luźniejsze asercje w mockach, ta tolerancja obowiązuje tylko wtedy, gdy Codex pracuje z tests/ lub jednego z jego podkatalogów; uruchomiony z katalogu głównego, nie odczyta tests/AGENTS.md. Przegląd kodu GitHub działa inaczej: Codex przeszukuje całe repozytorium w poszukiwaniu plików AGENTS.md i stosuje reguły przeglądu (## Code Review Rules) z pliku najbliższego danemu kodowi. Konkatenacja domyślnie zatrzymuje się na 32 KiB (project_doc_max_bytes): zbyt długi plik zostanie obcięty.
Sekcje, które tworzą plik
Kontekst jest najważniejszy, ponieważ kształtuje każdą późniejszą decyzję. Aplikacja SaaS podlegająca RODO (Ogólne Rozporządzenie o Ochronie Danych) nie jest kodowana tak samo jak narzędzie wewnętrzne dla pięciu osób:
## Context
SaaS invoice management application for French SMEs.
GDPR compliance mandatory. Data hosted in France (OVH).
Stack: Astro 6, React, Strict TypeScript, Prisma, PostgreSQL.
Authentication: Better Auth with server sessions.
Wiedząc, że aplikacja przetwarza dane podlegające RODO, Codex doda oczekiwane zabezpieczenia bez konieczności określania ich w każdym żądaniu. Następnie pojawiają się konwencje, które odpowiadają na jedno pytanie: jak tutaj wygląda poprawny kod?
## Conventions
- Strict TypeScript (no any, no implicit any)
- Functional React components only
- Naming: kebab-case files, PascalCase components,
camelCase variables
- Imports: @/ for path aliases
- Validation: Zod for all user inputs
- Errors: custom error classes in src/lib/errors.ts
- Logging: use src/lib/logger.ts (no console.log)
Sekcja poleceń jest najczęściej pomijana, a jej brak słono kosztuje: bez tych poleceń Codex nie może zweryfikować swojej pracy i zwraca kod, którego nigdy nie uruchomił ani nie przetestował.
## Commands
- `npm run dev` — Development server (port 4321)
- `npm run build` — Production build
- `npm run test` — Vitest tests
- `npm run test:e2e` — Playwright tests
- `npm run lint` — ESLint + Prettier
- `npm run db:migrate` — Prisma migrations
- `npm run db:seed` — Database seed
Ścisłe reguły tworzą barierę ochronną. Sformułowane jako „NIGDY“ i „ZAWSZE“, zapobiegają błędom, których naprawa kosztuje cały wieczór: usunięta migracja Prisma, którą trzeba będzie odtworzyć z produkcji, ujawniony sekret wymagający unieważnienia lub innerHTML wkomponowany w element, otwierający lukę XSS.
## Strict Rules (NEVER break these)
- NEVER modify the Prisma schema without creating a migration
- NEVER store secrets in code (use .env)
- NEVER use innerHTML (XSS risk)
- NEVER delete an existing Prisma migration
- NEVER expose internal IDs in public URLs
- ALWAYS validate user inputs with Zod
- ALWAYS use Prisma transactions for multi-table operations
Na koniec architektura opisuje dozwolony przepływ między warstwami. Bez niej Codex produkuje kod, który działa, ale omija Twoją strukturę – na przykład trasę odpytującą Prisma bezpośrednio, ponieważ była to najkrótsza droga.
## Architecture
Layers:
1. Routes (src/pages/) → receive requests
2. Services (src/services/) → business logic
3. Repositories (src/repositories/) → data access
Rule: Routes MUST NOT access Prisma directly.
Everything goes through a service, which goes through a repository.
Do tego, projekt po projekcie, dochodzą instrukcje specyficzne dla każdej używanej technologii:
## React
- Prefer Server Components by default
- Client Components only when necessary (interactivity)
- No useEffect for data fetching (use Server Actions)
- Local state with useState, global state with Zustand
## Prisma
- Relations: always include required fields explicitly
- Pagination: use cursor-based, not offset-based
- Soft delete: use deletedAt instead of DELETE
Dwa wzorce, które zapobiegają niespodziankom
Deklarowanie oczekiwanych zmiennych środowiskowych zapobiega sytuacjom, w których Codex wymyśla nazwy kluczy podczas pisania skryptu lub przypadkowo loguje wrażliwą wartość w śladzie debugowania:
## Required Environment Variables
- DATABASE_URL — PostgreSQL connection URL
- AUTH_SECRET — Secret for Better Auth (min 32 chars)
- SMTP_HOST — SMTP server for emails
- STRIPE_SECRET_KEY — Stripe API key (never log)
Wymienienie preferowanych bibliotek, a zwłaszcza tych, których odmawiasz, rozwiązuje powtarzający się problem: agent instaluje zależność, która sama w sobie jest całkowicie poprawna, ale Twój zespół odrzucił ją dwa lata temu po złym doświadczeniu.
## Dependencies
If you need:
- Validation → Zod (NOT Joi, NOT Yup)
- Dates → date-fns (NOT moment, NOT dayjs)
- HTTP client → ofetch (NOT axios)
- Tests → Vitest (NOT Jest)
- E2E → Playwright (NOT Cypress)
Utrzymywanie pliku przy życiu
AGENTS.md ewoluuje razem z Twoim kodem, tak jak test czy README. Aktualizuj go natychmiast po przyjęciu nowej konwencji, zmianie bibliotek lub frameworków, a zwłaszcza gdy tylko zidentyfikujesz powtarzający się błąd Codexa: ten ostatni przypadek zawsze sygnalizuje brakującą instrukcję, a nie awarię modelu. Warto też wypatrywać czwartego, bardziej subtelnego wyzwalacza – gdy nowy programista zadaje pytanie, na które AGENTS.md powinien był odpowiedzieć, ta odpowiedź należy do pliku.
Kluczowe wnioski
- Hierarchia
AGENTS.mdpozwala na stosowanie coraz bardziej szczegółowych instrukcji - Polecenia są kluczowe, aby Codex mógł zweryfikować swoją pracę
- Zasady NIGDY są najważniejsze dla unikania błędów
- Udokumentuj preferowane zależności, aby zapobiec złym wyborom
- Traktuj
AGENTS.mdjako żywy kod