Nowy projekt z Codex

Poziom 4 Poradnik Zaktualizowano 2026-10-12

Nowy projekt z Codex to zamiana krótkiej specyfikacji w repozytorium, którego bramki dowodzą poprawności pracy agenta: Codex generuje tylko narzędzia, celowe usterki pokazują, że każda bramka potrafi zawieść, AGENTS.md zapisuje polecenia definiujące „gotowe”, a skrypt startowy przygotowuje każde worktree, zanim wyjdzie pierwsza funkcja.

Ta strona jest dla programisty, który odpowiada za nowy serwis od pierwszego dnia, i dla tech leada, który chce, żeby każde nowe repozytorium w zespole startowało z tej samej sprawdzalnej bazy. Sytuacja: serwis rozliczeń dostał dziś rano zielone światło, specyfikacja to strona notatek, a pierwsza prawdziwa funkcja ma być gotowa za dwa tygodnie. Szkielet, który wygląda na kompletny, ale ma test runner przechodzący bez żadnych testów, przepuści bez kontroli każdą późniejszą zmianę agenta.

Co zyskasz, stawiając projekt z Codex

Kolejność sześciu kroków od specyfikacji do pierwszej scalonej funkcji
Pięć promptów do skopiowania: przegląd specyfikacji, szkielet narzędzi, sprawdzenie bramek, AGENTS.md i pierwsza funkcja
Skrypt verify i zadanie CI, które dowodzą poprawności pracy agenta bez czytania każdego wygenerowanego pliku
Skrypt startowy dla worktree, dzięki któremu równoległe zadania Codex zaczynają z zainstalowanymi zależnościami
Sposoby wyjścia z sytuacji, w których start projektu z Codex idzie źle

Zanim zaczniesz, zainstaluj Codex i zaloguj się (instalacja Codex); podstawy, które ta strona zakłada, opisuje pierwsze zadanie w Codex.

Z której powierzchni Codex startować nowy projekt?

Codex uruchamia tego samego agenta w kilku klientach; aplikacja desktopowa i CLI czytają ten sam katalog ~/.codex/, więc wybór dotyczy tylko tego, jak chcesz obserwować pracę. Szczegóły poniżej sprawdzono na codex-cli 0.157.1 w dniu 2026-09-26.

Powierzchnia	Wybierz ją na start, gdy	Jak zacząć
Aplikacja desktopowa (macOS, Windows)	Chcesz oglądać diff w panelu przeglądu i mieć kilka wątków obok siebie	`codex app`, potem dodaj folder projektu i uruchom wątek Local dla szkieletu
CLI	Pracujesz w terminalu albo na Linuksie, gdzie `codex app` nie istnieje	Wejdź do folderu (`cd`) i uruchom `codex`
Codex cloud	Nie pierwszego dnia	Zadanie w chmurze wymaga repozytorium w serwisie takim jak GitHub i środowiska chmurowego; użyj go, gdy baza jest już wypchnięta

Według Neowin (2026-07-09, źródło wtórne) aplikacja Codex działa teraz jako tryb Codex w desktopowym ChatGPT; na macOS CLI akceptuje zarówno Codex.app, jak i ChatGPT.app. Pracę typową dla aplikacji, na przykład wybór między wątkiem lokalnym a wątkiem w worktree, opisuje strona aplikacja desktopowa Codex w praktyce.

Wbudowany domyślny model Codex to GPT-6.1 Sol z wysiłkiem rozumowania low (od codex-cli 0.159.1); dla zalogowanych kont serwer może wybrać inny domyślny model (od codex-cli 0.154.0), więc sprawdź go poleceniem /model. Aktualne ustawienia domyślne podaje przegląd modeli. Do generowania szkieletu to wystarczy. Tryb Plan, z którego korzysta krok 1, ma własne ustawienie wysiłku: ignoruje model_reasoning_effort i czyta plan_mode_reasoning_effort, a gdy ten klucz nie jest ustawiony, używa wbudowanego presetu Plan (medium) (sprawdzone w źródłach codex-cli 0.157.1, codex-rs/core/src/config/mod.rs, 2026-09-26). Do przeglądu specyfikacji uruchom Codex poleceniem codex -c plan_mode_reasoning_effort="high" (albo ustaw ten klucz w ~/.codex/config.toml), zanim zaczniesz rozważać inny model.

