shinkan-jinkendo/.claude/rules/IMPLEMENTATION_RULES.md

Implementation Rules – Mitai Jinkendo

PFLICHTLEKTÜRE für Claude Code vor jeder Feature-Implementierung. Diese Regeln sind verbindlich und dürfen nicht ohne explizite Genehmigung des Nutzers übersprungen werden.

---

1. Konzept-basierte Implementierung (MANDATORY)

1.1 Wann gilt dieser Prozess?

PFLICHT bei:

• Feature-Requests mit verlinktem Konzept/Spec-Dokument
• Gitea Issues mit "Konzept" Label
• User sagt "laut Konzept", "wie im Konzept beschrieben"
• Komplexe Features mit >3 Datenquellen oder >5 Funktionen
• Neue Chart-Endpoints mit spezifischen Anforderungen

OPTIONAL bei:

• Einfache Bugfixes (1-2 Zeilen)
• Triviale UI-Änderungen (Text, Farbe, Spacing)
• Code-Cleanup ohne Funktionsänderung

Bei Unsicherheit: Prozess anwenden. Lieber einmal zu viel als einmal zu wenig.

---

2. Der 5-Stufen-Prozess

Stufe 1: Anforderungsanalyse (BEFORE ANY CODE)

□ Konzept/Spec-Dokument VOLLSTÄNDIG lesen
□ Pro Feature: Checkliste mit ALLEN geforderten Elementen erstellen
□ Datenquellen identifizieren (welche Tabellen, data_layer Funktionen)
□ Fehlende Funktionen dokumentieren (was muss neu gebaut werden)
□ Unklarheiten als Fragen dokumentieren
□ Gap-Analyse: Was existiert bereits? Was fehlt komplett?

Output: Anforderungs-Matrix (Tabelle oder Liste)

Beispiel für E1 (Energiebilanz Chart):

Gefordert im Konzept:
✓ Kalorienaufnahme täglich (nutrition_log.kcal)
✓ 7d Durchschnitt Aufnahme (berechnen)
✗ Trainingskalorien (activity_log.kcal) → FEHLT
✗ Gewichtstrend 7d geglättet (weight_log) → FEHLT
✗ Lagged comparison 3d/7d/14d → FEHLT
✓ TDEE geschätzt (Profile-basiert oder Formel)
✗ Energiebilanz als Balken → Chart-Typ ändern

Offene Fragen:
- Trainingskalorien: activity_log.kcal oder estimated_kcal?
- TDEE: Aus Profil oder Harris-Benedict berechnen?
- Lag-Korrelation: Pearson oder andere Methode?

Stufe 2: Umsetzungskonzept erstellen

□ Backend: Welche Endpoints? Welche Parameter?
□ Backend: Welche data_layer Funktionen? (existierend + neu)
□ Backend: Welche Berechnungen? (Formeln dokumentieren)
□ Frontend: Welche Komponenten? Welche Chart-Typen?
□ Frontend: Welche API-Calls?
□ Dependencies: Müssen andere Module angepasst werden?

Output: Strukturiertes Umsetzungskonzept als Markdown

Beispiel:

## E1: Energiebilanz Chart - Umsetzungskonzept

### Backend
**Endpoint:** `GET /api/charts/energy-balance?days=28`

**Datenquellen:**
- `nutrition_log` (kcal, date)
- `activity_log` (kcal, date) → aggregiert nach Tag
- `weight_log` (weight, date) → 7d gleitend

**Neue data_layer Funktionen:**
- `get_daily_training_calories(profile_id, days)` → Summe kcal pro Tag
- `get_weight_trend_7d(profile_id, days)` → 7d gleitender Durchschnitt
- `calculate_lag_correlation(energy_balance, weight_change, lag_days)` → Pearson

**Berechnungen:**
1. Energie-Bilanz = kcal_intake - (TDEE + training_kcal)
2. 7d avg intake = rolling_mean(kcal_intake, 7)
3. 7d avg bilanz = rolling_mean(bilanz, 7)
4. Lag-Korrelation: bilanz[t] vs. weight_change[t+3/7/14]

