Rozpoczynanie projektów z Codex App

Właśnie dostałeś zielone światło na nowy serwis. Specyfikacja produktu jest w dokumencie Notion, deadline za dwa tygodnie, a potrzebujesz projektu z TypeScript, bazą danych, testami, CI i konfiguracją wdrożenia zanim napiszesz jedną linię logiki biznesowej. Ustawienie tego wszystkiego ręcznie zajmuje cały dzień. Ustawienie tego w Codex App zajmuje jeden wątek.

Co wyniesiesz z tej lekcji

• Powtarzalny proces bootstrapowania dowolnego typu projektu w Codex App
• Produkcyjnej jakości plik AGENTS.md, który uczyni każde przyszłe zadanie Codex mądrzejszym
• Konfigurację środowiska lokalnego, aby worktree automatycznie instalowały zależności
• Twój pierwszy wątek worktree — działający w izolacji od głównego checkoutu

Workflow

Krok 1: Utwórz projekt w Codex App

Otwórz Codex App i dodaj nowy projekt. Wskaż go na katalog, w którym znajduje się (lub będzie się znajdował) twoje repozytorium. Jeśli zaczynasz od zera, najpierw utwórz katalog i zainicjalizuj repozytorium git — Codex potrzebuje repozytorium git, aby włączyć tryb worktree.

mkdir ~/projects/billing-service && cd ~/projects/billing-service
git init

W Codex App kliknij selektor projektów na pasku bocznym i dodaj ~/projects/billing-service. Masz teraz przestrzeń roboczą projektu, gdzie każdy wątek dziedziczy odpowiedni kontekst.

Krok 2: Scaffolduj projekt w wątku Local

Wybierz tryb Local do początkowego scaffoldingu, ponieważ chcesz, aby pliki zostały zapisane bezpośrednio w twoim katalogu roboczym. Wyślij swój pierwszy prompt z konkretnymi ograniczeniami — Codex działa najlepiej, gdy powiesz mu, jak wygląda “done”.

Wskazówka

Gotowy prompt do scaffoldingu projektu:

Create a Node.js/TypeScript project for a billing service with:

Tech stack: Express, Drizzle ORM, PostgreSQL, Vitest, Docker Compose
Structure:
- src/routes/ for API endpoints
- src/lib/db/ for schema and queries
- src/middleware/ for auth and validation
- tests/unit/ and tests/integration/

Include:
- tsconfig.json with strict mode
- Dockerfile and docker-compose.yml with PostgreSQL
- .github/workflows/ci.yml with lint, type-check, test
- ESLint flat config with TypeScript rules
- A basic health check endpoint at GET /health

Do NOT generate placeholder business logic. Only infrastructure and tooling.

Po wygenerowaniu plików przez Codex otwórz panel recenzji (ikona diffa), aby sprawdzić, co zostało utworzone. Dodaj zmiany, które chcesz, cofnij te, których nie chcesz, i commituj bezpośrednio z App.

Krok 3: Napisz swój AGENTS.md

To jest pojedynczy plik o największym wpływie na produktywność Codex w twoim repozytorium. Każde zadanie chmurowe, automatyzacja, interakcja z GitHub i wątek lokalny czyta AGENTS.md, aby zrozumieć twój projekt. Zainwestuj tu pięć minut, a każde przyszłe zadanie będzie lepsze.

Wskazówka

Gotowy prompt do generowania AGENTS.md:

Create an AGENTS.md file at the root of this project. Include:

1. Project overview: what this service does and its tech stack
2. Setup: how to install dependencies and start the dev server
3. Testing: the exact commands to run unit and integration tests
4. Linting: the lint and type-check commands
5. Code style: our conventions (named exports, async/await, Drizzle for DB)
6. Review guidelines: what to flag during code review (no raw SQL, validate all inputs, no console.log in production code)

Keep it concise. Codex reads this on every task, so optimize for signal, not length.

Dobry AGENTS.md wygląda tak:

# Billing Service

Express/TypeScript billing API with PostgreSQL via Drizzle ORM.

## Setup
npm install
docker compose up -d  # starts PostgreSQL
npm run db:migrate
npm run dev           # starts on port 3000