Postaw projekt w sześciu krokach

Utwórz repozytorium i napisz specyfikację, zanim Codex napisze kod.
Okno terminala
```
mkdir -p ~/projects/billing-service && cd ~/projects/billing-service
git init -b main
mkdir docs && touch docs/spec.md
```
Napisz docs/spec.md samodzielnie: co serwis robi, jaki stos już wybrałeś, co jest poza zakresem oraz trzy do pięciu kryteriów akceptacji pierwszej funkcji, każde sformułowane tak, żeby dało się je sprawdzić testem. Kwadrans poświęcony specyfikacji chroni przed szkieletem zbudowanym na domysłach agenta. Potem poproś Codex o krytyczny przegląd specyfikacji w trybie Plan (/plan w CLI), który proponuje, ale nie edytuje plików.
Prompt do skopiowania: przegląd specyfikacji przed szkieletem
Read docs/spec.md. Do not create or edit any files. Review it as the engineer who will build this service: 1. List every acceptance criterion that a test could not check as written, and propose a testable rewrite. 2. List decisions the spec leaves open that the scaffold forces (database driver, migration tool, test runner, how config and secrets are loaded, logging) and recommend one option for each, with a one-line reason. 3. List anything in the stack section that conflicts with anything else. End with a numbered list of questions I must answer before you scaffold.
Decyzje o stosie i architekturze, które wyjdą w przeglądzie, omawia strona planowanie architektury z Codex.

Odpowiedzi wpisz do docs/spec.md, nie do czatu. Specyfikację czyta każde kolejne zadanie; rozmowa znika razem z sesją. Potem zacommituj specyfikację, żeby repozytorium miało HEAD, z którym będą porównywane wszystkie późniejsze diffy i przeglądy:
Okno terminala
```
git add docs/spec.md && git commit -m "Add service spec"
```
Wygeneruj same narzędzia, w swoim katalogu roboczym. Uruchom Codex w folderze projektu i zaakceptuj pytanie o zaufanie: od codex-cli 0.150.0 niezaufany projekt nie dostarcza swojego AGENTS.md.
- CLI
- Aplikacja desktopowa
Okno terminala
cd ~/projects/billing-service codex
Uruchom codex app (na macOS CLI otworzy też ChatGPT.app, jeśli to ją masz zainstalowaną), dodaj ~/projects/billing-service jako projekt i uruchom wątek Local. Szkielet powstaje w wątku lokalnym, bo instalujesz go i weryfikujesz sam w tym katalogu roboczym; worktree wystartowałoby bez plików, które dopiero powstaną.
Prompt do skopiowania: szkielet infrastruktury bez logiki biznesowej
Read docs/spec.md. Scaffold the infrastructure for this service and nothing else. Stack: Node.js + TypeScript (strict), Express, Drizzle ORM with PostgreSQL, Vitest, ESLint flat config, Docker Compose for the local database. Create exactly: - package.json with scripts: dev, build, lint, typecheck (tsc --noEmit), test (unit), test:integration, db:migrate, and verify (runs lint, typecheck, test and test:integration, stopping on the first failure) - tsconfig.json with strict mode on - docker-compose.yml with PostgreSQL and a healthcheck, publishing the port as "${DB_PORT:-5432}:5432" - src/app.ts, src/server.ts, and GET /health returning {"status":"ok"} after a database ping - src/lib/db/ with the Drizzle client and an empty schema file - tests/unit/health.test.ts and tests/integration/health.test.ts that exercise GET /health for real - .github/workflows/ci.yml: on push and pull_request, top-level `permissions: contents: read`, checkout with `persist-credentials: false`, a PostgreSQL service container, `DATABASE_URL` in the job env pointing at that service container, `npm ci`, then `npm run verify` - .env.example with every variable the code reads, and .env in .gitignore Rules: - Do not create files I did not list. No README badges, no CONTRIBUTING, no placeholder features. - Do not configure any test runner to pass when it finds no tests. - Use only packages you are certain exist; list each dependency with the reason you chose it. - Do not run npm install. When you finish, print the commands I should run to install and start the database.
Instalację uruchom sam. Domyślny sandbox Codex workspace-write ogranicza dostęp do sieci, więc instalacja w sesji albo się nie uda, albo będzie wymagała zgody na wyjście poza sandbox:
Okno terminala
```
npm install
docker compose up -d --wait
npm run db:migrate
npm run verify; echo "exit code: $?"
```
Zanim zacommitujesz szkielet, sprawdź, czy każda nowa zależność istnieje i jest aktualna: npm view PACKAGE_NAME version dla każdego pakietu, którego nie znasz. Nazwa pakietu wymyślona przez model to ryzyko w łańcuchu dostaw, a nie literówka; pełną procedurę opisuje weryfikacja zależności. Potem uruchom codex review --uncommitted, żeby drugi raz przejrzeć szkielet, a gdy verify zwróci 0, zrób commit kontrolny, do którego krok 3 będzie mógł wracać:
Okno terminala
```
git add -A && git commit -m "Scaffold tooling"
```

