Deterministische CLIs

Diesen Beitrag anhören (11 Min.)

Zwei Läufe, dieselben Eingabedateien, zwei verschiedene Reports. Der Unterschied besteht aus einem Zeitstempel im Kopf und einer Tabelle, deren Zeilen diesmal in anderer Reihenfolge stehen. Fachlich hat sich nichts geändert, aber der Diff zeigt hundert Zeilen an, und keine davon bedeutet etwas. Also liest der Reviewer den ganzen Report noch einmal. Beim nächsten Mal liest er ihn gar nicht mehr.

Ein deterministisches CLI dreht diese Lage um: Was im Diff auftaucht, hat sich auch fachlich geändert. Byte für Byte. Das klingt nach einem Implementierungsdetail, ist in Wirklichkeit aber eine Entscheidung über Systemgrenzen.

Determinismus wird meist als Nebeneffekt behandelt, den man „auch noch“ mitnimmt. In Wahrheit ist er die Voraussetzung dafür, dass ein Ergebnis reviewbar wird. Und Reviewbarkeit ist die Währung, in der digitale Produktentwicklung tatsächlich bezahlt: Was ich nicht vergleichen kann, kann ich nicht freigeben, nicht widerlegen und nicht mit gutem Gewissen automatisieren.

Warum Determinismus ein Architektur-Hebel ist

Der Reflex ist, Determinismus als Eigenschaft der Ausgabe zu sehen. Ich sehe ihn als Eigenschaft der Systemgrenze. Ein CLI, das reproduzierbar arbeitet, zwingt mich, jede Quelle von Nichtdeterminismus explizit zu machen: Zeitstempel, Zufallszahlen, unsortierte Maps, Netzwerkantworten, OCR-Ergebnisse, Modell-Outputs. Jede dieser Quellen muss ich entweder einfrieren, sortieren, cachen oder aus dem Ergebnis heraushalten.

Genau diese Übung ist wertvoll, unabhängig vom Werkzeug. Wer Nichtdeterminismus benennt, hat die Zustands- und Abhängigkeitsgrenzen eines Systems schon halb dokumentiert. Die Frage „warum ist dieser Lauf nicht reproduzierbar?“ ist fast immer dieselbe wie „welcher Teil meines Systems ist verstecktes, ungezähmtes Ich-weiß-nicht?“.

Der Business-Outcome ist konkret. Ein deterministischer Report lässt sich per diff reviewen. Ein Reviewer sieht in Sekunden, was sich zwischen zwei Läufen geändert hat, statt eine ganze Ausgabe erneut zu lesen. Das verkürzt den Feedback-Zyklus von „ich lese das komplett neu“ auf „ich schaue mir die drei geänderten Zeilen an“. In Teams, die täglich solche Reports produzieren, ist das der Unterschied zwischen Reibung und Fluss.

Das Kostenmodell – Determinismus ist nicht gratis

Determinismus hat einen Preis. Wer ihn verschweigt, liefert eine Werbebotschaft statt einer Abwägung.

Man zahlt in expliziter Zustandskontrolle. Zeit muss injiziert statt gelesen werden. Zufall braucht einen Seed. Externe Sensoren – OCR, HTTP, ein Modell – brauchen einen Cache, damit ein zweiter Lauf dasselbe sieht wie der erste. Sortierung wird zur Pflicht, nicht zur Kür, weil sonst die Reihenfolge einer Hash-Map den Report verändert. Das ist zusätzliche Arbeit, und bei kleinen Wegwerf-Skripten lohnt sie sich oft nicht.

Der Gegenwert ist Reviewbarkeit, Auditierbarkeit und Testbarkeit in einem. Ein deterministischer Report ist automatisch ein Golden-Master-Test: Ich checke einen erwarteten Report ein und lasse die CI gegen ihn diffen. Ich brauche keine gesonderte Assertion-Wüste, das Artefakt selbst ist der Test. Die Kosten fallen einmalig an, die Wirkung wiederholt sich bei jedem Lauf. Genau deshalb setze ich Determinismus dort ein, wo etwas oft läuft und oft geprüft wird – und lasse ihn dort weg, wo ein Skript einmal etwas kippt und dann verschwindet.

