KI-Workflow

Dieses Projekt wurde mit Claude Code gebaut. Die meisten Behauptungen „mit KI gebaut” hören beim Label auf. Hier ist das vollständige Bild: was die KI weiß, wie Sitzungen funktionieren, wie Prompting in der Praxis aussieht und wo der Mensch die Grenze zieht. Wenn Sie selbst mit KI bauen oder einfach neugierig sind, wie das tatsächlich aussieht, ist dies für Sie.

Was die KI weiß

Claude Code verfügt über eine persistente Speicherdatei, die Kontext über Sitzungen hinweg bewahrt. Anstatt in jedem Gespräch die Codebasis neu zu erkunden, knüpft es dort an, wo wir aufgehört haben. Hier ist der Inhalt (bereinigt):

Projektidentität

• App-Name, Quellverzeichnis, Lizenz, App-Kennung
• Fork-Beziehung: Upstream ist En Croissant von Francisco Salgueiro, wir pflegen unseren eigenen Fork unabhängig
• Warum der Fork existiert: Der Upstream-Maintainer hat das TTS-Feature abgelehnt, was fair ist — unterschiedliche Visionen für dasselbe Projekt

Build-Regeln

• Nur pnpm — npm bricht vanillaExtract (weißer Bildschirm zur Laufzeit, kein Fehler, einfach nichts)
• Node.js 22+ erforderlich (Vite 7 benötigt crypto.hash)
• Immer pnpm format && pnpm lint:fix vor dem Committen
• App schließen, bevor die Binary überschrieben wird („Text file busy”)
• Nach dem Verschieben von Quellverzeichnissen cargo clean ausführen, um veraltete Pfadverweise zu bereinigen

Architekturwissen

• Welche Dateien welche Features besitzen (Atoms in atoms.ts, Baumnavigation in tree.ts, TTS-Engine in tts.ts)
• Warum alle TTS-Atoms getOnInit: true benötigen (imperative Lesezugriffe via store.get() bevor React subscribed)
• Wie der Audio-Cache funktioniert (provider:voiceId:lang:text-Schlüssel)
• Der Chessground-Koordinaten-Fix ist CSS-seitig, kein Fork der Bibliothek
• Datenlayout: was wo liegt, was per Symlink verknüpft ist, was App-Neustarts überlebt

Was sie nicht weiß

Der Speicher enthält keine API-Schlüssel, Passwörter oder Zugangsdaten. Er referenziert deren Speicherorte (localStorage-Atom-Namen), aber niemals die Werte. Die KI generiert Code, der Schlüssel aus den Einstellungen liest — sie sieht oder handhabt die eigentlichen Geheimnisse nie.

Was der KI gesagt wird

Über die Speicherdatei hinaus folgt Claude Code Regeln, die in sein System eingebaut sind:

• Nicht über-engineeren. Nur Änderungen vornehmen, die direkt angefragt wurden. Ein Bugfix erfordert keine Bereinigung des umgebenden Codes. Drei ähnliche Codezeilen sind besser als eine voreilige Abstraktion.
• Keine URLs erraten. Niemals Links oder Endpunkte erfinden.
• Lesen vor dem Bearbeiten. Niemals Änderungen an Code vorschlagen, den sie nicht gelesen hat.
• Bearbeiten statt Erstellen bevorzugen. Keine neuen Dateien erstellen, es sei denn, es ist absolut notwendig.
• Keine Sicherheitslücken. Auf Injection, XSS und OWASP-Top-10-Probleme achten.
• Bei Unsicherheit fragen. Wenn eine Anweisung mehrdeutig ist, fragen statt raten.
• Zweimal messen, einmal schneiden. Destruktive Operationen (Force Push, Reset —hard, Dateien löschen) erfordern explizite menschliche Freigabe.

Gute Prompts schreiben

Der Unterschied zwischen einer nützlichen KI-Interaktion und einer frustrierenden ist fast immer der Prompt.

