Promptowanie Codex: brief zadania, Plan mode i AGENTS.md

Dobre promptowanie Codex polega na tym, że każde zadanie dostaje krótki brief z czterech części (cel, kontekst, ograniczenia i lista „gotowe, gdy” z komendami, które muszą przejść), a trwałe reguły projektu mieszkają w AGENTS.md. Plan mode wyłapuje złe podejście, zanim zmieni się jakikolwiek plik, a niezależny przegląd i ponownie uruchomione bramki dowodzą wyniku bez czytania każdej linii.

Ta strona jest dla programistów, którzy pracują z Codex na co dzień, i dla tech leadów, którzy chcą, żeby prompty całego zespołu dawały ten sam rodzaj dowodów. Sytuacja, którą rozwiązuje: dwóch inżynierów daje Codex ten sam ticket. Jeden dostaje przetestowaną zmianę w jednej turze. Drugi dostaje wiarygodnie wyglądający diff, który dotknął 14 plików, pominął testy i mimo to zameldował „wszystkie testy przechodzą”.

Jeśli nie masz jeszcze za sobą pierwszego zadania, zacznij od pierwszego zadania w Codex. Zasady promptowania niezależne od narzędzia znajdziesz w technikach promptowania.

Co zyskasz, promptując Codex w ten sposób

• Regułę, co należy do promptu, co do AGENTS.md, co do skilla, a co do testu.
• Czteroczęściowy brief zadania, którego ostatnia część to lista komend, a nie życzenie.
• Kolejność działań: sprawdź kontekst, zaplanuj, wykonaj, zrób przegląd w świeżym wątku, uruchom bramki ponownie.
• JSON Schema, która zamienia przebieg codex exec w raport sprawdzalny skryptem.
• Pięć promptów do skopiowania i sposoby wyjścia z typowych awarii promptów w Codex.

Co wpisać w prompt, a co w AGENTS.md?

Umieść instrukcję tam, gdzie kosztuje najmniej, a zawodzi najgłośniej. Codex ładuje AGENTS.md do każdej sesji, więc za każdą linię płacisz przy każdym zadaniu, także przy tych, które nie mają z nią nic wspólnego.

Instrukcja jest…	Umieść ją w	Dlaczego
Prawdziwa tylko dla tego zadania: błąd, endpoint, kryteria akceptacji	Prompcie	W każdej innej sesji to szum.
Prawdziwa dla każdego zadania w repozytorium: komenda testów, układ, styl błędów	AGENTS.md w katalogu głównym repozytorium	Codex czyta go przed rozpoczęciem pracy, więc nie powtarzasz tego ręcznie.
Prawdziwa dla jednego serwisu lub pakietu	Zagnieżdżonym AGENTS.md w tym katalogu	Ładuje się tylko wtedy, gdy Codex startuje w tym katalogu lub głębiej.
Wieloetapowa procedura używana od czasu do czasu (release notes, migracja)	Skillu	Ładuje się, gdy zadanie jej potrzebuje, a nie w każdej turze.
Reguła, której nie wolno złamać	Teście, regule lintera albo hooku	Prompt to prośba; czerwona bramka to fakt.

Trzy reguły ładowania decydują, czy tekst z AGENTS.md w ogóle trafi do modelu (sprawdzone na Codex CLI 0.157.1, 2026-09-26):

• Jeden plik na katalog. Od katalogu głównego projektu do katalogu, w którym uruchomiłeś Codex, każdy katalog wnosi najwyżej jeden plik: AGENTS.override.md, jeśli istnieje, a w przeciwnym razie AGENTS.md. Override zastępuje AGENTS.md tylko we własnym katalogu. Nie anuluje plików powyżej; łańcuch nadal łączy się od korzenia do liścia.
• Wspólny budżet. Pliki projektu dzielą project_doc_max_bytes, domyślnie 32 KiB. Gdy łańcuch jest za długi, ucinane są najgłębsze, czyli najbardziej szczegółowe pliki.
• Zaufanie. Od Codex 0.150.0 niezaufany projekt nie dostarcza projektowego AGENTS.md. Ładuje się tylko globalny ~/.codex/AGENTS.md.

Pełny opis ładowania, kontrolę budżetu w CI i to, kiedy przenieść regułę do skilla, znajdziesz w optymalizacji AGENTS.md i skilli w Codex.

Napisz brief, który Codex potrafi domknąć

Brief ma cztery części. Pierwsze trzy sterują pracą. Czwarta definiuje „gotowe” jako coś, co maszyna potrafi sprawdzić, i właśnie dzięki niej nie musisz czytać diffu linia po linii. Pisanie i dopracowywanie instrukcji w ten sposób to inżynieria promptów.