Diese Abwägung ist die eigentliche Ingenieursleistung, nicht die Implementierung. Ich habe schon Teams gesehen, die jedes Skript deterministisch zwingen wollten und über Seed-Injektion in Wegwerf-Tools stolperten. Und ich habe das Gegenteil gesehen: einen täglichen Report, den niemand mehr las, weil er bei jedem Lauf anders aussah und ein Review Stunden gekostet hätte. Die Grenze verläuft nicht zwischen „immer“ und „nie“. Sie verläuft an der Frage, ob das Artefakt wiederholt geprüft wird. Wird es das, zahlt sich der Preis um Größenordnungen aus. Wird es das nicht, ist Determinismus Gold-Plating.

Die Grenze vor dem Werkzeug

Vor der Toolwahl kläre ich, welche Daten führend sind, was später nachvollziehbar sein muss und welche Teile unabhängig geändert werden sollen. So kann ich den PDF-Parser tauschen, ohne Matching-Regeln oder Reportformat anzufassen. Determinismus hilft beim letzten Punkt, ersetzt aber keine klare Fachgrenze: Ein reproduzierbarer Report kann auch Unklarheit zuverlässig wiederholen.

Ein konkretes Beispiel – Belege gegen Buchungen matchen

Ich zeige das an einem Inventur-Werkzeug, das ich als Muster immer wieder verwende. Die Aufgabe: ein Kontoblatt über Rechnungsnummern an PDF-Belege koppeln, Inventarpositionen gegen Rechnungspositionen matchen und die Lücken sichtbar machen. Klingt nach Buchhaltung, ist in Wahrheit eine Architekturübung über unsichere Daten.

Drei Design-Entscheidungen tragen das Ganze, und keine davon ist ein Werkzeug.

Die erste ist die Dreistufigkeit: Kontoblatt an Belege koppeln, Positionen matchen, Nicht-PDF-Vendors separat über Buchungstext-Regeln behandeln. Diese Stufen sind wichtiger als jedes Dateiformat. Sie sind die Fachgrenze, an der ich später unabhängig etwas ändern kann.

Die zweite ist die saubere Trennung von hartem Match und Fuzzy-Fallback. Zuerst müssen definierte Tokens im Produkttitel stehen; Fuzzy Matching kommt nur zum Zug, wenn der harte Weg nichts findet. Damit bleibt Automatisierung erklärbar. Ich kann für jede Zeile sagen, warum sie zugeordnet wurde – hart über eine Regel oder weich über eine Ähnlichkeit oberhalb einer Schwelle. Ein Fuzzy-Match, den niemand mehr begründen kann, ist kein Feature – er ist die Fehlersuche von übermorgen.

Die dritte ist die Behandlung von OCR als unsicherer Sensor. Vision liefert die Basis, Tesseract korrigiert gezielt Beträge in der Soll/Haben-Region, ein JSON-Cache macht spätere Läufe reproduzierbar. Der entscheidende Satz: Der erkannte Text ist ein Messwert, keine Wahrheit. Beträge, Namen und Nummern können falsch gelesen werden. Deshalb bekommt diese Schicht Cache, Schwellenwerte, manuelle Alias-Regeln und – das ist der Kern – Diffbarkeit.

Der Report selbst ist dann ein Architekturartefakt, kein Nebenprodukt. Inventarpositionen, Rechnungsnummern, Kaufdatum, Match-Art, verwaiste Kontoeinträge und ungenutzte Rechnungspositionen stehen sichtbar nebeneinander. Genau dadurch wird aus einem Skript ein prüfbares Datensystem: Man sieht nicht nur, was gematcht wurde, sondern auch, was nicht passt – und das ist meist die interessantere Information.

Wie das aufgerufen wird

inventory-correlate \
  --account account.pdf \
  --inventory inventory.pdf \
  --out report.md

# review is just a diff against the last known-good run
diff last-report.md report.md

Das Beispiel ist bewusst klein. Es soll keine vollständige Anwendung simulieren, sondern die Grenze zeigen. Ein gutes Beispiel hat nicht die meisten Features. Es hat die eine Entscheidung, über die man nach fünf Minuten streiten kann. Hier steckt sie im zweiten Aufruf: Weil der Report deterministisch ist, ist der Review ein diff. Kein Dashboard, kein State, kein „lies das nochmal ganz“.

flowchart LR
  PDFs --> Parser
  Parser --> Normalize
  Normalize --> Match["Hard match<br/>then fuzzy fallback"]
  Match --> Report["Deterministic<br/>Markdown report"]
  Report --> Diff["Review via diff"]

