# Codex — Harness Tutorial

> 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

```bash
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:

```bash
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.**

1. **Code von Hermes liegt vor** — funktional, aber roh.
2. **Tasksheet lesen** — Was hat Hermes gebaut? Was fehlt?
3. **Ruckfragen beantworten** — Codex fragt ~10x nach. Geduld zahlt sich aus.
4. **Polishing** — Type Hints, Error Handling, Docstrings, README.
5. **Review** — `codex review` laufen lassen.
6. **Samuel reviewed** — Fertiges Produkt Samuel zeigen.
7. **Ship** — Commit-Freigabe von Samuel.

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

```bash
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"

```bash
# 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 zu Samuel (Ship):**

```bash
# Nach Codex-Session:
codex review                  # automatischer Review
# Ergebnis an Samuel:
> 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:**

```bash
# Server starten und Samuel 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. Samuel reviewed → 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:**

```bash
# 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