Konfiguracja AGENTS.md
Poprosiles Codex o dodanie funkcji, a on uzyl Express gdy twoj projekt dziala na Fastify. Kazales mu uruchomic testy, a on sprobowal npm test gdy twoj projekt uzywa pnpm vitest. Codex jest potezny, ale bez kontekstu o twoim konkretnym projekcie wraca do generycznych zalozen, ktore marnuja twoj czas na cofanie zlych wyborow.
AGENTS.md rozwiazuje ten problem. To plik markdown ktory Codex czyta przed rozpoczeciem jakiejkolwiek pracy — instrukcja obslugi twojego projektu dla agenta AI. Pomysl o nim jak o wdrazaniu nowego dewelopera: oto jak strukturyzujemy kod, oto jak testujemy, oto czego nigdy nie dotykac.
Co wyniesiesz z tego przewodnika
Dział zatytułowany „Co wyniesiesz z tego przewodnika”- Globalny
~/.codex/AGENTS.mdz twoimi osobistymi umowami roboczymi - Projektowy
AGENTS.mdz konwencjami specyficznymi dla repozytorium - Zagniezdzone nadpisania dla konkretnych katalogow (wsparcie monorepo)
- Codex poprawnie przestrzegajacy twoich konwencji od pierwszego razu
- Wytyczne przegladu ktore Codex stosuje przy przegladaniu PR-ow na GitHub
Jak dziala odkrywanie
Dział zatytułowany „Jak dziala odkrywanie”Codex buduje lancuch instrukcji przy starcie, przechodzac po systemie plikow w okreslonej kolejnosci:
-
Zakres globalny: Codex czyta
~/.codex/AGENTS.override.mdjesli istnieje. W przeciwnym razie czyta~/.codex/AGENTS.md. Tylko jeden plik jest uzywany na tym poziomie. -
Zakres projektu: Poczawszy od katalogu glownego projektu (zwykle katalogu glownego Git), Codex przechodzi w dol do biezacego katalogu roboczego. W kazdym katalogu sprawdza
AGENTS.override.md, nastepnieAGENTS.md, a na koniec wszelkie skonfigurowane nazwy zapasowe. Co najwyzej jeden plik na katalog jest dolaczany. -
Laczenie: Pliki sa konkatenowane od katalogu glownego w dol, z pustymi liniami miedzy nimi. Pliki blizej biezacego katalogu roboczego pojawiaja sie pozniej w prompcie, wiec efektywnie nadpisuja wczesniejsze wytyczne.
Codex pomija puste pliki i przestaje dodawac pliki gdy laczny rozmiar osiagnie project_doc_max_bytes (domyslnie 32 KiB).
Utworz globalne wytyczne
Dział zatytułowany „Utworz globalne wytyczne”Twoj globalny AGENTS.md obowiazuje w kazdym repozytorium ktore otworzysz w Codex. Uzywaj go dla osobistych umow roboczych i preferencji narzedzi.
mkdir -p ~/.codexUtworz ~/.codex/AGENTS.md:
# Global Working Agreements
## Development preferences- Prefer pnpm over npm for package management.- Always run tests after modifying source files.- Ask for confirmation before adding new production dependencies.- Use TypeScript strict mode in all new files.
## Git conventions- Write conventional commit messages (feat:, fix:, chore:, etc.).- Never force-push to main or master.- Create feature branches for all changes.
## Code style- Use single quotes for strings in JavaScript/TypeScript.- Prefer async/await over raw promises.- Add JSDoc comments to exported functions.Utworz instrukcje na poziomie projektu
Dział zatytułowany „Utworz instrukcje na poziomie projektu”Pliki na poziomie repozytorium ucza Codex norm specyficznych dla twojego projektu, dziedziczac jednoczesnie twoje globalne ustawienia domyslne.
Utworz AGENTS.md w katalogu glownym repozytorium:
# Project: E-Commerce API
## Architecture- This is a Node.js API using Fastify (NOT Express).- Database: PostgreSQL with Drizzle ORM.- Auth: JWT tokens with 24-hour expiry, refresh tokens in HTTP-only cookies.- All routes are in src/routes/ with one file per resource.
## Commands- `pnpm dev` -- Start the development server.- `pnpm test` -- Run Vitest test suite.- `pnpm lint` -- Run ESLint and Prettier checks.- `pnpm db:migrate` -- Run database migrations.- `pnpm db:seed` -- Seed test data.
## Code conventions- All new endpoints must have corresponding test files in tests/.- Use Zod schemas for request validation (not manual checks).- Error responses follow the RFC 7807 Problem Details format.- Never use console.log in production code -- use the pino logger.
## Review guidelines- Flag any API endpoint missing authentication middleware.- Flag any database query that does not use parameterized inputs.- Verify that new dependencies have more than 1000 weekly npm downloads.Zagniezdzone nadpisania dla monorepo
Dział zatytułowany „Zagniezdzone nadpisania dla monorepo”W monorepo rozne pakiety czesto maja rozne konwencje. Uzyj AGENTS.override.md w zagnieZdzonych katalogach aby zastapic szersze reguly dla konkretnych kontekstow.
myproject/ AGENTS.md # Konwencje calego projektu packages/ api/ AGENTS.override.md # Reguly specyficzne dla API (nadpisuje projektowy AGENTS.md dla tego katalogu) frontend/ AGENTS.md # Dodatki specyficzne dla frontendu shared/ AGENTS.md # Konwencje wspoldzielonej bibliotekiPrzyklad packages/api/AGENTS.override.md:
# API Service Overrides
## Testing- Use `make test-api` instead of `pnpm test`.- Integration tests require a running PostgreSQL container.- Run `docker-compose up -d db` before running tests.
## Security- Never rotate API keys without notifying the #security Slack channel.- All new endpoints must be added to the OpenAPI spec before implementation.Gdy Codex startuje z packages/api/, laduje: globalny AGENTS.md, nastepnie projektowy AGENTS.md, a na koniec packages/api/AGENTS.override.md. Plik nadpisujacy zastepuje (nie laczy sie z) jakimkolwiek AGENTS.md w tym samym katalogu.
Niestandardowe nazwy zapasowe
Dział zatytułowany „Niestandardowe nazwy zapasowe”Jesli twoj zespol juz uzywa innej nazwy pliku (jak TEAM_GUIDE.md lub CONTRIBUTING.md), powiedz Codex aby ja rozpoznawal:
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md", "CONTRIBUTING.md"]project_doc_max_bytes = 65536Codex sprawdza kazdy katalog w nastepujacej kolejnosci: AGENTS.override.md, AGENTS.md, a nastepnie kazda nazwe zapasowa w kolejnosci w jakiej je wylistowales. Tylko pierwsze dopasowanie na katalog jest uzywane.
Wzorce AGENTS.md z prawdziwego swiata
Dział zatytułowany „Wzorce AGENTS.md z prawdziwego swiata”Dla aplikacji Next.js
Dział zatytułowany „Dla aplikacji Next.js”# Next.js E-Commerce Frontend
## Stack- Next.js 15 with App Router (NOT Pages Router).- React Server Components by default. Use "use client" only when hooks are needed.- Tailwind CSS with the project's design tokens in tailwind.config.ts.- Zustand for client state. No Redux.
## Conventions- Pages go in app/(routes)/ following the route group pattern.- Shared components in components/ with .tsx extension.- API routes in app/api/ -- each route in its own directory with route.ts.- Use next/image for all images, never raw <img> tags.
## Testing- `pnpm test` runs Vitest for unit tests.- `pnpm test:e2e` runs Playwright for E2E tests.- Every new page must have at least one Playwright test.Dla serwisu Python FastAPI
Dział zatytułowany „Dla serwisu Python FastAPI”# FastAPI Authentication Service
## Stack- Python 3.12 with FastAPI and Pydantic v2.- SQLAlchemy 2.0 with async sessions.- Alembic for migrations.- Poetry for dependency management.
## Commands- `poetry run pytest` -- Run test suite.- `poetry run ruff check .` -- Lint.- `poetry run mypy .` -- Type check.- `alembic upgrade head` -- Run migrations.
## Conventions- All endpoints return Pydantic models, never raw dicts.- Use dependency injection for database sessions.- Async everywhere -- no sync database calls.- Type hints required on all function signatures.Gdy cos nie dziala
Dział zatytułowany „Gdy cos nie dziala”Nic sie nie laduje: Zweryfikuj ze jestes w zamierzonym repozytorium i ze codex raportuje oczekiwany katalog glowny workspace. Upewnij sie ze pliki instrukcji zawieraja tresc — Codex ignoruje puste pliki.
Pojawiaja sie zle wytyczne: Poszukaj AGENTS.override.md wyzej w drzewie katalogow. Zmien nazwe lub usun nadpisanie aby powrocic do zwyklego pliku.
Instrukcje sa obciete: Zwieksz project_doc_max_bytes w konfiguracji lub podziel duze pliki na zagniezdzone katalogi.
Zamieszanie z profilami: Uruchom echo $CODEX_HOME przed uruchomieniem Codex. Niestandardowa wartosc kieruje Codex do innego katalogu domowego niz ten ktory edytowales.
Codex ignoruje porady z AGENTS.md: Plik moze byc zaladowany, ale instrukcje moga byc zbyt niejasne. Uzywaj trybu rozkazujacego (“Always run tests after editing” zamiast “Tests are nice to have”). Sprawdz czy laczny rozmiar plikow nie przekroczyl limitu bajtow.