Udowodnij, że każda bramka potrafi zawieść. Zielony verify pierwszego dnia niczego nie dowodzi, dopóki nie zobaczysz, jak każda bramka robi się czerwona. Ten krok pozwala później ufać pracy agenta bez jej czytania.

Bramka integracyjna potrzebuje lokalnej bazy, do której sandbox workspace-write sam nie sięga. Zatwierdź eskalację, gdy Codex poprosi o uruchomienie npm run verify poza sandboxem, albo wprowadź cztery usterki i uruchom verify sam; inaczej test:integration zawiedzie z powodu sandboxa, a tabela pokaże fałszywe „yes”.

I want evidence that each check in `npm run verify` can fail. For each of the four gates below:
1. Make the smallest change that should break only that gate:
   - lint: add an unused variable in src/app.ts
   - typecheck: pass a number where a string is expected in src/server.ts
   - test: change the expected /health body in tests/unit/health.test.ts
   - test:integration: point the integration test at a table that does not exist
2. Run `npm run verify` and report which gate failed and its exit code.
3. Revert the change with `git restore <file>`, and confirm that `git status --short` prints nothing.

Finish with a table: gate, breaking change, failed as expected (yes/no), exit code.
If a gate fails with a connection or sandbox error instead of the intended error, report that as NOT a valid failure.
If any gate did not fail, stop and tell me why instead of fixing it.

Każde „no” w tej tabeli to najcenniejszy wynik całego startu projektu. Napraw bramkę i uruchom prompt ponownie.

Napisz AGENTS.md na podstawie tego, co już działa. Uruchom /init („create an AGENTS.md file with instructions for Codex”), żeby dostać szkic, a potem dopracuj go promptem poniżej. Codex zechce ponownie uruchomić polecenia instalacyjne, które potrzebują sieci i Dockera: zatwierdź te eskalacje albo uruchom polecenia sam i wklej do czatu ich kody wyjścia. Codex czyta AGENTS.md przed rozpoczęciem jakiejkolwiek pracy, więc każde kolejne zadanie, lokalne czy w chmurze, dziedziczy te polecenia.

Rewrite AGENTS.md for this repository. Keep it under 60 lines. Include only what an agent cannot infer from the code:

1. One paragraph: what the service does and where the spec lives (docs/spec.md).
2. Setup: the exact commands, in order, including starting the database.
3. Definition of done: "npm run verify exits 0" plus any rule the gates cannot check.
4. Conventions the linter does not enforce: named exports, Zod validation on every route input, Drizzle for all database access, no raw SQL.
5. Boundaries: never edit .github/workflows/ or existing tests to make a check pass; ask first.
6. Code Review Rules: flag missing input validation, error responses that leak internals, and console.log outside scripts/.

