Codex — Harness Tutorial

Stand: März 2026. Aus der täglichen Praxis mit Codex; Flags, Preise und Bugs können sich seitdem geändert haben. Siehe auch: Codex Referenz.

Pipeline-Rolle: Finish und Ship (Wave 3, Polishing) Codex liefert das beste Endprodukt aller Harnesses — aber nur wenn der Input gut ist.

1. Quick Start

cd ~/Projekte/MeinProjekt     # im Projektordner starten

codex                         # interaktive Session
# oder non-interactive:
codex exec "Lies src/api.py und schreibe Type Hints fuer alle Funktionen"

Fuer Code-Review:

codex review                  # automatischer Code-Review des aktuellen Repos
codex review src/api.py       # nur eine Datei reviewen

Erste Schritte:

> Lies das Tasksheet: [Inhalt aus harness-tasksheets/task-codex-polish.md]
> Lies src/ und gib mir eine Einschaetzung: Was muss noch getan werden?

Codex wird jetzt ~10 Rueckfragen stellen. Das ist kein Bug — das ist das Feature. Alle Fragen beantworten, dann baut Codex sauber.

2. Typischer Workflow

Codex ist der letzte Schritt — nicht der erste.

Code von Hermes liegt vor — funktional, aber roh.
Tasksheet lesen — Was hat Hermes gebaut? Was fehlt?
Ruckfragen beantworten — Codex fragt ~10x nach. Geduld zahlt sich aus.
Polishing — Type Hints, Error Handling, Docstrings, README.
Review — codex review laufen lassen.
Der Owner prüft — Fertiges Produkt dem Owner zeigen.
Ship — Commit-Freigabe vom Owner.

Beispiel-Flow:

> Lies DECISIONS.md und src/. Hermes hat die Implementierung gebaut.
  Deine Aufgabe: Polishing. Type Hints, Error Handling, Docstrings.
  Dann README.md aktualisieren.
[Codex stellt Rueckfragen]
> Antwort auf Frage 1: Python 3.11+
> Antwort auf Frage 2: FastAPI-Style Docstrings
> Antwort auf Frage 3: Ja, pytest fuer alle neuen Funktionen
[Codex baut]
> Lauf `codex review` und zeig mir das Ergebnis.

3. Starken nutzen

Bestes Endprodukt: Codex liefert Code der tatsaechlich production-ready aussieht. Type Hints, Error Handling, Docstrings — alles dabei.

Grundliche Ruckfragen (~10x bevor gebaut): Das klingt nervig ist aber wertvoll. Jede Frage verhindert eine Annahme die spaeter korrigiert werden muss.

Codex: "Soll die agents-Liste aus YAML oder aus einer Datenbank geladen werden?"
→ Ohne diese Frage: Codex haette geraten → moegliche Re-Arbeit
→ Mit Antwort: saubere Implementierung beim ersten Mal

Scope-Treue: Codex bleibt nah am Referenz-Material. Was im Tasksheet steht wird gebaut — nicht mehr, nicht weniger.

Hugbsches Dashboard-Output: Wenn Codex ein Dashboard baut, sieht es professionell aus. Besser als Hermes-Output, besser als OpenCode-Output.

codex review fuer automatischen Code-Review:

codex review                  # Review des gesamten Repos
codex review src/api.py       # nur api.py
# Output: Konkrete Verbesserungsvorschlaege mit Zeilennummern

4. Schwachen kompensieren

Langsam am Start: Codex braucht Zeit um sich einzulesen. Nicht nach 30 Sekunden abbrechen — Codex denkt noch.

Dashboard-Stabilitaet: In der Eval-Phase ist Codex 2x abgestuerzt beim Generieren grosser Dashboards. Bei komplexen Outputs: - Scope in kleinere Chunks aufteilen - Nicht "baue das ganze Dashboard" sondern "baue zuerst die Navbar"

# Statt:
codex exec "Baue das komplette Dashboard"

# Besser:
codex exec "Baue nur die Navbar-Komponente in src/templates/navbar.html"
codex exec "Baue nur die Sidebar in src/templates/sidebar.html"
codex exec "Integriere Navbar und Sidebar in src/templates/index.html"

Wenig Selbstkritik ("erhaben/selbstbewusst"): Codex gibt selten zu wenn etwas nicht stimmt. Besser codex review laufen lassen als Codex selbst fragen ob der Code gut ist.

GPT 5.4 Medium = mittel-teuer: Nicht fuer Exploration nutzen. Codex nur einsetzen wenn der Code fast fertig ist.

Nicht fuer Recherche oder Drafts: Das ist Verschwendung. - Recherche → Claude Code Subagent - Drafts → OpenCode - Implementierung → Hermes - Polishing → Codex

5. Handoff-Muster

Von Hermes zu Codex:

> [Inhalt des Hermes-Summary-Tasksheets]
  Hermes hat implementiert. Deine Aufgabe:
  1. Type Hints fuer alle Funktionen in src/api.py und src/services/
  2. Error Handling: HTTPException fuer alle FastAPI Endpunkte
  3. Docstrings: Google-Style
  4. README.md: Installation + Usage aktualisieren
  Scope: NUR diese 4 Punkte. Kein neues Feature.

Codex an den Owner (Ship):

# Nach Codex-Session:
codex review                  # automatischer Review
# Ergebnis an den Owner:
> Review ist sauber. Aenderungen:
  - src/api.py: Type Hints, Error Handling, Docstrings
  - README.md: Installation + Usage
  Bereit fuer git commit wenn du freigibst.

Fertiges Produkt zeigen:

# Server starten und dem Owner zeigen:
uvicorn src.main:app --reload --port 8000
# dann: http://localhost:8000 im Browser

codex review in Pipeline integrieren:

Wave 3 Checkpoints:
1. codex review → Qualitaets-Check
2. pytest → Tests gruen
3. Der Owner prüft → Ship-Entscheidung

6. Kosten-Tipps

Ruckfragen sind Features, nicht Bugs — Geduld spart Re-Work: Eine beantwortete Ruckfrage verhindert eine falsche Annahme. Falsche Annahme = Re-Run = doppelte Kosten.

# Nicht ungeduldig werden:
Codex: "Welches Python-Version minimum?"
> 3.11+
# Diese 2 Sekunden sparen moegliche 5 Minuten Korrektur

Nur fuer Polishing nutzen, nicht fuer Exploration:

# Teuer und schlechter ROI:
codex exec "Erkunde die Codebase und finde Verbesserungsmoeglichkeiten"

# Guenstig und guter ROI:
codex exec "Fuege Type Hints zu src/api.py hinzu"

Scope begrenzen = Kosten begrenzen: Je enger der Scope, desto weniger Tokens, desto guenstiger.

Nach Hermes einsetzen, nicht vor: Codex auf rohem, unstrukturierten Code einzusetzen ist teuer weil viel mehr Korrekturen noetig sind. Erst Hermes, dann Codex.

codex exec fuer automatisierbare Tasks:

# Guenstiger als interaktive Session fuer klare Aufgaben:
codex exec "Schreibe pytest-Tests fuer alle Funktionen in src/api.py"
codex exec "Generiere OpenAPI-Dokumentation aus den FastAPI-Endpunkten"

Faustregeln: - Type Hints fuer eine Datei: ~$0.05-0.10 - Vollstaendiges Polishing (5 Dateien): ~$0.20-0.50 - README generieren: ~$0.05-0.10 - codex review fuer gesamtes Repo: ~$0.10-0.20 - Exploration (nicht empfohlen): $0.50+ fuer schlechten ROI