Ich committe koreanische Spezifikationen statt Code — PWA-App + Server in 3 Spezifikationsblättern

Beim Programmieren mit AI bin ich immer wieder über ein Problem gestolpert. Der erzeugte Code bleibt zwar erhalten, aber die Gespräche und die Absicht, aus denen dieser Code entstanden ist, gehen verloren. Drei Monate später gibt es niemanden mehr, den man fragen kann: „Warum ist dieser Code eigentlich so geworden?“

Also habe ich die Richtung umgedreht. Ich committe Spezifikationen, die die Absicht enthalten, in git, und behandle den Code als Build-Artefakt. Um das zu überprüfen, habe ich eine kleine App komplett gebaut und veröffentlicht.

Es ist eine PWA namens Rimlog, bei der AI frühere Notizen an Lese- und Lernaufzeichnungen anfügt. Kein Server, keine Registrierung, die Daten liegen nur im Browser.

Die App selbst ist unspektakulär. Was ich teilen möchte, ist die Art, wie sie gebaut wurde.

Vorgehensweise

Im Ordner eux/ des Repos liegen drei koreanische Spezifikationsblätter. Das gesamte App-Gerüst umfasst 40 Zeilen, das AI-Karten-Widget 25 Zeilen, und für den Insight-Server gibt es ein Blatt. Sie bestehen aus Sätzen wie diesem.

saveCapture : Erfasst das Capture-Formular (Quellenname · Zitat · meine Gedanken · Tags) — fügt es am Anfang von captures ein + spiegelt es im Local Storage wider + zeigt den Toast „Gespeichert“ an + wechselt zum Tab „Verlauf“.

Wenn man diese Dateien in ein Tool namens EstreUX gibt, entsteht daraus Code (ich nenne das brew). Der generierte Code enthält den Hash der Spezifikation, und wenn man nur die Spezifikation oder nur den Code ändert, blockiert ein pre-commit den Commit. So wird per Gate verhindert, dass die Spezifikation in dem Moment zur Lüge wird, in dem sie veraltet.

Ich habe auch Zahlen gemessen. Anhand eines im Framework ursprünglich vorhandenen 152-zeiligen Zahlen-Keypads, das in eine 28-zeilige Spezifikation zurückgeführt wurde, ergab die Messung, dass sich die von Menschen gepflegte Zeilenzahl um 60–82 % verringert hat. Der generierte Code selbst kann länger werden als das Original. Reduziert wird der Teil, den Menschen lesen und ändern. Die Messaufzeichnungen liegen im Repo.

Auch der Server ist nur ein Spezifikationsblatt

Die Pages-Demo ist serverlos, daher hilft die AI dort nur mit einem Tag-Overlap-Fallback. Damit es richtig läuft, habe ich einen selbst gehosteten Server ergänzt; auch dieser ist eine mit brew aus einem einzigen Spezifikationsblatt erzeugte Node-Einzeldatei ohne Abhängigkeiten. Das Backend kann ausgewählt werden.

• nvidia (Standard): die kostenlose API von build.nvidia.com. Man bekommt einen Key ohne Kartenregistrierung, und mit rund 40 Aufrufen pro Minute bei OpenAI-Kompatibilität ist das für ein persönliches Journal mehr als ausreichend
• claude-cli / codex-cli: Pro Anfrage wird claude -p bzw. codex exec als Child-Prozess aufgerufen. Das ist ein Weg, bereits bezahlte Claude-/ChatGPT-Abos ohne API-Key weiterzuverwenden
• openai / google: einfacher Key-Proxy

Keys und Authentifizierung bleiben ausschließlich auf dem Server und gelangen nicht in den Browser.

Punkte, bei denen ich noch nicht sicher bin

Ich erweitere die Beurteilung der Spezifikation↔Code-Konsistenz derzeit über statische Diffs hinaus um Property-basierte dynamische Prüfungen, aber bei der Gewichtung fehlt noch das Calibration-Tuning. Außerdem habe ich eine Klasse von False Positives entdeckt, bei der Framework-Rendering in einer headless-DOM-Umgebung anders läuft als im echten Browser; daher steht auch noch aus, die Verifizierungsumgebung auf einen realen Browser hochzustufen. Wenn man sich die Commit-Historie von Anfang an ansieht, bleibt der Ablauf Scaffold → Spezifikation → Generierung → Nachbearbeitung der Reihe nach erhalten.

• Live: https://soliestre.github.io/Rimlog/
• Repo: https://github.com/SoliEstre/Rimlog
• Build-Protokoll (detailliert): https://estreui.tistory.com/5

Mich interessieren zwei Dinge. Wo seht ihr die Fallstricke darin, die Spezifikation als SSoT zu verwenden? Mich würde besonders interessieren, an welchen Stellen ihr erlebt habt, dass die Ausdruckskraft der Spezifikation dem Code nicht mehr folgen kann. Und gibt es bei der Wiederverwendung eines Abos über claude -p als App-Backend etwas, das im realen Einsatz problematisch werden könnte (im Hinblick auf Rate Limits, Nutzungsbedingungen oder Latenz)?