## Testing
npm run test           # Vitest unit tests
npm run test:integration  # requires running PostgreSQL

## Linting
npm run lint           # ESLint
npm run type-check     # tsc --noEmit

## Code style
- Named exports only
- async/await over raw promises
- Drizzle ORM for all database access (no raw SQL)
- Zod schemas for input validation on every route

## Review guidelines
- Flag any raw SQL queries
- Flag missing input validation
- Flag console.log (use structured logger)
- Verify error responses do not leak internal details

Krok 4: Skonfiguruj środowisko lokalne

Środowiska lokalne informują Codex, jakie skrypty konfiguracyjne uruchomić przy tworzeniu worktree. Bez tego każdy worktree startuje pusty — bez node_modules, bez bazy danych, bez możliwości uruchomienia testów.

W Codex App przejdź do ustawień projektu i utwórz środowisko lokalne ze skryptem konfiguracyjnym:

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

Teraz każdy wątek worktree automatycznie instaluje zależności i uruchamia PostgreSQL zanim Codex zacznie pracę. To właśnie sprawia, że równoległy development faktycznie działa — każdy worktree jest samowystarczalny.

Krok 5: Uruchom swój pierwszy wątek Worktree

Z infrastrukturą na miejscu przetestuj pełny workflow. Wybierz tryb Worktree w edytorze wątku i wskazuj gałąź main jako punkt wyjścia. Codex tworzy izolowany git worktree w $CODEX_HOME/worktrees/, więc nic nie dotyka twojego lokalnego checkoutu.

Wskazówka

Gotowy prompt do pierwszej funkcji w worktree:

Implement a POST /api/invoices endpoint that:
- Accepts { customerId, items: [{ description, amount }] }
- Validates input with Zod
- Inserts an invoice record and line items using Drizzle
- Returns the created invoice with a generated invoice number
- Includes a unit test for the validation logic and an integration test for the database insert

Follow the patterns in AGENTS.md. Run tests after implementation.

Gdy Codex zakończy, masz trzy opcje dla zmian w worktree:

1. Create branch here — promuje worktree do nazwanej gałęzi. Wypchnij i otwórz PR bezpośrednio z App.
2. Sync with local — aplikuje zmiany z powrotem do twojego lokalnego checkoutu. Użyj tego, gdy musisz zweryfikować względem działającego serwera deweloperskiego.
3. Keep iterating — wysyłaj dodatkowe prompty w tym samym wątku, aby dopracować implementację.

Gdy coś się nie uda

Skrypt konfiguracyjny worktree nie powiedzie się po cichu. Jeśli skrypt konfiguracyjny środowiska lokalnego ma błąd (na przykład PostgreSQL się nie uruchomił), Codex kontynuuje, ale nie może uruchomić testów. Sprawdź zintegrowany terminal (Cmd + J), aby zobaczyć wynik skryptu konfiguracyjnego. Napraw skrypt i rozpocznij nowy wątek worktree.

AGENTS.md jest za długi. Jeśli twój AGENTS.md przekracza kilkaset linii, Codex spędza tokeny na czytaniu instrukcji zamiast wykonywaniu pracy. Utrzymaj go skupionego na poleceniach i konwencjach. Przenieś szczegółową dokumentację architektury do oddzielnych plików i odwołuj się do nich tylko gdy jest to istotne.

Submoduły git w projekcie. Worktree nie inicjalizują automatycznie submodułów git. Dodaj git submodule update --init do skryptu konfiguracyjnego środowiska lokalnego, jeśli twój projekt ich używa.

Prompt scaffoldingowy generuje zbyt wiele opinii. Jeśli Codex generuje pliki, o które nie prosiłeś (odznaki README, przewodniki kontrybutorskie, nadmiarowy boilerplate), dodaj jawne ograniczenie: “Do NOT create files I did not list. Only generate the files specified above.”

Co dalej

Zrozumienie baz kodu z Codex Użyj Codex na różnych powierzchniach do mapowania architektury i onboardingu do nieznanego kodu

Budowanie funkcji z równoległymi agentami Uruchamiaj wiele wątków worktree do równoległego rozwijania funkcji