Eine App, die nichts rät

coachframe.ai ist ein SaaS für wissenschaftsbasiertes Multisport-Coaching. Athleten trainieren so, wie eine gewählte Coach-Persona es täte — belegt, im Chat. Über den Sport schreibe ich hier nicht. Mich interessiert der Maschinenraum.

Die meisten Trainings-Apps raten. Sie werfen eine Formel auf deine Herzfrequenz und nennen das Wissenschaft. Ich wollte es andersherum: Jede Zahl, die der Coach ausgibt, ist auf eine real existierende Primärquelle rückführbar — oder ehrlich als abgeleitet markiert. Kein stiller Wert ohne Herkunft. Diese eine Vorgabe bestimmt, wie das ganze Projekt gebaut ist.

Erst die Spezifikation, dann der Code

Das Projekt läuft spec-first. Bevor eine Zeile Code entsteht, steht das Konzept. Ich nutze dafür specumentation, eine eigene Konvention für Konzept → Epic → Ticket → Code. Die Verzeichnisse sind fest: docs/concept/ für die Spezifikation, docs/epics/ für die Tickets.

Der Stand heute: 24 nummerierte Konzept-Dokumente, 13 Epics, 99 Tickets. Jedes Konzept trägt einen Status — Entwurf, freigegeben, implementiert — und verlinkt sauber auf die anderen. Ein Epic wird aus einem oder mehreren Konzepten abgeleitet, jedes Ticket verweist auf den konkreten Konzept-Paragraphen, an dem es hängt:

### [E-13.04] Multisport-Verteilung im Generator
Status: erledigt
Konzept-Ref: [24] §1, [02] §3

Der eigentliche Gewinn liegt in der Rückkopplung. Ein Audit am Konzept deckt auf, dass ein bereits als „erledigt" geführter Bereich in Wahrheit eine Lücke hatte — woraufhin ein neues Konzept und ein neues Epic den alten Bereich wieder aufmachen. Die Spezifikation führt, der Code zieht nach. Wer schon mal versucht hat, aus gewachsenem Code rückwärts ein Konzept zu rekonstruieren, weiß, warum das die ruhigere Variante ist.

Die Evidenzbasis: nichts raten, alles belegen

Neben den Apps liegt auf Repo-Ebene ein Verzeichnis research/. Das ist die Quellenbasis für das Coaching-LLM. 112 Studien-Karteikarten über sechs Domänen — Training, Load/Recovery, Psychologie, Ernährung, Gender/Alter, Kraft. Jede Karte ist eine echte, begutachtete Primärquelle, kein Blog-Post und keine KI-Zusammenfassung unbekannter Herkunft. Die vollständige Quellenliste steht öffentlich auf coachframe.ai/wissenschaft.

Eine Karteikarte ist nicht bloß ein Zitat. Sie hat YAML-Frontmatter mit DOI, Evidenzklasse, Stichprobengröße und Population, dazu einen Validierungs-Block, der festhält, wer die Quelle wann gegen PubMed geprüft hat. Wichtig ist der maschinenlesbare Teil: Aus jeder Karte fallen Entscheidungsregeln, aus denen sich der Plan-Generator speist.

decision_rules:
  - when: "easy_run AND hr > aerobic_threshold"
    then: "flag intensity drift"
    rationale_study: "2010-seiler-best-practice-distribution"

Damit das im Produkt hält, ist die Belegpflicht selbst zu einem Konzept geworden. Jeder dosimetrische Wert im Generator trägt entweder rationale: [<slug>] — Verweis auf eine echte Karteikarte — oder derived: [<feld>], wenn er aus belegten Größen abgeleitet ist. Ein Build-Test validiert die Slugs gegen die real existierenden Karten. Ein unbelegter Wert lässt das CI durchfallen.

Von der Studie zur Coach-Persona

Damit aus den Karteikarten ein Coach wird, der im Chat eine Haltung hat, braucht es zwei Schritte: Aggregation und Personifizierung.

Aggregation. Eine einzelne Studie ist noch keine Trainingsregel. Darum trägt jede Karteikarte einen maschinenlesbaren Block mit when / then-Regeln und dem Befund, der die Regel stützt:

- when: athlete.training_status in ["well_trained", "elite"]
        and athlete.tid.hit_share_by_session > 0.30
  then: coach.warn("Hart-Anteil ist hoch — kein langfristiger Vorteil belegt, Erholungsrisiko prüfen.")
  rationale_study: 2010-seiler-best-practice-distribution

Die Regeln aus vielen Karten werden pro Trainingsschule zu einer Methoden-Doktrin verdichtet — Polarized (Seiler), VDOT (Daniels), Block-Periodisierung (Rønnestad), das norwegische Doppel-Threshold (Tjelta-Bakken) und vier weitere. Acht Doktrinen, jede an reale Forschung und eine reale Trainingsphilosophie gebunden. Daraus wird eine maschinenlesbare Regelbasis, aus der sich der Plan-Generator speist.

Konflikte gehören dazu. Studien widersprechen sich. Seiler sagt polarisiert, eine neuere Arbeit zeigt in der Basisphase eher pyramidal. Aufgelöst wird das nicht per Münzwurf, sondern über die Phase: in der Basis pyramidal, zur Spitze polarisiert. Die widersprechende Karte wird nicht gelöscht, sondern überholt — sie bleibt lesbar, und die Empfehlung wird an der Stelle vorsichtiger. Oft ist eine Karte, die einer Schule widerspricht, gar kein Widerspruch, sondern schlicht der Beleg für eine andere Schule.

