Konfiguracja AGENTS.md w Codeksie

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.

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 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.

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ł.

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ł.
Wpisz /init w prompcie Codexa. Codex przeskanuje repozytorium i zapisze AGENTS.md w korzeniu.
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ą.
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:

# 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.

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.

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.

# terminal
mkdir -p ~/.codex
$EDITOR ~/.codex/AGENTS.md

# 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.

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ć:

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:

# terminal, z katalogu, z którego zwykle uruchamiasz Codexa
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 <INSTRUCTIONS> 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.

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.

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:

# terminal, korzeń repozytorium
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.

Dodaj wytyczne przeglądu, 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. Dodaj sekcję, na podstawie której recenzent może działać:

## Review guidelines
- 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.

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 na kanale wydań latest (v2.1.281 dla Bedrock, Google Cloud, Foundry, bramek LLM i sesji bez telemetrii; sprawdzone 2026-09-26); 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.

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 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.

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 Włącz @codex review i zastosuj swoje wytyczne przeglądu w pull requestach.

Optymalizacja AGENTS.md i skilli w Codeksie Zmieść łańcuch w budżecie, przenieś procedury do skilli i zatrzymaj CI, zanim plik zostanie obcięty.

Przycinanie CLAUDE.md i AGENTS.md Protokół ablacji do usuwania reguł, które przestały na siebie zarabiać.

Instalowanie skilli i zarządzanie nimi Gdzie leżą pliki skilli w każdym narzędziu i jak zespół je współdzieli.