Markdown als Audit-Artefakt

Warum Markdown und nicht sofort eine Oberfläche? Weil ein Markdown-Report reviewbar, diffbar und archivierbar ist, ohne dass ich ein Dashboard bauen muss. Bei Datenwerkzeugen ist Diffbarkeit ein starkes Qualitätsmerkmal. Liegt ein Report als Markdown vor, kann eine Änderung im Review gesehen werden – Zeile für Zeile, mit voller Historie im Git. Das ist oft wertvoller als eine Oberfläche, die nur den letzten Zustand zeigt und die Frage „was hat sich geändert?“ gar nicht beantworten kann.

Dasselbe Prinzip trägt weit über Buchhaltung hinaus. Publishing-Werkzeuge können nach demselben Muster arbeiten: Eingabe rein, deterministisches Artefakt raus, Änderungen als Diff sichtbar. Ob ich Belege zuordne oder Präsentationen erzeuge – die Architektur ist identisch, weil das Qualitätsproblem identisch ist: Ich will Änderungen sehen, nicht Zustände raten.

Woran ich den Nutzen prüfe

Ein Diff begrenzt den Review auf die tatsächlich geänderten Zeilen. Ob das Zeit spart, lässt sich an der Review-Dauer eines wiederkehrenden Reports ablesen. Ein erwarteter Report kann außerdem als Golden Master dienen; ein unerwarteter Diff ist dann ein konkretes Prüfsignal. Dafür investiere ich in Caches, Seeds und explizite Sortierung – nicht, weil Determinismus für jedes Skript ein Selbstzweck wäre.

Worauf ich prüfe, bevor ich das produktiv nenne

Eine Idee ist erst belastbar, wenn auch der Fehlerpfad beschrieben ist. Was passiert bei Wiederholung? Was ist idempotent? Wo liegt die Transaktionsgrenze? Welche Logs oder Reports helfen später bei der Analyse? Diese Fragen wirken trocken, sind aber oft der Unterschied zwischen Demo und Betrieb.

Beim deterministischen CLI kommt eine spezifische Frage dazu: Ist der Nichtdeterminismus wirklich eingefangen, oder nur zufällig gerade still? Ein Report, der heute stabil ist, weil die Map zufällig sortiert ausliefert, kippt morgen bei einer anderen Laufzeit. Deshalb erzwinge ich Sortierung explizit, versioniere Caches und behandle manuelle Korrekturen als Daten, nicht als Handgriffe. Fuzzy Matching braucht explizite Schwellen und einen Weg, harte Regeln vorzuziehen – sonst ist das Ergebnis nicht mehr erklärbar. Ein Tool darf unsicher sein, aber es muss seine Unsicherheit zeigen.

Vor einem produktiven Einsatz prüfe ich drei Dinge:

Gleiche Eingaben erzeugen byteweise dasselbe Ergebnis.
Uhrzeit, Zufall, Reihenfolge und externe Antworten sind explizit begrenzt.
Fehler und unsichere Zuordnungen erscheinen im prüfbaren Artefakt.

Typische Fehler

Der erste Fehler ist, das Werkzeug mit der Lösung zu verwechseln. Docker ist keine Architektur. GraphQL ist kein Fachmodell. React ist kein State-Konzept. Ein LLM ist kein Prozess. Diese Werkzeuge können gute Grenzen ausdrücken, aber sie erzeugen sie nicht automatisch. Determinismus ist genauso: Er ist eine Entscheidung über Systemgrenzen, kein Flag, das man setzt.

Der zweite Fehler ist, den glücklichen Pfad zu überbewerten. Viele Systeme sehen im Demo-Modus sauber aus. Interessant wird es bei Wiederholung, Teilfehlern, alten Daten, Netzwerkproblemen, falschen Berechtigungen oder menschlicher Korrektur. Genau dort zeigt sich, ob das Modell trägt – und ob der Report morgen noch denselben Diff liefert wie heute.

Schluss

Ich investiere in Determinismus, wenn ein Ergebnis wiederholt geprüft wird. Dann zeigt der Diff die Änderung, und Caches, Seeds oder explizite Sortierung haben einen konkreten Zweck. Für ein einmaliges Wegwerfskript wäre derselbe Aufwand Gold-Plating.

Weiterführende Quellen

Wie fandest du diesen Beitrag?

Kommentare