Konfiguracja AGENTS.md
Poprosiłeś Codex o dodanie funkcji, a on użył Express gdy twój projekt działa na Fastify. Kazałeś mu uruchomić testy, a on spróbował npm test gdy twój projekt używa pnpm vitest. Codex jest potężny, ale bez kontekstu o twoim konkretnym projekcie wraca do generycznych założeń, które marnują twój czas na cofanie złych wyborów.
AGENTS.md rozwiązuje ten problem. To plik markdown który Codex czyta przed rozpoczęciem jakiejkolwiek pracy — instrukcja obsługi twojego projektu dla agenta AI. Pomyśl o nim jak o wdrażaniu nowego dewelopera: oto jak strukturyzujemy kod, oto jak testujemy, oto czego nigdy nie dotykać.
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 - Zagnieżdżone nadpisania dla konkretnych katalogów (wsparcie monorepo)
- Codex poprawnie przestrzegający twoich konwencji od pierwszego razu
- Wytyczne przeglądu które Codex stosuje przy przeglądaniu PR-ów na GitHub
Jak działa odkrywanie
Dział zatytułowany „Jak działa odkrywanie”Codex buduje łańcuch instrukcji przy starcie, przechodząc po systemie plików w określonej kolejności:
-
Zakres globalny: Codex czyta
~/.codex/AGENTS.override.mdjeśli istnieje. W przeciwnym razie czyta~/.codex/AGENTS.md. Tylko jeden plik jest używany na tym poziomie. -
Zakres projektu: Począwszy od katalogu głównego projektu (zwykle katalogu głównego Git), Codex przechodzi w dół do bieżącego katalogu roboczego. W każdym katalogu sprawdza
AGENTS.override.md, następnieAGENTS.md, a na koniec wszelkie skonfigurowane nazwy zapasowe. Co najwyżej jeden plik na katalog jest dołączany. -
Łączenie: Pliki są konkatenowane od katalogu głównego w dół, z pustymi liniami między nimi. Pliki bliżej bieżącego katalogu roboczego pojawiają się później w prompcie, więc efektywnie nadpisują wcześniejsze wytyczne.
Codex pomija puste pliki i przestaje dodawać pliki gdy łączny rozmiar osiągnie project_doc_max_bytes (domyślnie 32 KiB).
Utwórz globalne wytyczne
Dział zatytułowany „Utwórz globalne wytyczne”Twój globalny AGENTS.md obowiązuje w każdym repozytorium które otworzysz w Codex. Używaj go dla osobistych umów roboczych i preferencji narzędzi.
mkdir -p ~/.codexUtwórz ~/.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.Utwórz instrukcje na poziomie projektu
Dział zatytułowany „Utwórz instrukcje na poziomie projektu”Pliki na poziomie repozytorium uczą Codex norm specyficznych dla twojego projektu, dziedzicząc jednocześnie twoje globalne ustawienia domyślne.
Utwórz AGENTS.md w katalogu głównym 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.Zagnieżdżone nadpisania dla monorepo
Dział zatytułowany „Zagnieżdżone nadpisania dla monorepo”W monorepo różne pakiety często mają różne konwencje. Użyj AGENTS.override.md w zagnieżdżonych katalogach aby zastąpić szersze reguły dla konkretnych kontekstów.
myproject/ AGENTS.md # Konwencje całego projektu packages/ api/ AGENTS.override.md # Reguły specyficzne dla API (nadpisuje projektowy AGENTS.md dla tego katalogu) frontend/ AGENTS.md # Dodatki specyficzne dla frontendu shared/ AGENTS.md # Konwencje współdzielonej bibliotekiPrzykład 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/, ładuje: globalny AGENTS.md, następnie projektowy AGENTS.md, a na koniec packages/api/AGENTS.override.md. Plik nadpisujący zastępuje (nie łączy się z) jakimkolwiek AGENTS.md w tym samym katalogu.
Niestandardowe nazwy zapasowe
Dział zatytułowany „Niestandardowe nazwy zapasowe”Jeśli twój zespół już używa innej nazwy pliku (jak TEAM_GUIDE.md lub CONTRIBUTING.md), powiedz Codex aby ją rozpoznawał:
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md", "CONTRIBUTING.md"]project_doc_max_bytes = 65536Codex sprawdza każdy katalog w następującej kolejności: AGENTS.override.md, AGENTS.md, a następnie każdą nazwę zapasową w kolejności w jakiej je wylistowałeś. Tylko pierwsze dopasowanie na katalog jest używane.
Wzorce AGENTS.md z prawdziwego świata
Dział zatytułowany „Wzorce AGENTS.md z prawdziwego świata”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 coś nie działa
Dział zatytułowany „Gdy coś nie działa”Nic się nie ładuje: Zweryfikuj że jesteś w zamierzonym repozytorium i że codex raportuje oczekiwany katalog główny workspace. Upewnij się że pliki instrukcji zawierają treść — Codex ignoruje puste pliki.
Pojawiają się złe wytyczne: Poszukaj AGENTS.override.md wyżej w drzewie katalogów. Zmień nazwę lub usuń nadpisanie aby powrócić do zwykłego pliku.
Instrukcje są obcięte: Zwiększ project_doc_max_bytes w konfiguracji lub podziel duże pliki na zagnieżdżone katalogi.
Zamieszanie z profilami: Uruchom echo $CODEX_HOME przed uruchomieniem Codex. Niestandardowa wartość kieruje Codex do innego katalogu domowego niż ten który edytowałeś.
Codex ignoruje porady z AGENTS.md: Plik może być załadowany, ale instrukcje mogą być zbyt niejasne. Używaj trybu rozkazującego (“Always run tests after editing” zamiast “Tests are nice to have”). Sprawdź czy łączny rozmiar plików nie przekroczył limitu bajtów.