**Response Format:**
```json
{
  "chart_type": "mixed",  // Line + Bar kombiniert
  "data": {
    "labels": ["2026-01-01", ...],
    "datasets": [
      {"type": "line", "label": "Kalorien", "data": [...]},
      {"type": "line", "label": "7d Ø Kalorien", "data": [...]},
      {"type": "line", "label": "Training kcal", "data": [...]},
      {"type": "line", "label": "TDEE", "data": [...], "borderDash": [5,5]},
      {"type": "bar", "label": "Bilanz", "data": [...], "yAxisID": "y1"},
      {"type": "line", "label": "Gewicht (7d)", "data": [...], "yAxisID": "y2"}
    ]
  },
  "metadata": {
    "avg_intake": 2100,
    "avg_balance": -300,
    "weight_change_7d": -0.5,
    "lag_correlation": {
      "3d": 0.42,
      "7d": 0.68,
      "14d": 0.75
    }
  }
}

Frontend

Component: NutritionCharts.jsx → renderEnergyBalance()

Chart-Typ: Recharts ComposedChart (Line + Bar kombiniert)

API-Call: api.getEnergyBalanceChart(days)

Features:

• Dual Y-Axis (links: kcal, rechts: kg)
• Legende mit Hover-Details
• Tooltips zeigen alle Werte
• Lag-Korrelation in Metadata-Box unter Chart

### Stufe 3: User-Approval einholen (MANDATORY)

□ Umsetzungskonzept dem User zeigen □ Offene Fragen klären □ Auf explizites OK warten □ Bei Änderungswünschen: Konzept anpassen, erneut zeigen

**Niemals** mit der Implementierung beginnen ohne User-Approval!

### Stufe 4: Implementierung

□ Exakt nach genehmigtem Konzept implementieren □ Niemals "ähnliches" bauen oder Abkürzungen nehmen □ Bei unvorhergesehenen Problemen: User informieren, Konzept anpassen □ Commits: Referenz zum Konzept im Commit-Message

**Commit-Message Format:**

feat: E1 Energiebilanz Chart (konzept-konform)

Backend:

• Neue data_layer Funktionen: get_daily_training_calories, get_weight_trend_7d
• Endpoint: /api/charts/energy-balance mit Lag-Korrelation
• Chart-Type: mixed (Line + Bar kombiniert)

Frontend:

• ComposedChart mit Dual Y-Axis (kcal + kg)
• Lag-Korrelation Metadata-Display

Konzept: .claude/docs/functional/mitai_jinkendo_konzept_diagramme_auswertungen_v2.md (E1)

### Stufe 5: Compliance-Check (BEFORE COMMIT)

□ Jedes Feature gegen Konzept prüfen (Checkliste abhaken) □ Alle geforderten Elemente vorhanden? □ Berechnungen korrekt nach Konzept? □ Chart-Typ und Darstellung wie gefordert? □ Metadata vollständig?

**Erst nach 100% Compliance: Commit + Push**

---

## 3. Warnsignale für Fehlverhalten

**Wenn der User sagt:**
- "Das steht aber im Konzept"
- "Es fehlt X" (nach Deploy)
- "Überprüfe das Konzept"
- "Das ist nicht wie gefordert"

**→ SOFORT STOPPEN**
- Konzept nochmal vollständig lesen
- Gap-Analyse machen: Was fehlt?
- Nachfragen, nicht raten
- Konzept-konform überarbeiten

---

## 4. Skill-Integration

Für komplexe Features (>10 Funktionen, >3 Module):

```bash
/implement-feature <feature-name> <konzept-datei>

Der Skill führt automatisch Stufe 1-3 aus und wartet auf Approval.

---

5. Ausnahmen

Einzige erlaubte Ausnahme: User sagt explizit: "Ignoriere das Konzept" oder "Mach es anders als im Konzept"

Alle anderen Fälle: Prozess anwenden.

---

6. Eskalation bei Unklarheiten

Bei Unklarheiten im Konzept:

1. Niemals raten oder "ähnliches" bauen
2. Immer nachfragen:
   • "Im Konzept steht X, aber unklar ist Y. Wie soll ich vorgehen?"
   • "Option A oder Option B?"
3. Warten auf Antwort
4. Konzept mit Antwort aktualisieren

---

Zusammenfassung: 5-Stufen-Checkliste

□ 1. Anforderungsanalyse (Konzept vollständig lesen, Checkliste erstellen)
□ 2. Umsetzungskonzept (Backend + Frontend + Datenquellen dokumentieren)
□ 3. User-Approval (Konzept zeigen, auf OK warten)
□ 4. Implementierung (Exakt nach Konzept, keine Abkürzungen)
□ 5. Compliance-Check (100% Checkliste abhaken vor Commit)

Kein Schritt darf übersprungen werden.