# CLAUDE.md — Steve-TradingBot Engineering Rules

Diese Datei enthält verbindliche Projektregeln für Claude Code.

---

## 1. Plan before code

Vor jeder Codeänderung:

1. Relevante Dateien lesen.
2. Alle Call-Sites finden.
3. Alle Downstream-Consumer finden.
4. DB-Writes prüfen.
5. GUI-Consumer prüfen.
6. Bot-/Worker-/CommandBus-Besitz klären.
7. Tests identifizieren.
8. Cross-Impact-Matrix erstellen.
9. Bei riskanten Bereichen auf Operator-GO warten.

Kein Code vor Plan, wenn die Änderung betrifft:

- Trading-Logik
- Order Execution
- Bot Runtime
- Worker Runtime
- Portfolio-State
- DB-Schema
- DB-Mutation
- CommandBus
- env-Dateien
- Mainnet
- Wallets
- Secrets
- Strategieparameter

---

## 2. Cross-Impact-Matrix ist Pflicht

Vor jeder nicht-trivialen Änderung muss diese Matrix erstellt werden:

| Changed Area | Direct Effect | Downstream Consumers | Required Follow-up |
|---|---|---|---|

Zu prüfen sind immer:

- GUI
- CommandBus
- Worker
- Bot Runtime
- Exchange/API Execution
- Portfolio-State
- Postgres Telemetry
- Dashboard / Analytics
- Telegram / Reporter
- Tests
- Backlog / Memory

Ein Fix ist nicht vollständig, wenn nur eine Schicht repariert wurde und eine andere bekannte Schicht weiterhin kaputt ist.

---

## 3. Layer-Completion-Regel

Eine Aufgabe darf nur als `CLOSED` gemeldet werden, wenn alle betroffenen Layer entweder:

- gefixt,
- getestet,
- bewusst out-of-scope,
- oder als Follow-up mit Namen und Prio gepinnt wurden.

Beispiel `close_position`:

Ein erfolgreicher Command muss prüfen:

- GUI erzeugt Command
- CommandBus Audit existiert
- Worker verarbeitet Command
- LiveTrader/Testnet Execution funktioniert
- live_portfolio.json ist konsistent
- trade_logs wird geschrieben
- position_snapshots wird geschrieben
- Dashboard/History/PnL zeigen den Trade
- Bot überschreibt keinen State mit stale RAM
- Retry/Idempotency funktioniert
- Mainnet bleibt verboten

---

## 4. State-Split-Brain-Regel

Wenn Bot und Worker denselben State lesen oder schreiben, muss geprüft werden:

- Gibt es getrennte In-Memory-Instanzen?
- Wird dieselbe Datei geschrieben?
- Gibt es File-Lock / Reload / mtime-check?
- Kann ein Prozess den State des anderen überschreiben?
- Können Phantom-Positionen entstehen?
- Können doppelte Sells entstehen?

Jede Worker-State-Mutation braucht eine Bot-Side-Konsistenzprüfung oder einen expliziten Follow-up-Blocker.

---

## 5. Telemetry-Pflicht

Jede Funktion, die Exchange-/Portfolio-State verändert, muss Telemetrie schreiben oder bewusst begründen, warum nicht.

Pflichtflächen:

- trade_logs
- position_snapshots
- bot_statuses, falls relevant
- CommandBus audit, falls command-getrieben
- live_portfolio.json oder äquivalenter State
- GUI History/PnL-Verfügbarkeit
- metadata_json mit command_id/source/reason, falls vorhanden

Kein erfolgreicher Exchange- oder Testnet-Trade darf nur im Log oder CommandBus sichtbar sein.

---

## 6. Mainnet- und Secret-Regeln

Strikt verboten ohne explizites Operator-GO:

- Mainnet aktivieren
- mainnet in Allowed-Environments ergänzen
- Wildcard-Allow verwenden
- Private Keys ausgeben
- API Keys ausgeben
- Seed Phrases verwenden
- `docker compose config` mit Secrets ausgeben
- env dumps ausgeben
- Wallets funden
- echte Solana-Orders ausführen