Every command you write must be one that you ran successfully in this session or that I reported running successfully. Show me each one with its exit code and who ran it.

Wynik powinien wyglądać mniej więcej tak:

# Billing service

Express + TypeScript billing API on PostgreSQL via Drizzle ORM. The spec, including
acceptance criteria, is docs/spec.md; read it before changing behaviour.

## Setup
npm install
docker compose up -d --wait
npm run db:migrate

## Definition of done
- `npm run verify` exits 0 (lint, typecheck, unit and integration tests).
- New behaviour has a test that fails without the change.

## Conventions
- Named exports only. async/await, no raw promise chains.
- Validate every route input with Zod. All database access through Drizzle; no raw SQL.

## Boundaries
- Do not edit .github/workflows/ or existing tests to make a check pass. Ask first.

## Code Review Rules
- Flag missing input validation, error responses that leak internals, console.log outside scripts/.

Przetestuj plik, zamiast mu ufać: uruchom nową sesję i zapytaj „What command proves a change is done here, and which files may you not edit?”. Jeśli odpowiedź nie cytuje npm run verify i linii z sekcji Boundaries, Codex nie czyta pliku; zajrzyj do awarii opisanych niżej. Warstwy plików globalnych i zagnieżdżonych opisuje szybki start z AGENTS.md.

Przygotuj każde worktree do pracy, a potem zacommituj bazę. Zarządzane worktree zaczyna wyłącznie od zacommitowanych plików: bez node_modules/, bez .env, bez niezacommitowanych zmian (sprawdzone na codex-cli 0.157.1 na stronie izolowane zadania Codex w worktree Gita). Zacommituj skrypt startowy, żeby każde worktree, niezależnie od tego, kto je tworzy, startowało tak samo:

#!/usr/bin/env bash
# scripts/setup-worktree.sh: run from inside a fresh worktree, in your own terminal
set -euo pipefail
MAIN=$(git worktree list --porcelain | awk 'NR==1 {print $2}')   # main checkout is listed first
ID=$(basename "$(dirname "$PWD")")        # managed worktrees sit at $CODEX_HOME/worktrees/<id>/billing-service
DB_PORT=$(( 5500 + $(printf '%s' "$ID" | cksum | cut -d' ' -f1) % 400 ))   # stable port per worktree
SRC="$MAIN/.env"; [ -f "$SRC" ] || SRC=.env.example                # local values, else committed defaults
grep -v -E '^(COMPOSE_PROJECT_NAME|DB_PORT)=' "$SRC" \
  | sed -E "s#^(DATABASE_URL=.*:)[0-9]+/#\1$DB_PORT/#" > .env
grep -q '^DATABASE_URL=' .env || { echo "no DATABASE_URL in $SRC; add it to .env.example" >&2; exit 1; }
printf 'COMPOSE_PROJECT_NAME=billing-%s\nDB_PORT=%s\n' "$ID" "$DB_PORT" >> .env
export COMPOSE_PROJECT_NAME="billing-$ID" DB_PORT                 # own Compose project and database
git submodule update --init --recursive                           # no-op without submodules
npm ci
docker compose up -d --wait
npm run db:migrate

Dopisz jedną linię do sekcji Setup w AGENTS.md: „In a new worktree, run scripts/setup-worktree.sh first.” Potem zacommituj AGENTS.md i skrypt startowy i wypchnij zmiany:

chmod +x scripts/setup-worktree.sh
git add -A && git commit -m "Add AGENTS.md and worktree setup script"
git remote add origin git@github.com:YOUR_ORG/billing-service.git
git push -u origin main

YOUR_ORG to twoja organizacja albo użytkownik na GitHubie. Ustaw zadanie CI jako obowiązkową kontrolę przed scaleniem (nazwa kontroli statusu pojawia się dopiero po pierwszym przebiegu): na GitHubie otwórz Settings → Rules → Rulesets → New branch ruleset, wskaż gałąź main, włącz Require status checks to pass i dodaj zadanie CI. Klasyczne reguły w Settings → Branches też zadziałają.