Personifizierung. Die acht Methoden sind die interne Tiefenschicht — der Athlet sieht sie nie direkt. Darüber liegen 85 Coach-Charaktere mit Namen und Gesicht, jeder fest an eine der acht Methoden gebunden. Statt „du trainierst ab jetzt nach Schule X" wählt der Athlet einen Coach, der eine Haltung mitbringt.

Entscheidend ist die Trennung von Methode und Stil. Die Methode bestimmt den Inhalt — was im Plan steht. Der Stil bestimmt nur die Sprache — wie der Coach es sagt. Sechs Stile gibt es, von sachlich-nüchtern bis sokratisch-fragend, und jede Methode lässt nur die Stile zu, die zu ihr passen. Einen nüchtern-wissenschaftlichen Polarized-Coach im Drill-Sergeant-Ton gibt es nicht — das wäre eine Figur, die ihrer eigenen Methode widerspricht. Die Trennung muss strikt bleiben; vermischt man sie im Code, franst die Coach-Stimme aus.

Claude als Werkzeug an mehreren Stellen

Ein solches Projekt allein durchzuziehen — Recherche, Konzept, drei Apps — geht nur mit Hebeln. Claude ist einer davon, an mehreren Stellen der Kette:

• Recherche. Ein PubMed-Fetcher (NCBI E-utils) zieht die Records, Claude liest Abstracts, ordnet ein und füllt die Karteikarte nach Template. Die Zahlen stammen wörtlich aus dem Abstract, die Validierungs-Notiz hält fest, wo der Volltext noch fehlt.
• Aggregation. Claude verdichtet die Karten zu Methoden-Doktrinen und löst Widersprüche zwischen Studien sauber auf.
• Konzeption. Die Konzept-Dokumente und Epics entstehen im Dialog — ich gebe Richtung und Audit-Blick, das Modell hält Struktur und Querverweise konsistent.
• Umsetzung. Laravel-Services, Nuxt-Komponenten, die Expo-App. Der Output ist normaler Code, kein Black-Box-Generat.

Claude ist hier kein Selbstzweck und keine Magie, sondern ein Werkzeug unter mehreren, das an den richtigen Stellen Zeit spart. Den Audit-Blick, was stimmt und was nicht, behalte ich.

Der Output: drei Apps, ein gemeinsamer Kern

Das Monorepo hat drei Apps und teilt sich Wissen und Belege auf Repo-Ebene.

• apps/api — Laravel 13, PHP 8.3, Sanctum. Postgres, Redis, S3.
• apps/web — Nuxt 4, Vue 3. Kein Tailwind, sondern ein eigenes Token-System namens „Night Ride".
• apps/mobile — Expo, React Native. Liest Apple HealthKit und liefert Workouts plus Tagesvitalwerte an die API.

Daten kommen aus Garmin und Apple Health. Weil dieselbe Einheit oft über beide Wege hereinkommt, läuft vor der Auswertung eine Deduplizierung — sonst zählt ein Lauf doppelt in die Trainingslast.

Der Chat: Fakten zuerst, Modell danach

Hier weiche ich vom Erwartbaren ab. Der naheliegende Weg für einen Coaching-Chat wäre ein Agent mit Tool-Calling: Das Modell ruft selbst Funktionen auf, um den Plan zu lesen oder Aktivitäten zu holen. Vorbereitet ist das im SDK-Wrapper.

Genutzt wird es im aktiven Pfad nicht. Stattdessen sammelt ein Kontext-Assembler die Fakten deterministisch, bevor das Modell überhaupt dran ist: die Analyse-Marker der Einheit, die aktuelle Form, die Leistungs-Anker. Daraus baut ein Persona-Builder den System-Prompt — Methoden-Doktrin, Persona-Stimme, Guardrails, dann der Fakten-Block. Erst dann streamt das Modell die Antwort.

Warum nicht das Modell die Fakten holen lassen? Weil das Produkt verspricht, nichts zu raten. Ein deterministischer Fakten-Layer ist prüfbar und reproduzierbar. Tool-Calling ist mächtig, aber es verlagert Kontrolle dorthin, wo ich sie bei einem Belegpflicht-Produkt am wenigsten haben will. Die Architektur ist vorbereitet, falls sich das ändert.

Das Coaching-LLM ist durchweg Claude; das Modell wird pro Zweck gewählt — Sonnet für den Chat, Opus für Planung und Review, Haiku für kurze Mitteilungen. Jede Anfrage landet mit Token-Zahlen und Kosten in einer eigenen Tabelle, damit nichts im Nebel läuft.

Was bleibt

Spec-first kostet vorne Zeit und zahlt sie hinten zurück. Die Evidenzbasis ist Arbeit, die man sieht, sobald jemand fragt „warum eigentlich?" — dann steht da eine Studie und keine Ausrede. Und ein deterministischer Fakten-Layer vor dem LLM ist langweiliger als ein Agent mit Tool-Calling, aber er tut, was er soll.

Mehr ist es nicht. Für eine App, die nichts raten darf, reicht das.