Default:

```text
BINANCE_TESTNET=true
MULTI_STRATEGY_DRY_RUN=true
T2_SOLANA_EXECUTION=false
T3_COPY_TRADING=false
```

---

## 7. CommandBus-Regeln

CommandBus-Änderungen brauchen besondere Prüfung:

- allowed environments
- idempotency keys
- retry behavior
- terminal states
- active duplicate behavior
- audit timeline
- GUI notification
- Worker handler
- runtime registry
- GUI registry
- mainnet bleibt verboten

Kein Command gilt als fertig, wenn er nur `succeeded` im CommandBus ist, aber keine Telemetry erzeugt.

---

## 8. Strategy-Group-Regeln

Jede Änderung an `strategy_id` oder `strategy_group` muss prüfen:

- decision_logs
- trade_logs
- position_snapshots
- GUI StrategyGroup Widgets
- T1/T2/T3 Architekturvertrag
- Tests
- Backlog/Docs

Aktuelle Zielarchitektur:

```text
T1 = Binance only
T2 = Solana Pump only, disabled until separate GO
T3 = Copy Trading only, disabled until separate GO
```

T1 darf nur Binance handeln.  
T2 darf nicht als Binance-Pump-Label weiter ausgebaut werden.  
T3 bleibt deaktiviert.

---

## 9. T1 Binance-only-Regel

Jedes Signal, das an T1 geht, muss Binance-handelbar sein.

Pflicht:

```text
Signal → Binance Pair exists?
yes → T1 may evaluate
no  → reject_reason = symbol_not_on_binance
```

Kein Solana-Fallback.  
Kein Trade auf nicht gelistete Coins.  
Kein T2-Fallback in T1.

---

## 10. Runtime- und Cutover-Regeln

Keine Runtime-Änderung ohne explizites Operator-GO:

- Bot restart
- Worker restart
- GUI restart
- env change
- Docker rebuild
- DB migration
- CommandBus registry change
- Strategy activation

Bei Bot-/Worker-/GUI-Code im Container:

- Watchdog freeze, falls Bot betroffen
- SOT-1d Build/Recreate-Pfad verwenden
- 3-Way MD5 prüfen: Repo == Image == Container
- Healthcheck prüfen
- Tracebacks prüfen
- relevante Telemetrie prüfen
- Rollback-Hinweis liefern

---

## 11. Test-Regeln

Jede Änderung braucht passende Tests.

Mindestens:

- gezielte Unit-/Feature-Tests
- relevante Regressionen
- Syntax-Check
- Runtime-Smoke, falls Container betroffen

Wenn Tests nicht möglich sind:

- ehrlich sagen
- Grund nennen
- manuelle Verify-Schritte liefern
- Follow-up pinnen

---

## 12. Scope-Regeln

Keine stille Scope-Erweiterung.

Nicht nebenbei ändern:

- Strategieparameter
- Risk-Parameter
- Cash-Caps
- Time-Stops
- DCA-Regeln
- CommandBus-Versionen
- env-Dateien
- DB-Schema
- GUI-Actions
- Mainnet-/Wallet-bezogene Logik

Wenn eine Änderung Folgeprobleme offenlegt, diese klar melden und als separate Phase pinnen.

---

## 13. Closure-Format

Jede Closure muss enthalten:

- Root Cause
- geänderte Dateien
- Tests
- Cross-Impact-Ergebnis
- Runtime-Status
- 3-Way MD5 bei Container-Code
- Bot/Worker/GUI Status, falls betroffen
- DB-Boundaries
- Mainnet-Status
- was bewusst nicht geändert wurde
- verbleibende Risiken
- Follow-up-Backlog
- STOP

Niemals `CLOSED` melden, wenn:

- Telemetry fehlt
- GUI nichts anzeigt
- State inkonsistent ist
- ein bekannter Downstream-Bug offen bleibt
- ein Bot/Worker-Split-Brain möglich ist
- nur die erste Fehlerschicht behoben wurde