Seien Sie spezifisch darin, was Sie wollen. Nicht „fix den Bug”, sondern „der TTS-Cache-Schlüssel enthält nicht den Provider-Namen, sodass beim Wechsel von ElevenLabs zu Google gecachtes ElevenLabs-Audio abgespielt wird, anstatt neues Audio zu generieren.”

Liefern Sie Kontext, den die KI nicht hat. Die KI kann Ihren Code lesen, aber nicht Ihre Gedanken. „Der Nutzer hat gemeldet, dass die Koordinaten auf dem Brett verkehrt herum sind” ist weniger nützlich als „das CSS in chessgroundBaseOverride.css hat Reihen und Linien vertauscht — Franciscos Original hatte sie verkehrt herum.”

Nennen Sie Ihre Einschränkungen. „Keine neuen Dateien erstellen” oder „das bestehende Atom-Muster verwenden” oder „das muss ohne API-Schlüssel funktionieren” zeigen der KI, wo die Leitplanken sind.

Sagen Sie, was Sie nicht wollen. „Keine Fehlerbehandlung für Fälle hinzufügen, die nicht eintreten können” oder „den umgebenden Code nicht refactoren” verhindert Über-Engineering — der häufigste KI-Fehlermodus.

Das Muster ist: Absicht + Kontext + Einschränkungen. Wer das beherrscht, für den wird die KI dramatisch nützlicher.

Plan-Modus: Eine Claude nutzen, um eine andere zu prompten

Claude Code hat einen „Plan-Modus”, der Denken vom Handeln trennt. Im Plan-Modus liest die KI Dateien, erkundet die Codebasis und erstellt einen Plan — schreibt aber keinen Code. Sie überprüfen den Plan, passen ihn an und wechseln dann in den Implementierungsmodus, in dem die KI ausführt.

Warum funktioniert das? Weil der schwierigste Teil jeder Programmieraufgabe nicht das Schreiben des Codes ist. Es geht darum herauszufinden, welchen Code man schreiben soll — welche Dateien zu ändern sind, welche Muster zu befolgen sind, welche Randfälle existieren. Der Plan-Modus widmet dieser Frage die volle Aufmerksamkeit, bevor eine einzige Zeile geschrieben wird.

Ein Beispiel aus diesem Projekt: Als wir das Hilfe-Menü umstrukturierten, um den Sprachselektor hinzuzufügen, erkundete das Plan-Modus-Gespräch, wie Tauri-Menüs funktionieren, welche Atoms bereits existierten, wie der Doc-Viewer Ressourcenpfade auflöste und wie die Bestätigungsdialog-API aussah. Als wir in die Implementierung wechselten, hatte die KI eine vollständige Karte der Änderungen. Keine Fehlstarts.

Im Grunde nutzen Sie eine Instanz der KI als Senior-Architekten und eine andere als Entwickler. Dasselbe Modell, unterschiedliche Rollen.

Wie Sitzungen ablaufen

Eine typische Sitzung sieht so aus:

1. Der Mensch äußert seine Absicht. „Caching-Hinweis zum KittenTTS-Abschnitt hinzufügen.” „PostHog-Telemetrie entfernen.” „Die Qualitätsbewertungen sind falsch, hier ist, was sie sein sollten.”

2. Die KI liest die relevanten Dateien. Sie rät nicht, was in einer Datei steht. Sie liest sie, versteht den aktuellen Zustand und schlägt dann Änderungen vor. Mehrere Dateien werden parallel gelesen, wenn sie unabhängig voneinander sind.

3. Die KI nimmt die Änderung vor. Gezielte Bearbeitungen an bestehenden Dateien. Keine Umschreibungen — chirurgische Modifikationen, die alles Drumherum bewahren.

4. Der Mensch prüft. Jede Bearbeitung wird angezeigt, bevor sie auf die Festplatte geschrieben wird. Der Mensch genehmigt, lehnt ab oder lenkt um. „Nein, das ist zu zahm — sag, dass es wirklich mies ist.” „Verschieb den Absatz nach oben.” „Das ist nicht, was ich gemeint habe.”

