# Konfiguracja AGENTS.md w Codeksie URL: https://developertoolkit.ai/pl/codex/quick-start/agents-md/ Description: Napisz globalny i projektowy AGENTS.md dla Codexa, sprawdź przez codex debug prompt-input, co się wczytało, i udowodnij, że reguły zmieniają zachowanie. `AGENTS.md` to plik instrukcji w Markdownie, który Codex dołącza do każdej sesji, zanim cokolwiek zrobi. Codex łączy jeden plik globalny z `~/.codex/` z najwyżej jednym plikiem projektowym na katalog, od korzenia repozytorium w dół do katalogu startowego, więc głębsze pliki trafiają dalej i wygrywają. Od Codex 0.150.0 projekt oznaczony jako niezaufany nie dostarcza żadnych plików projektowych. Ta strona jest dla programisty, który konfiguruje Codexa w prawdziwym repozytorium, i dla tech leada, który będzie odpowiadał za ten plik w zespole. Prosisz Codexa o nowy endpoint, a on sięga po Express w serwisie na Fastify, po czym uruchamia `npm test` w workspace na pnpm. Winny nie jest model: nic mu nie powiedziało, jak działa to repozytorium. ## Co będziesz mieć po skonfigurowaniu AGENTS.md - Krótki projektowy `AGENTS.md` z poleceniami, wyborami technologicznymi i twardymi regułami, których Codex nie wywnioskuje z kodu. - Globalny `~/.codex/AGENTS.md` z twoimi osobistymi ustawieniami, oddzielony od reguł zespołu. - Zagnieżdżony plik dla jednego pakietu w monorepo i różnicę między `AGENTS.md` a `AGENTS.override.md`. - Deterministyczne sprawdzenie, co Codex wczytał, oraz sondę, która pokazuje, czy reguły zmieniają jego zachowanie. - Trzy prompty do skopiowania: szkic pliku, sonda reguł i audyt nieaktualnych lub sprzecznych linii. Potrzebujesz zainstalowanego i zalogowanego Codexa oraz jednego wykonanego zadania. Jeśli ich nie masz, zacznij od strony [uruchom pierwsze zadanie w Codexie](/pl/codex/quick-start/first-task/). ## Jak Codex wybiera pliki AGENTS.md do wczytania? Codex buduje jeden blok instrukcji na początku każdej sesji. Poniższe zachowanie odtworzyliśmy w testowym repozytorium na Codex CLI 0.157.1 (sprawdzone w dniu 2026-09-26). | Warstwa | Gdzie szuka Codex | Reguła | | --- | --- | --- | | Globalna | `~/.codex/` (albo `$CODEX_HOME`) | `AGENTS.override.md`, jeśli istnieje, w przeciwnym razie `AGENTS.md`. Jeden plik. | | Korzeń projektu | Idzie w górę od katalogu startowego do pierwszego trafienia z `project_root_markers` (domyślnie `.git`) | Wyznacza, gdzie zaczyna się łańcuch projektowy. | | Każdy katalog, od korzenia do katalogu startowego | Ten katalog | Pierwszy istniejący z: `AGENTS.override.md`, `AGENTS.md`, potem kolejne wpisy `project_doc_fallback_filenames`. Jeden plik na katalog. | | Budżet | Wszystkie pliki projektowe razem | `project_doc_max_bytes`, domyślnie 32 768 bajtów (32 KiB). Plik globalny się do niego nie liczy. | | Zaufanie | Projekt | Projekt oznaczony jako niezaufany wczytuje tylko plik globalny (Codex 0.150.0 i nowsze). | Pierwszego dnia liczą się dwie konsekwencje. Po pierwsze, `AGENTS.override.md` ukrywa tylko `AGENTS.md` w **tym samym** katalogu; pliki powyżej nadal się wczytują. Po drugie, gdy łańcuch przekracza budżet, Codex obcina **najgłębszy** plik jako pierwszy, w pół zdania, bez żadnego komunikatu w terminalu (Codex CLI 0.157.1). Budżet szczegółowo omawia [przewodnik po optymalizacji AGENTS.md](/pl/codex/build/agents-md-optimization/). ## Przygotuj projektowy AGENTS.md przez /init Zacznij od szkicu napisanego przez Codexa, a potem go przytnij. Wygenerowany plik wymienia wszystko, co agent widział; twoim zadaniem jest zostawić tylko to, czego sam by nie ustalił. 1. Otwórz korzeń repozytorium w terminalu i uruchom `codex`. Gdy Codex zapyta **Trust this folder?**, zaakceptuj. Niezaufany projekt nigdy nie wczytuje swoich plików projektowych, więc zapisany plik nigdy by się nie wczytał. 2. Wpisz `/init` w prompcie Codexa. Codex przeskanuje repozytorium i zapisze `AGENTS.md` w korzeniu. 3. Przytnij szkic do linii, które przechodzą test: „Czy Codex pomyliłby się bez tej linii?”. Nazwy frameworków oczywiste z `package.json` zwykle odpadają. Dokładne polecenie testów, zakazane biblioteki i katalogi, których nie wolno edytować, zwykle zostają. 4. Zacommituj plik i dodaj go do `CODEOWNERS`, żeby każdą zmianę zatwierdzała konkretna osoba. Ten plik steruje każdą sesją w repozytorium, więc zasługuje na taki sam przegląd jak konfiguracja CI. Plik projektowy, który przetrwa takie cięcie, jest krótki. Ten jest dla API na Fastify w workspace na pnpm: ```markdown # Orders API ## Commands - Install: `pnpm install --frozen-lockfile` - Test one file: `pnpm vitest run path/to/file.test.ts` - Full gate before you say you are done: `pnpm typecheck && pnpm lint && pnpm test` ## Hard rules - The HTTP framework is Fastify. Never add Express or its middleware. - Validate every request body with the Zod schemas in `src/schemas/`. - Log with the `pino` instance from `src/logger.ts`. No `console.log` in `src/`. - Never edit files under `src/generated/`; run `pnpm codegen` instead. ## Definition of done - A new endpoint ships with a test in `tests/routes/` that fails without the change. - Report the gate output. If a command fails, say so; do not claim success. ``` **Prompt do skopiowania: szkic AGENTS.md, któremu możesz zaufać** ```text Draft an AGENTS.md for this repository. Read package manifests, lockfiles, CI workflows and lint/test config before writing anything. Include only: 1. The exact install, single-test, and full-gate commands, copied from CI. 2. Hard rules a reader could not infer from the code (forbidden libraries, generated directories, logging and validation conventions). 3. A short definition of done that names the commands to run. Rules for you: imperative sentences, no more than 40 lines, no framework descriptions a manifest already states. After the file, list every line you inferred rather than read from a config file, with the file you would check. Do not write the file yet; show it to me first. ``` Ostatnia instrukcja jest kluczowa. Szkic, który oddziela to, co przeczytał, od tego, co zgadł, mówi ci dokładnie, które linie sprawdzić przed commitem. ## Co należy do AGENTS.md, a co gdzie indziej? `AGENTS.md` to rada, którą czyta model. Wszystko, co musi zachodzić za każdym razem, należy do mechanizmu, który przy naruszeniu kończy się jawnym błędem. | Reguła | Gdzie ją umieścić | Dlaczego | | --- | --- | --- | | „Uruchom `pnpm test` przed zakończeniem” | `AGENTS.md` i to samo polecenie w CI | Codex zwykle się do tego stosuje; CI egzekwuje to zawsze. | | „Żadnego `console.log` w `src/`” | Reguła lintera plus jedna linia w `AGENTS.md` | Bramka lintera łapie to, co model przeoczy. | | Dwunastokrokowa procedura wydania lub migracji | Skill w `.agents/skills/` | Wczytuje się tylko wtedy, gdy zadanie jej potrzebuje, a nie w każdej turze. | | Sandbox, zatwierdzenia, dozwolony model | `config.toml` | To ustawienia, które Codex egzekwuje, a nie rady. Zobacz [konfigurację Codexa](/pl/codex/quick-start/configuration/). | ## Dodaj globalny AGENTS.md z osobistymi ustawieniami Plik globalny idzie z tobą do każdego repozytorium, więc zawiera preferencje dotyczące tego, **jak pracujesz**, a nigdy fakty o jednym projekcie. Ogranicz go do kilku linii; wczytuje się w każdej sesji. ```bash # terminal mkdir -p ~/.codex $EDITOR ~/.codex/AGENTS.md ``` ```markdown # Personal defaults - Before you change more than three files, show me a plan and wait. - Prefer small commits with conventional messages (feat:, fix:, chore:). - Never push, force-push, or open a pull request unless I ask. - When a repository's AGENTS.md disagrees with this file, follow the repository. ``` Ostatnia linia rozstrzyga konflikty na piśmie. Plik projektowy i tak wczytuje się później i zwykle wygrywa, ale zapisanie tego usuwa zgadywanie. Na tymczasową zmianę osobistą utwórz `~/.codex/AGENTS.override.md`; zastępuje globalny `AGENTS.md`, dopóki go nie usuniesz. ## Dodaj zagnieżdżony AGENTS.md dla jednego pakietu w monorepo W monorepo jeden pakiet często łamie reguły z korzenia. Umieść plik w tym pakiecie i uruchamiaj Codexa z jego wnętrza. ```text repo/ AGENTS.md # workspace-wide rules, always loaded packages/ billing/ AGENTS.md # adds billing rules on top of the root legacy-api/ AGENTS.override.md # wins over legacy-api/AGENTS.md AGENTS.md # ignored while the override exists ``` Uruchomiony z `packages/billing/` Codex wczytuje plik globalny, potem `AGENTS.md` z korzenia, a na końcu `packages/billing/AGENTS.md`. Uruchomiony z korzenia repozytorium nie wczytuje **żadnego** pliku pakietu, bo przejście kończy się na katalogu startowym. To najczęstszy powód, dla którego reguła pakietu „nie działa”. Z `AGENTS.override.md` korzystaj oszczędnie, na tymczasowy etap, taki jak migracja, i w pierwszej linii zapisz warunek jego usunięcia. Łatwo o nim zapomnieć, a dopóki ktoś go nie skasuje, ukrywa sąsiedni `AGENTS.md`. Jeśli zespół trzyma już wskazówki dla agentów w innym pliku, dodaj go jako nazwę zapasową w `~/.codex/config.toml` zamiast go powielać: ```toml # ~/.codex/config.toml project_doc_fallback_filenames = ["TEAM_GUIDE.md"] ``` Codex sprawdza nazwy zapasowe tylko wtedy, gdy w katalogu nie ma ani `AGENTS.override.md`, ani `AGENTS.md`. ## Sprawdź, co dokładnie wczytał Codex Pytanie „które pliki instrukcji wczytałeś?” daje ci to, co model pamięta. `codex debug prompt-input` wypisuje w formacie JSON prompt, który Codex by wysłał, bez wywoływania modelu: ```bash # terminal, from the directory where you normally start Codex codex debug prompt-input "ping" > /tmp/codex-prompt.json jq -r '.. | .text? // empty | select(startswith("# AGENTS.md instructions"))' /tmp/codex-prompt.json ``` Wynik to jeden blok `` wypisany z prawdziwymi podziałami wierszy. Najpierw twój plik globalny, potem separator `--- project-doc ---`, a dalej kolejne pliki projektowe od korzenia do katalogu startowego. Z `packages/billing/` w drzewie powyżej powinieneś zobaczyć trzy sekcje. Jeśli brakuje plików projektowych, folder jest oznaczony jako niezaufany. Jeśli ostatni plik kończy się w pół zdania, przekroczyłeś budżet. `codex debug prompt-input` nie ma flagi `--cd` w Codex CLI 0.157.1. Najpierw przejdź do katalogu: `(cd packages/billing && codex debug prompt-input "ping")`. ## Udowodnij, że reguły zmieniają zachowanie Codexa Plik, który się wczytuje, to jeszcze nie plik, który działa. Sprawdź twarde reguły przebiegiem tylko do odczytu i porównaj odpowiedź z oczekiwaną, zanim powierzysz plikowi prawdziwe zadania. **Prompt do skopiowania: sonda reguł AGENTS.md (tylko odczyt)** ```text Do not edit any files. For each task below, state the exact commands you would run, the files you would touch, and quote the AGENTS.md line that decided each choice. If no line applies, say "no instruction" instead of guessing. 1. Add a POST /refunds endpoint with request validation. 2. Fix a failing test in tests/routes/orders.test.ts. 3. Update a type that lives in src/generated/. ``` Zapisz powyższy prompt jako `probe.txt` w korzeniu repozytorium. Uruchom go nieinteraktywnie, żeby odpowiedź była powtarzalna: ```bash # terminal, repository root codex exec --sandbox read-only "$(cat probe.txt)" ``` Każda odpowiedź „no instruction” to luka, którą akceptujesz albo zamykasz jedną linią. Każda odpowiedź cytująca niewłaściwą linię to konflikt do naprawienia. Trzymaj `probe.txt` w repozytorium i uruchamiaj go ponownie po każdej zmianie `AGENTS.md`. Sonda mówi ci, że Codex **zamierza** stosować się do pliku. Bramki dowodzą, że to zrobił. Polecenia z sekcji „Definition of done” trzymaj w CI, żeby sesję, która zignorowała regułę, zatrzymał build, a nie czujność recenzenta. Jak przeglądać zmiany bez czytania każdej linii, opisuje strona [przejrzyj zmiany Codexa przed commitem](/pl/codex/quick-start/review-workflow/). ## Dodaj reguły code review, które Codex stosuje w pull requestach Przegląd w Codexie czyta te same pliki. Instrukcje przeglądu wbudowane w Codex CLI 0.157.1 każą recenzentowi korzystać z plików instrukcji z korzenia i z zakresu zmienionych plików, a przy konflikcie wygrywają wskazówki bardziej szczegółowe. Dla przeglądów na GitHubie przewodnik OpenAI mówi: „Add a `## Code Review Rules` section to the file closest to the code the rules govern” (odczyt 2026-10-13). Dodaj sekcję, na podstawie której recenzent może działać: ```markdown ## Code Review Rules - Flag any route in src/routes/ registered without the auth preHandler. - Flag SQL built with string concatenation instead of the query builder. - Treat a missing test for a new endpoint as a P1 finding. ``` Wypróbuj ją lokalnie przed pushem poleceniem `codex review --base main`. Aby te same reguły działały na GitHubie z `@codex review`, przejdź do strony [połącz Codexa z GitHubem](/pl/codex/quick-start/github-integration/). ## Jeden AGENTS.md dla Codexa i Claude Code `AGENTS.md` nie jest wyłącznie plikiem Codexa. Claude Code czyta `AGENTS.md`, gdy w repozytorium nie ma `CLAUDE.md`, od wersji v2.1.277 (v2.1.281 dla Bedrock, Google Cloud, Foundry, bramek LLM i sesji bez telemetrii), na obu kanałach wydań (sprawdzone 2026-10-12); przełącznik jest w sekcji „Project instructions” w `/config`. Zespół, który używa obu narzędzi, może trzymać jeden plik zamiast dwóch, które z czasem się rozjadą. Szerszy obraz daje strona [AGENTS.md i CLAUDE.md jako zwięzły kontekst repozytorium](/pl/developer-scorecard-guide/claude-md-context/). ## Dlaczego Codex ignoruje mój AGENTS.md? Większość awarii to problemy z wczytywaniem, a nie z modelem. Sprawdzaj je w tej kolejności. | Objaw | Przyczyna | Naprawa | | --- | --- | --- | | W `codex debug prompt-input` widać tylko reguły globalne | Projekt jest oznaczony jako niezaufany | Uruchom ponownie `codex` w folderze i zaakceptuj **Trust this folder?** albo ustaw `trust_level = "trusted"` w sekcji `[projects."/absolute/path"]` w `~/.codex/config.toml`. | | Reguły pakietu nigdy nie działają | Codex został uruchomiony z korzenia repozytorium | Uruchamiaj Codexa w katalogu pakietu. Reguły, które mają obowiązywać wszędzie, trzymaj w pliku w korzeniu. | | `AGENTS.md` w katalogu jest ignorowany | Obok leży `AGENTS.override.md`, być może pusty | Usuń override albo przenieś jego treść i wtedy go usuń. | | Najgłębszy plik urywa się w pół zdania | Łańcuch przekracza `project_doc_max_bytes` | Najpierw przytnij plik w korzeniu. Podniesienie limitu tylko ukrywa problem; [przewodnik po optymalizacji](/pl/codex/build/agents-md-optimization/) ma kontrolę budżetu w CI. | | Zmiany w `~/.codex/AGENTS.md` nic nie dają | `CODEX_HOME` wskazuje inny katalog | Uruchom `echo $CODEX_HOME`. Gdy zmienna jest ustawiona, Codex czyta plik globalny z tego katalogu. | | Plik się wczytuje, a Codex i tak łamie regułę | Reguła jest mglista albo przeczy jej inna linia | Przepisz ją jako polecenie z konkretną ścieżką lub komendą, a potem wesprzyj regułą lintera lub testem. | | Codex uruchamia polecenie, które już nie istnieje | Plik zestarzał się po zmianie narzędzi | Po każdej zmianie skryptów w `package.json` lub CI uruchom poniższy prompt audytowy. | **Prompt do skopiowania: audyt AGENTS.md pod kątem nieaktualnych i sprzecznych reguł** ```text Audit every AGENTS.md and AGENTS.override.md in this repository, plus ~/.codex/AGENTS.md. Do not edit anything. Report: 1. Commands that do not exist in package.json scripts, the Makefile, or CI. 2. Pairs of lines that contradict each other, with both file paths. 3. Lines that restate what a manifest or config file already makes obvious. 4. Any AGENTS.override.md, with the AGENTS.md it currently hides. End with a proposed diff that removes or fixes each item, smallest first. ``` ## Co dalej z AGENTS.md - [Połącz Codexa z GitHubem](/pl/codex/quick-start/github-integration/) — Włącz @codex review i zastosuj swoje reguły code review w pull requestach. - [Optymalizacja AGENTS.md i skilli w Codeksie](/pl/codex/build/agents-md-optimization/) — Zmieść łańcuch w budżecie, przenieś procedury do skilli i zatrzymaj CI, zanim plik zostanie obcięty. - [Przycinanie CLAUDE.md i AGENTS.md](/pl/workflows/context/pruning-context-files/) — Protokół ablacji do usuwania reguł, które przestały na siebie zarabiać. - [Instalowanie skilli i zarządzanie nimi](/pl/ecosystem/skills/installing-managing/) — Gdzie leżą pliki skilli w każdym narzędziu i jak zespół je współdzieli.