Jeśli aplikacja desktopowa na twoim komputerze oferuje skrypt startowy dla wątków w worktree na poziomie projektu, wskaż w nim ten plik zamiast powielać polecenia; plik pozostaje jedynym źródłem.

Dostarcz pierwszą funkcję z worktree. Uruchom ją w izolacji od swojego katalogu roboczego: codex --worktree w CLI albo wątek Worktree w aplikacji desktopowej. Zarządzane worktree startuje na odłączonym HEAD, więc prompt najpierw tworzy gałąź.

Zanim wyślesz prompt, przygotuj worktree: uruchom w nim scripts/setup-worktree.sh we własnym terminalu albo zatwierdź eskalację, gdy Codex o nią poprosi. Skrypt instaluje pakiety i korzysta z Dockera, a sandbox workspace-write sam na to nie pozwala.

You are in a fresh Git worktree. First run `git switch -c feat/create-invoice`.
Assume scripts/setup-worktree.sh has already run. If `npm run verify` cannot reach the database, stop and tell me; do not try to start it yourself.

Implement "Create invoice" from docs/spec.md: POST /api/invoices accepting { customerId, items: [{ description, amountCents }] }.

Order of work:
1. Write one failing test per acceptance criterion in the spec, plus one for a request with an empty items array. Run them and show that they fail for the right reason.
2. Implement until they pass. Validate input with Zod; insert the invoice and its line items in one Drizzle transaction.
3. Run `npm run verify` and show the exit code.

Do not edit existing tests, .github/workflows/, or docs/spec.md. If a criterion is ambiguous, stop and ask.
Finish with: each acceptance criterion mapped to the test that proves it.

Jak sprawdzić start projektu bez czytania każdego wygenerowanego pliku?

Szkielet to kilkaset linii, których nie napisałeś. Nie musisz ich czytać, jeśli każda teza poniżej ma dowód, a dowody są tanie.

Teza	Dowód	Kto zatwierdza
Bramki działają	Tabela z kroku 3: każda bramka zawiodła na swojej psującej zmianie i przeszła po jej cofnięciu	Ty, zanim napiszesz `AGENTS.md`
Kod robi to, co mówi specyfikacja	Jeden test na kryterium akceptacji, pokazany jako czerwony przed zmianą i zielony po niej	Ty zatwierdzasz testy; testy zatwierdzają kod
Nic nie wyszło poza zlecenie	`git status --short`, który pokazuje też pliki nieśledzone, wymienia tylko pliki z promptu	Ty
Zależności istnieją	`npm view` dla każdego nieznanego pakietu i zacommitowany lockfile	Ty albo akcja przeglądu zależności w CI
Zmiana wytrzymuje drugie spojrzenie	`codex review --uncommitted` na szkielecie przed commitem kontrolnym, `codex review --base main` na gałęzi funkcji	Drugi przebieg modelu, potem człowiek w pull requeście
Działa poza twoim laptopem	Zadanie CI uruchamia `npm run verify` na świeżym kontenerze PostgreSQL	CI jako obowiązkowa kontrola

Czytaj kod tylko tam, gdzie tabela zostawia lukę: plik, którego dowody nie pokrywają, test słabszy niż jego kryterium albo uwaga z przeglądu, której nie da się odrzucić na podstawie samego diffu. Zamianę linii specyfikacji na testy opisuje strona wykonywalne kryteria akceptacji, a przygotowanie kodu dla agentów ocenia właściwości, które ten start projektu ustawia.

Co się psuje przy starcie projektu z Codex?

Codex ignoruje AGENTS.md. Projekt jest niezaufany, CODEX_HOME w jednym z klientów wskazuje inny katalog albo Codex został uruchomiony poza repozytorium. Naprawa: uruchom Codex z katalogu głównego repozytorium i zaakceptuj pytanie o zaufanie; sprawdź echo $CODEX_HOME w powłoce i w środowisku aplikacji; codex doctor pokaże, co czyta CLI. Potem powtórz test „which command proves a change is done” z kroku 4.