5. Committen auf Anweisung. Die KI committet nie von sich aus. Der Mensch sagt „commit” oder „commit and push.” Commits enthalten Co-Authored-By: Claude Opus 4.6 — immer zugeordnet, nie versteckt.

Kontextfenster und Speicherstände

Jedes KI-Gespräch hat ein Kontextfenster — die Gesamtmenge an Text, die es gleichzeitig im Speicher halten kann. Wenn das Gespräch lang genug wird, werden ältere Nachrichten komprimiert, um Platz zu schaffen.

Zwei Strategien: Gespräche fokussiert halten (eine Aufgabe pro Gespräch) und Speicherstände nutzen (Claude Code speichert Transkripte als JSONL-Dateien, von denen Sie mit vollständig wiederhergestelltem Kontext fortfahren können). Die Speicherdatei dient einem anderen Zweck — sie ist eine persistente Wissensbasis, die über alle Gespräche hinweg bestehen bleibt.

Was die KI vorschlägt vs. was ausgeliefert wird

Der erste Vorschlag der KI ist selten die endgültige Version. Ein typischer Austausch:

• KI entwirft etwas Vernünftiges
• Mensch sagt „zu Corporate” oder „sei direkter” oder „das ist falsch, hier ist der Grund”
• KI passt an
• Mensch genehmigt

Geschmack, Tonfall und die finale Entscheidung sind immer menschlich. Die KI liefert Geschwindigkeit — Dateien lesen, Kontext verstehen, präzise Bearbeitungen über eine Codebasis hinweg, die sie im Speicher halten kann. Der Mensch liefert Urteilsvermögen — was gebaut werden soll, wie es sich anfühlen soll, wann Schluss ist.

Skills und Slash-Befehle

Claude Code unterstützt „Skills” — wiederverwendbare Prompts, die als Markdown-Dateien im Verzeichnis .claude/commands/ gespeichert sind. Man ruft sie mit einem Slash-Befehl auf, wie /translate-docs.

Dieses Projekt verwendet einen /translate-docs-Skill, der das Übersetzen der Dokumentation in mehrere Sprachen automatisiert. Die Skill-Datei enthält die vollständigen Anweisungen: welche Dateien zu übersetzen sind, welches Format zu verwenden ist, wie mit Codeblöcken und Links umzugehen ist, welcher Ton beizubehalten ist. Anstatt das alles jedes Mal zu erklären, tippt man einfach /translate-docs und die KI weiß genau, was zu tun ist.

Skills kodieren Prozesse, nicht nur Informationen. Man kann sie für jeden wiederkehrenden Workflow erstellen: Tests ausführen, deployen, PRs reviewen, Changelogs aktualisieren.

Coding-Prinzipien

Das vollständige Prinzipiendokument befindet sich im Repository unter .claude/01_UNIVERSAL_PRINCIPLES.md. Es begann als Robert C. Martins Clean Code (2008) plus Ergänzungen für das KI-Zeitalter. Dann hatten wir ein ehrliches Gespräch darüber, was noch Bestand hat und was nicht.

Was zeitlos ist

• Absichtsoffenbarende Namen. Immer. Für immer.
• Funktionen tun eine Sache. Das eigentliche Prinzip ist Kohärenz, nicht Größe.
• Keine Seiteneffekte. Immer noch die Ursache der meisten Bugs.
• Kommentare erklären das Warum, nicht das Was.
• Single Responsibility. Ein Modul sollte nur einen Grund haben, sich zu ändern.
• Gegen Interfaces programmieren, nicht gegen Implementierungen.
• Fehler nicht verschlucken. Jeder Fehler ist eine Information.
• Emergentes Design: Alle Tests bestehen, keine Duplikation, drückt Absicht aus, minimiert Komplexität. In dieser Reihenfolge.

Was kontextabhängig ist

Diese Prinzipien sind fundiert, aber die spezifischen Regeln spiegeln eine Vor-KI- oder sprachspezifische Welt wider. Wir wenden den Geist an, nicht den Buchstaben:

