tutorials/tutorial-opencode.md

# OpenCode — Harness Tutorial

> Pipeline-Rolle: **Reality-Check** (Wave 2, Gegenentwurf)
> OpenCode prueft ob der Plan von Claude Code Sinn ergibt — und baut schnell erste Strukturen.

---

## 1. Quick Start

```bash
cd ~/Projekte/MeinProjekt     # WICHTIG: im Projektordner starten, nicht woanders

opencode                      # interaktive TUI-Session
# oder one-shot:
opencode run "Erstelle eine index.html fuer das Dashboard"
```

Erste Schritte nach dem Start:

```
> Lies ARCHITECTURE.md        # Was hat Claude Code geplant?
> Lies harness-tasksheets/task-aktuell.md   # Was ist mein Auftrag?
> Erstelle einen Gegenentwurf zu Abschnitt 2
```

TUI-Navigation:
- `Tab` — zwischen Panels wechseln
- `Ctrl+C` — Session beenden
- `/model` — Modell wechseln (MiniMax fuer guenstige Runs)

---

## 2. Typischer Workflow

**OpenCode ist kein Planer — es ist ein Prufer und schneller Builder.**

1. **Vorarbeit lesen** — Was hat Claude Code in ARCHITECTURE.md entschieden?
2. **Gegenentwurf erstellen** — Alternativen aufzeigen, Annahmen hinterfragen.
3. **Scope-Check** — Stimmt das Tasksheet? Ist der Output-Pfad klar?
4. **Bauen** — Dateistruktur anlegen, HTML-Skeleton, Python-Geruest.
5. **Ergebnis dokumentieren** — Was wurde gebaut, was wurde weggelassen, warum.

Beispiel Reality-Check Session:

```bash
opencode run "Lies ARCHITECTURE.md. Identifiziere die 3 groessten Risiken im Plan."
```

Beispiel Schnell-Build:

```bash
opencode run "
Erstelle folgende Dateistruktur fuer ein FastAPI-Dashboard:
- src/main.py (FastAPI App mit /health Endpunkt)
- src/templates/index.html (Bootstrap 5, leeres Dashboard-Layout)
- requirements.txt (fastapi, uvicorn, jinja2)
Scope: NUR diese 3 Dateien, kein extra Code.
"
```

---

## 3. Starken nutzen

**Schnelles Planen:** OpenCode liefert in <30 Sekunden einen Gegenplan.
Ideal wenn Claude Code Bedenken hat die validiert werden muessen.

**Parallele Recherche:** Mehrere opencode-Instanzen parallel starten:

```bash
opencode run "Recherchiere FastAPI WebSocket" &
opencode run "Recherchiere Svelte vs React fuer Dashboards" &
wait
```

**Saubere Dateistruktur:** OpenCode legt Dateien ordentlich an.
HTML + Python zusammen — besser als Hermes darin.

**Guenstig fuer Drafts:** Mit MiniMax (~$0.10/1M) kostet ein komplettes
HTML-Skeleton fast nichts. Lieber einen Draft wegwerfen als ihn teuer planen.

**One-shot gut geeignet fuer:**
- README-Drafts generieren
- requirements.txt aus Codebase ableiten
- Dateistruktur anlegen
- Bestehenden Code in andere Sprache uebersetzen

---

## 4. Schwachen kompensieren

**Scope-Drift:** OpenCode fragt NICHT zurueck. Es baut was es fuer richtig haelt.
Ohne explizites Briefing entsteht oft das Falsche.

Schlecht:
```
> Bau ein Dashboard
```

Gut:
```
> Bau ein Dashboard. Scope: NUR src/templates/index.html.
  Bootstrap 5. Kein JavaScript ausser was Bootstrap mitbringt.
  Kein Backend, keine API-Calls. Nur HTML-Skeleton.
  Output-Pfad: src/templates/index.html
```

**Website statt Dashboard:** OpenCode neigt dazu bei "Dashboard" eine
Marketing-Website zu bauen. Immer explizit sagen: "Admin-Dashboard, nicht Landing Page."

**Feedback-Annahme schwach:** Wenn OpenCode etwas falsch gebaut hat:
- NICHT: "Das ist falsch, mach nochmal"
- BESSER: Session beenden, neues Briefing mit explizitem Korrektiv

```bash
opencode run "
Vorher wurde index.html als Landing Page gebaut — das war falsch.
Jetzt: Admin-Dashboard fuer Monitoring. Keine Hero-Section, kein Marketing.
Nur: Navbar, Sidebar mit 3 Links, Main-Content-Area mit Platzhalter-Cards.
"
```

**Kein Gedaechtnis zwischen Sessions:** Jeder `opencode run` startet frisch.
Kontext muss immer mitgegeben werden.

---

## 5. Handoff-Muster

**Von Claude Code zu OpenCode:**

```bash
# Claude Code schreibt ARCHITECTURE.md
# Dann:
opencode run "Lies ARCHITECTURE.md und erstelle einen Reality-Check: Was koennte schiefgehen?"
```

**Von OpenCode zu Hermes (Implementierung):**

```bash
# OpenCode hat Dateistruktur angelegt und Plan validiert
# Jetzt Hermes mit dem Ergebnis briefen:
hermes chat
> Lies src/main.py und src/templates/index.html.
  OpenCode hat das Geruest gebaut. Deine Aufgabe: Implementiere Endpunkt /api/status
  der JSON zurueckgibt: {"status": "ok", "agents": []}.
  Nur diese eine Funktion.
```

**Was OpenCode an Hermes uebergibt:**
- Dateistruktur (angelegt, nicht implementiert)
- Plan-Validierung als Kommentar in DECISIONS.md
- Liste der bewusst weggelassenen Features

---

## 6. Kosten-Tipps

**MiniMax nutzen:** OpenCode unterstuetzt Modellwechsel. MiniMax ist
~150x guenstiger als Opus. Fuer Drafts und Reality-Checks vollig ausreichend.

```
/model minimax/minimax-text-01
```

**Kurzes aber vollstaendiges Briefing:** Ein schlechtes Briefing fuehrt
zu einem falschen Output — das kostet einen Re-Run. Re-Run = doppelte Tokens.
Lieber 2 Minuten laenger briefen als zweimal zahlen.

**One-shot statt TUI fuer einfache Tasks:**

```bash
# Guenestiger als TUI-Session:
opencode run "Erstelle requirements.txt fuer src/*.py"
```

**Scope eingrenzen spart Tokens:** Je groesser der Scope, desto mehr
generiert OpenCode. 3 Dateien zu erzeugen kostet weniger als 10.

**Falscher Scope = verschwendete Tokens:** Wenn OpenCode eine Website
statt ein Dashboard baut, sind alle generierten Tokens umsonst.
Briefing-Zeit ist billiger als Re-Run-Kosten.

**Faustregeln:**
- Reality-Check (ARCHITECTURE.md lesen + Feedback): ~$0.01-0.02
- HTML-Skeleton generieren: ~$0.02-0.05
- Vollstaendiges Dateigeruest (5-10 Dateien): ~$0.05-0.15
- Re-Run wegen schlechtem Briefing: gleiche Kosten nochmal