1. Cel. Jedna zmiana zachowania, zapisana jako wynik: „POST /api/v2/orders zwraca 429 po 20 żądaniach na minutę na klucz API”.
2. Kontekst. Pliki i wzorzec do skopiowania: „Trasa jest w src/routes/orders.ts. Skopiuj podejście z src/middleware/auth-limiter.ts”.
3. Ograniczenia. Granica zmiany: „Nie zmieniaj kształtu odpowiedzi. Nie dodawaj zależności. Dotykaj tylko src/middleware/ i src/routes/orders.ts oraz testów”.
4. Gotowe, gdy. Komendy z oczekiwanym wynikiem: „pnpm test src/middleware przechodzi, pnpm lint przechodzi, a nowy test pada, gdy usuniesz limiter”.

Najważniejsza jest ostatnia klauzula punktu 4. Test, który przechodzi nawet po usunięciu funkcji, niczego nie dowodzi, więc poproś Codex, żeby pokazał, że jego test potrafi się wywrócić.

Prompt do skopiowania: brief zaczynający od weryfikacji

Goal: POST /api/v2/orders returns HTTP 429 with a Retry-After header after
20 requests per minute per API key.

Context: the route is src/routes/orders.ts. Copy the approach in
src/middleware/auth-limiter.ts, including how it reads the key and the store.

Constraints: do not change the response body of successful requests, do not
add dependencies, and edit only src/middleware/, src/routes/orders.ts and
their tests. If you need to touch anything else, stop and ask.

Done when:
1. Write the test first in tests/middleware/orders-limiter.test.ts and run it.
   Show me it fails before the change.
2. Implement the limiter. Run `pnpm test tests/middleware` and `pnpm lint`.
3. Temporarily disable the limiter, rerun the new test, and show that it fails.
   Restore the limiter.
Finish with: files changed, each command you ran with its exit code, and
anything you assumed.

Promptuj Codex we właściwej kolejności

Większość złych wyników bierze się z dobrego promptu w złym momencie: implementacji, zanim ktokolwiek uzgodnił podejście, albo przeglądu robionego przez ten sam wątek, który napisał kod.

1. Sprawdź, co Codex już wie. Uruchom codex debug prompt-input "ping" w katalogu, w którym uruchomisz Codex. Polecenie wypisuje jako JSON dane wejściowe widoczne dla modelu, więc potwierdzisz, że twoje pliki AGENTS.md w nich są. W trakcie sesji /status pokazuje bieżącą konfigurację i zużycie tokenów.

2. Zaplanuj przed edycją. Przy wszystkim, co dotyka więcej niż jednego modułu, wpisz /plan, żeby przełączyć się w Plan mode, i poproś o plan. Zatwierdź albo popraw listę plików i testów, zanim Codex napisze kod. Poprawka planu kosztuje jedną wiadomość; poprawka gotowego diffu kosztuje nowy przebieg.

3. Wykonaj według briefu. Wyjdź z Plan mode i wklej czteroczęściowy brief. Trzymaj jedną zmianę zachowania na wątek. Na poboczne pytanie w trakcie zadania /side otwiera rozmowę boczną w efemerycznym forku, więc główny wątek zachowuje swój kontekst.

4. Zrób przegląd w świeżym kontekście. Uruchom /review w nowym wątku albo codex review --uncommitted w terminalu. Recenzent, który nie pisał kodu, nie dzieli z autorem jego martwych pól. Ile przeglądu potrzebuje każda klasa ryzyka, opisuje strona o przeglądzie pracy Codex.

5. Uruchom bramki sam. Uruchom komendy z „gotowe, gdy” w swoim terminalu albo zostaw to CI. Raport Codex to deklaracja; twoje kody wyjścia to dowód. /diff pokazuje każdy zmieniony plik, także nieśledzone, więc zmiana poza zakresem jest widoczna od razu.

Prompt do skopiowania: plan do zatwierdzenia (Plan mode)

Plan the migration of our Express error-handling middleware in src/middleware/
to Fastify hooks. Do not edit files yet.

List:
1. every file you will change and the transformation for each,
2. the existing tests that cover this behaviour, and the tests you will add,
3. the commands that prove the migration is complete,
4. what you will not change, and any risk you see.
Mark each step you are unsure about and say what would resolve it.

Prompt do skopiowania: niezależny przegląd przed merge'em

Review the uncommitted changes against the task below. You did not write
this code. Do not fix anything.

Task: POST /api/v2/orders returns 429 after 20 requests per minute per key.