• DRY. Duplikation, die auseinanderdriftet, ist gefährlich. Aber jedes wiederholte Muster in eine Abstraktion zu extrahieren, erzeugt Indirektion, die schlimmer sein kann. Manchmal sind drei lesbare Zeilen genau hier besser als eine voreilige Abstraktion in einer anderen Datei.
• Strikte TDD-Zeremonie. Das Prinzip — getesteten Code ausliefern, wissen, dass er funktioniert — ist nicht verhandelbar. Die Zeremonie — der Test muss vor dem Code existieren — wurde für einen Workflow entworfen, in dem Menschen langsam tippen. Schreiben Sie Tests. Stellen Sie sicher, dass sie bestehen. Ob der Test oder der Code zuerst kam, ist weniger wichtig als die Frage, ob beide existieren.
• Die Pfadfinder-Regel. „Den Campingplatz sauberer hinterlassen” — ja. Aber der Pfadfinder hat den Campingplatz aufgeräumt, nicht den ganzen Wald. Reparieren Sie, was Sie anfassen. Refactoren Sie nicht die gesamte Struktur einer Datei, nur weil Sie eine Zeile darin geändert haben.

Ergänzungen für das KI-Zeitalter

• Prinzipienbasierte Orientierung skaliert besser als Regeln. Das Prinzip erlaubt Urteilsvermögen; die Regel ist spröde.
• Wenn der Agent es baut, kann der Agent es warten. Gesprächskontext und Artefakte bewahren. Den Build-Prozess dokumentieren, nicht nur das Ergebnis.
• Klar statt clever. Das System, das dies gebaut hat, muss die Denkweise rekonstruieren und korrekt modifizieren können. Explizite Struktur schlägt kleine clevere Abstraktionen.
• Könnte dies zu Infrastruktur werden? Ein Tool löst ein Problem für Sie. Infrastruktur ermöglicht anderen, darauf aufzubauen. Entwerfen Sie entsprechend.

Wo der Mensch die Grenze zieht

Die KI ist ein Werkzeug. Ein bemerkenswert gutes. Aber es gibt Dinge, die sie nicht tut:

• Produktentscheidungen. Welche Features gebaut, was gestrichen wird, wie sich die App anfühlen soll. „Die System-TTS-Qualitätsbewertung sollte ‚passabel’ sagen, weil sie wirklich mies ist” — das ist eine menschliche Einschätzung, die auf tatsächlichem Zuhören basiert.
• Geschmack. Die KI kann saubere Prosa schreiben, aber die Stimme des Projekts, die Entscheidung, bei der Qualität ehrlich zu sein, die Wahl, Francisco prominent zu würdigen — das sind menschliche Entscheidungen.
• Ethik. PostHog zu entfernen war keine Refactoring-Aufgabe. Es war: „Die Einstellungsseite sagt, wir sammeln keine Telemetrie, aber es gibt einen aktiven PostHog-API-Schlüssel im Code. Das ist eine Lüge. Beheb das.” Die KI hat ausgeführt. Der Mensch hat das Problem erkannt und es für wichtig befunden.
• Schach. Dem Brett ist Ihr Tooling egal.

Warum wir das teilen

Weil „mit KI gebaut” bedeutungslos geworden ist. Jeder sagt es. Niemand zeigt es. Die interessante Frage ist nicht, ob KI beteiligt war — sondern wie sie beteiligt war und was der Mensch tatsächlich beigetragen hat.

Dies ist die Antwort. Der Mensch bringt die Vision, den Geschmack, das Urteilsvermögen und die Verantwortung. Die KI bringt die Geschwindigkeit, das Gedächtnis und die unermüdliche Bereitschaft, Rust-Fehlermeldungen um 2 Uhr morgens zu lesen.

Keiner baut dieses Ding allein. Beide werden gewürdigt. Das ist der Deal.

---

En Parlant~ ist ein Fork von En Croissant von Francisco Salgueiro, gebaut mit Claude Code von Anthropic.