npm install nie działa w sesji. Sandbox workspace-write domyślnie ogranicza dostęp do sieci. Naprawa: instaluj we własnym terminalu, tak jak w kroku 2, i napisz w prompcie, żeby Codex nie instalował. Nie obchodź tego przez --dangerously-bypass-approvals-and-sandbox; tej flagi używaj wyłącznie w jednorazowym sandboksie z ograniczoną siecią, na przykład w kontenerze do wyrzucenia.

verify jest zielony w pustym projekcie. Test runner dostał polecenie, żeby przechodzić bez testów, albo jedyny test sprawdza stałą. Naprawa: uruchom ponownie prompt z kroku 3; każdą bramkę, która nie zawodzi, napraw przed czymkolwiek innym.

Szkielet urósł o pliki, o które nie prosiłeś. Odznaki w README, CONTRIBUTING.md, przykładowa funkcja. Naprawa: git status --short, żeby je wypisać, git clean -nd, żeby zobaczyć, co zostałoby usunięte z nieśledzonych plików i katalogów, a gdy lista się zgadza, git clean -fd. Zostaw w prompcie „Do not create files I did not list”.

Zależność nie istnieje albo ma kilka lat. Model zapisał z pamięci wiarygodnie brzmiącą nazwę albo starą wersję główną. Naprawa: npm view PACKAGE_NAME version dla każdego nieznanego wpisu, usuń to, co się nie rozwiązuje, i poproś Codex o zamianę na wskazany przez ciebie pakiet.

Zadanie w worktree nie może uruchomić testów. Worktree nie ma node_modules/, .env albo baza nie działa. Naprawa: uruchom scripts/setup-worktree.sh w worktree; jeśli zadanie potrzebowało niezacommitowanej pracy, zacommituj ją i zacznij nowe worktree od zaktualizowanej gałęzi.

Worktree dzielą i nadpisują jedną bazę danych. Każde zarządzane worktree leży w $CODEX_HOME/worktrees/<id>/billing-service, więc jego folder ma tę samą nazwę co twój główny katalog roboczy. Docker Compose wyprowadza nazwę projektu z nazwy folderu, dlatego docker compose up w worktree podłącza się do kontenerów głównego katalogu roboczego albo tworzy je od nowa, a db:migrate uruchamia migracje z gałęzi funkcji na bazie, na której pracujesz. Nic nie zgłasza błędu; dane po prostu zmieniają się bez twojej wiedzy. Naprawa: daj każdemu worktree własny projekt Compose i własny port, tak jak robi to skrypt z kroku 5 przez COMPOSE_PROJECT_NAME=billing-<id> (albo docker compose -p) oraz osobny DB_PORT i pasujący DATABASE_URL, przy porcie publikowanym w docker-compose.yml jako "${DB_PORT:-5432}:5432". Pełne stosy na zadanie opisuje strona środowiska efemeryczne dla zadań agentów.

AGENTS.md rośnie, aż nikt mu nie ufa. Każda poprawka staje się nową linią. Naprawa: trzymaj w AGENTS.md polecenia, definicję „gotowe” i granice; notatki o architekturze przenieś do docs/ i tylko do nich odsyłaj. Przycinanie pliku opisuje optymalizacja AGENTS.md.

Dokąd dalej po pierwszej funkcji z worktree w Codex

Izolowane zadania Codex w worktree Gita Przygotowanie, weryfikacja i sprzątanie zadań w worktree bez utraty commitów

Przepływy wieloagentowe w Codex Kilka zadań w worktree nad jedną funkcją, scalanych przez te same bramki

Codex w CI/CD Dodaj przegląd i automatyzację Codex do zadania CI utworzonego na tej stronie

Spec-driven development Utrzymaj docs/spec.md jako źródło prawdy, gdy agenci zmieniają kod

Zaczynasz taki sam projekt w innym narzędziu? Zobacz nowy projekt z Claude Code albo nowy projekt z Cursorem. Jeśli pracujesz z istniejącym kodem, a nie nowym projektem, przeczytaj poznawanie bazy kodu z Codex.