Report, with file and line:
1. any change outside src/middleware/, src/routes/orders.ts and their tests,
2. any test that would still pass if the limiter were removed,
3. any behaviour change for successful requests,
4. anything the task asked for that is missing.
Answer "no findings" for a category only after you checked it.

Wklej go do nowego wątku albo przekaż jako własne instrukcje przeglądu: codex review --uncommitted - czyta je ze standardowego wejścia.

Dostrój wysiłek rozumowania, zanim przepiszesz prompt

Gdy poprawnie zbudowany brief nadal daje płytką pracę, przyczyną jest często wysiłek rozumowania, a nie sformułowanie. GPT-6.1 Sol, domyślny model dołączony do Codex od CLI 0.159.1, działa w Codex domyślnie z wysiłkiem low (CLI 0.162.1). Polecenie /model wybiera zarówno model, jak i wysiłek rozumowania. Żeby ustalić poziom dla jednego przebiegu, przekaż go jako nadpisanie konfiguracji:

# Terminal: jeden przebieg z wysokim wysiłkiem, bez zmiany config.toml
codex -c model_reasoning_effort="high" "Find the root cause of the flaky test in tests/queue/retry.test.ts"

Obowiązuje tu reguła całego serwisu: zacznij od domyślnego modelu, podnieś wysiłek, zanim zmienisz model, i zmieniaj model dopiero wtedy, gdy każe ci to twoja własna ewaluacja. Aktualne modele, poziomy wysiłku i ceny są w przeglądzie modeli.

Spraw, by wynik codex exec dało się sprawdzić maszynowo

Prompt do nienadzorowanego przebiegu codex exec potrzebuje innego zakończenia: nikt nie czyta jego prozy. Poproś o stały kształt raportu przez --output-schema, a ostatnią wiadomość zapisz do pliku przez -o. Zapisz to jako .codex/report.schema.json:

{
  "type": "object",
  "additionalProperties": false,
  "required": ["status", "files_changed", "commands_run", "assumptions"],
  "properties": {
    "status": { "type": "string", "enum": ["done", "blocked"] },
    "files_changed": { "type": "array", "items": { "type": "string" } },
    "commands_run": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["command", "exit_code"],
        "properties": {
          "command": { "type": "string" },
          "exit_code": { "type": "integer" }
        }
      }
    },
    "assumptions": { "type": "array", "items": { "type": "string" } }
  }
}

Potem uruchom brief z pliku, w sandboksie workspace-write, i sprawdź zarówno raport, jak i prawdziwe bramki:

# Terminal albo CI: brief jest czytany ze standardowego wejścia ("-")
codex exec --sandbox workspace-write \
  --output-schema .codex/report.schema.json \
  -o codex-report.json - < briefs/orders-rate-limit.md

jq -e '.status == "done"' codex-report.json   # deklaracja agenta
pnpm test && pnpm lint                         # dowód

Schema sprawia, że raport da się sparsować, a nie że jest prawdziwy. Lista commands_run pełna zer to nadal relacja agenta o samym sobie, więc pipeline uruchamia bramki ponownie. Zdarzenia JSONL, wybór sandboksa i uwierzytelnianie w CI opisuje strona Codex bez interakcji: codex exec.

Wygeneruj AGENTS.md z repozytorium, a potem go przytnij

/init tworzy plik AGENTS.md z instrukcjami dla Codex. Wygenerowany plik zwykle powtarza to, co model i tak wyczyta z package.json, więc przytnij go przed commitem.

Prompt do skopiowania: przycięcie wygenerowanego AGENTS.md

Read AGENTS.md. For each line, classify it as:
KEEP - a rule you could not infer from the code, config or README,
CUT - restates something visible in package.json, tsconfig or the layout,
MOVE - a multi-step procedure that should be a skill,
GATE - a "never" rule that a test, lint rule or hook should enforce.
Rewrite AGENTS.md with only the KEEP lines, under 60 lines, commands in
backticks. List the MOVE and GATE lines separately with a proposed home.

Które wzorce promptów marnują przebieg Codex?

Wzorzec	Przykład	Co napisać zamiast tego
Wszystko naraz	„Zrefaktoryzuj auth, dodaj testy, zaktualizuj dokumentację i popraw lint”.	Jedna zmiana zachowania na wątek; resztę ustaw w kolejce.
Nadmiar placeholderów	„Dodaj walidację [TYP] do [ENDPOINT] przy użyciu [BIBLIOTEKA]”.	„Dodaj walidację Zod do POST /users według src/schemas/order.schema.ts”.
Niewypowiedziane oczekiwanie	„Napraw błąd”.	Objaw, dane wejściowe, które go wywołują, podejrzany plik i test regresyjny do dodania.
„Nigdy” bez kontroli	„Nigdy nie loguj numerów kart”.	Zostaw zdanie i dodaj test albo regułę lintera, która pada, gdy numer karty trafi do loggera.
Samoocena	„Sprawdź swoją pracę i potwierdź, że jest poprawna”.	Komendy z kodami wyjścia, a potem przegląd w świeżym wątku.
Firmowy podręcznik	Główny AGENTS.md, który opisuje każdy zespół i proces.	Reguły repozytorium w katalogu głównym, reguły serwisów zagnieżdżone, procedury w skillach.

