Przejdź do głównej treści
Polski— Wybierz język
Menu

AGENTS.md: Konfiguruj instrukcje repozytorium

Lekcja 15 z 20 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Opanowanie pliku konfiguracyjnego Codex
  2. Hierarchia AGENTS.md
  3. Sekcje, które tworzą plik
  4. Dwa wzorce, które zapobiegają niespodziankom
  5. Utrzymywanie pliku przy życiu
  6. Kluczowe wnioski

Lekcja zaktualizowana 3 listopada 2026 na podstawie strony Custom instructions with AGENTS.md: Codex odczytuje wyłącznie pliki AGENTS.md znajdują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.md pozwala 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.md jako żywy kod