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