Prompt do skopiowania: z mglistego zgłoszenia błędu do briefu

Before changing any code, rewrite this bug report as a task brief with
Goal, Context, Constraints and Done when. Find the likely files yourself.
Done when must contain a failing regression test and the commands that
prove the fix. Ask me only the questions you cannot answer from the repo.

Bug report: login returns 500 when the email contains a plus sign.

Skąd wiesz, że prompt zadziałał, bez czytania każdej linii?

Oceniaj przebieg po dowodach, w tej kolejności:

1. Zakres. /diff wymienia tylko pliki, na które pozwalał brief. Dodatkowy plik oznacza, że ograniczenia były za luźne albo zostały zignorowane.
2. Bramki. Komendy z „gotowe, gdy” przechodzą, gdy uruchamiasz je ty albo CI, a nie tylko w raporcie Codex.
3. Siła testu. Nowy test padał przed zmianą albo padał po wyłączeniu funkcji.
4. Niezależny przegląd. /review w świeżym kontekście albo codex review --uncommitted nie zgłasza uwag w kategoriach, które wskazałeś.
5. Akceptacja. Inżynier, który napisał brief, zatwierdza pull request na podstawie tych dowodów. Tech leadzi decydują, które klasy ryzyka wymagają dodatkowo ludzkiej lektury kodu; zobacz przegląd pracy Codex.

Gdy brief dwa razy przejdzie te kontrole dla tego samego rodzaju zadania, przenieś jego trwałe linie do AGENTS.md albo do skilla, żeby następna osoba nie musiała odkrywać ich od nowa.

Kiedy prompty i AGENTS.md zawodzą w Codex

• Codex ignoruje regułę zapisaną w AGENTS.md. Uruchom codex debug prompt-input "ping" i wyszukaj regułę. Jeśli jej brak, sprawdź dwie przyczyny: pusty AGENTS.override.md w tym samym katalogu zasłania plik albo łańcuch przekroczył project_doc_max_bytes i najgłębszy plik został ucięty. Osobno potwierdź, że projekt jest zaufany (0.150.0 i nowsze): prompt-input może pokazać AGENTS.md także dla niezaufanego projektu (sprawdzone na 0.157.1), więc obecność reguły w jego wyniku nie wyklucza tej przyczyny. Usuń przyczynę, potem zacznij nowy wątek.
• Codex edytuje pliki spoza briefu. Wymień dozwolone ścieżki i dopisz: „If you need to touch anything else, stop and ask”. Zbędne zmiany cofnij przez git restore <ścieżka>, zamiast prosić Codex, żeby odtworzył je z pamięci.
• Raport mówi, że testy przechodzą, a CI pada. Agent uruchomił węższą komendę albo żadnej. Wpisz dokładne komendy w „gotowe, gdy”, poproś o kody wyjścia i niech rozstrzyga CI.
• Wynik odjeżdża od zatwierdzonego planu. Wklej zatwierdzony plan do promptu wykonawczego jako kontrakt i poproś Codex, żeby przy każdej zmianie podał, który krok planu realizuje.
• Jakość spada pod koniec długiego wątku. Kontekst jest pełen starych prób. Uruchom /compact albo zacznij nowy wątek z notatką przekazania; kiedy wybrać które, opisuje zarządzanie kontekstem w Codex.
• Płytkie odpowiedzi przy trudnym problemie. Podnieś wysiłek rozumowania przez /model albo -c model_reasoning_effort="high", zanim przepiszesz brief lub zmienisz model.

Dokąd dalej w temacie promptowania Codex

• Optymalizacja AGENTS.md i skilli w Codex: mechanizm ładowania, budżet 32 KiB i skille.
• Zarządzanie kontekstem w Codex: długie wątki, kompaktowanie i przekazania.
• Przegląd pracy Codex: głębokość przeglądu dopasowana do ryzyka.
• Codex bez interakcji: codex exec: codex exec w skryptach i CI.
• Spec-driven development: gdy brief rozrasta się w specyfikację.
• Ten sam temat dla Claude Code: prompt engineering w Claude Code.