Vor drei Tagen habe ich einen Post über Drift-Prevention veröffentlicht. Pattern erklärt: Source of Truth identifizieren, generierendes Tool dranhängen, Hook setzen, fertig. Drei Tage später bin ich selbst exakt in diese Falle gelaufen.
Eine andere Doku angeschaut. Fünf Wochen nicht gepflegt. Dreizehn falsche oder fehlende Einträge. Ein Pfad zeigte auf ein Verzeichnis, das nie existiert hat. Audit-Agents zogen aus diesen Lügen ihre Schlüsse. Reviews waren unbrauchbar geworden.
Das ist der Lehrstoff. Ich gebe ihn ungefiltert weiter — weil das, was ich daraus mitnehme, vielleicht spart, was es mich gekostet hat.
Drift ist kein Disziplin-Problem, sondern ein Struktur-Problem
Die erste Reaktion auf so einen Fund ist immer dieselbe: Ich hätte besser aufpassen müssen. Falsche Diagnose.
Disziplin ist ein verbrauchsbares Gut. Nach einer Woche hektischer Sprints reicht sie für das Produkt, nicht mehr für die Hygiene. Nach drei Wochen reicht sie nicht mal mehr für die Hygiene-Erinnerungen. Wer behauptet, er pflege Doku konsequent über Monate hinweg manuell, lügt oder hat sehr wenig zu tun.
Merke: Wenn dein Pattern Disziplin braucht, hast du es nicht implementiert. Du hast es nur dokumentiert.
Best Practices, die auf “ich denk schon dran” basieren, sind Theater. Sie funktionieren in der Woche, in der du sie aufschreibst. Danach verfallen sie linear mit deiner Aufmerksamkeit. Das ist keine Schwäche — das ist die Grundkonstante jedes Menschen, der mehr als ein Projekt gleichzeitig betreibt.
Die Lösung ist nicht mehr Disziplin. Die Lösung ist eine Struktur, die den Verstoß physisch blockiert.
Anatomie einer typischen Drift
Damit du das Muster im eigenen Setup erkennst, hier die typische Verlaufskurve:
Woche 1: Du legst eine Doku an. Inhalte stimmen. Du fühlst dich gut.
Woche 2: Drei kleine Änderungen am System. Doku nicht angepasst — du wolltest “gleich noch” aktualisieren. Du tust es nicht.
Woche 3-5: Sprint. Hektik. Niemand schaut in die Doku, weil alle wissen, wo die Wahrheit gerade lebt. Die Doku verrottet still.
Woche 6: Jemand neuer (Mitarbeiter, Agent, du selbst nach Urlaub) liest die Doku, glaubt sie, handelt danach. Falsche Pfade. Falsche Befehle. Tickets entstehen, die es gar nicht geben dürfte.
In meinem Fall: fünf Wochen Drift. Sechs Einträge zeigten auf Dinge, die längst entfernt waren. Sieben echte Einträge fehlten komplett, weil sie in dieser Zeit dazugekommen waren. Pfade in der Doku zeigten auf ein Verzeichnis, das es nie gab — irgendwann mal versehentlich falsch reingeschrieben, nie gemerkt.
Das ist nicht selten. Das ist der Normalzustand jeder Doku, die du nicht aktiv vor dem Verrotten schützt.
Die drei Schichten gegen Drift
Sauberes Anti-Drift-Pattern besteht aus drei Schichten. Eine allein reicht nicht. Alle drei zusammen machen das Verstoßen praktisch unmöglich.
Schicht eins: Source of Truth identifizieren. Frag bei jedem neuen Manifest, jeder Inventory-Liste, jeder Übersichts-Doku: Gibt es schon eine Datei, in der dieselbe Information deterministisch berechnet werden kann? Wenn ja — die ist die Wahrheit. Das neue File ist abgeleitet, nie originär. Wenn du das nicht klar trennst, hast du am Ende zwei Wahrheiten, und eine driftet.
Schicht zwei: Generierungs-Tool. Abgeleitete Doku wird durch ein deterministisches Skript regeneriert — kein AI, keine Zufallszahlen, keine LLM-Calls. Zweimal laufen lassen ergibt denselben Output. Aus identischem Input identischer Output. Dazu ein automatisierter Test, der das Tool aufruft und den Output gegen die committete Datei diff’d. Diff muss leer sein, sonst fällt der Test.
Schicht drei: Pre-Commit-Hook. Der Hook prüft bei jedem Commit: Hat sich die Source of Truth geändert? Ist die abgeleitete Doku entsprechend mit-regeneriert? Wenn nein — Commit wird abgelehnt mit klarer Anweisung.
Jede Schicht für sich ist hilfreich. Erst alle drei zusammen ergeben Härte.
Rat: Wenn du eine der Schichten weglässt, weißt du genau, welche Drift dich später erwischt — die, die durch das Loch fällt, das du gelassen hast.
Warum fail-with-instruction besser ist als auto-stage
An dieser Stelle steht jeder vor einer Designentscheidung. Soll der Hook die abgeleitete Doku selbst regenerieren und mit-committen (auto-stage)? Oder soll er nur fehlschlagen und sagen, was zu tun ist (fail-with-instruction)?
Auto-stage ist bequemer. Du änderst die Source of Truth, der Hook merkt es, regeneriert, fügt zum Commit hinzu, fertig. Klingt elegant.
Ist aber falsch.
Auto-stage erzeugt Beifang im Commit. Du wolltest eine Sache committen, plötzlich hängen drei Files mit dran, die du nicht aktiv ausgewählt hast. Das untergräbt jeden ernsthaften Code-Review und jede saubere Commit-Hygiene. Du verlierst die Kontrolle darüber, was in deinen Commits steht — und das ist das Letzte, was du verlieren willst.
Fail-with-instruction macht es so:
ERROR: Source of Truth wurde geändert, abgeleitete Doku ist nicht aktualisiert.
Fix: führe das Generierungs-Tool aus, füge die abgeleitete Datei zum Commit hinzu, committe erneut.
Du bleibst der Fahrer. Der Hook erinnert dich, was du tun musst, blockiert den falschen Commit, lässt dich aber den richtigen selbst zusammenstellen.
Merke: Hooks ersetzen nicht deine Entscheidungen. Sie verhindern nur, dass du sie aus Versehen umgehst.
Der heimliche Saboteur: Mirror-Sync vs. Versionskontrolle
Hier kommt eine Falle, in die ich beim Aufräumen fast getappt wäre — und die in praktisch jedem Setup lauert, das nicht trivial einfach ist.
Du hast oft zwei Welten: eine, in der Versionskontrolle lebt (Git, Repositories, Commits, Diffs), und eine, in der Mirror-Sync lebt (iCloud, Syncthing, Dropbox, OneDrive). Die eine Welt pflegt Geschichte und kleine Diff-fähige Artefakte. Die andere spiegelt große Verzeichnisse zwischen Geräten.
Wenn du diese Welten nicht sauber trennst, hast du am Ende einen Symlink zwischen einem Git-Verzeichnis und einem 274-Megabyte-Mirror-Pfad. Beide Sync-Mechanismen kämpfen gegeneinander. Wer zuerst schreibt, gewinnt. Wer zuletzt liest, ist verwirrt.
Die saubere Regel:
- Kleine, kuratierte Manifeste (Listen, Inventories, Konfigurations-Summaries) gehören in die Versionskontrolle. Klein, versioniert, Diff-fähig, Review-fähig.
- Große, lebende Verzeichnisse (Projekte, Arbeitsordner, Asset-Sammlungen) gehören in den Mirror-Sync. Groß, ohne Git, ohne Diff-Anspruch.
- Wenn die zwei Welten auf demselben Server zusammentreffen, brauchst du einen Deploy-Schritt — etwa ein Hook, der nach dem Pullen die Manifeste in die Mirror-Welt kopiert (per Copy, nicht per Symlink, nicht per Delete-Sync).
Achtung: Bevor du irgendeinen Sync zwischen zwei Pfaden einrichtest — prüfe, welche Mechanismen schon auf dem Ziel-Pfad laufen. Ein zweiter Sync auf demselben Pfad ist fast immer eine Falle.
Wiederholung ist Pflicht, kein Eingeständnis
Jetzt der unbequeme Teil. Ich habe dieses Pattern in der vergangenen Woche dreimal erklärt — einmal als Post, einmal als interne Doku, einmal in einer Konversation. Trotzdem reingelaufen.
Das ist normal. Und es ist kein Disziplinversagen.
Eine Lektion einmal zu lesen sichert sie nicht. Auch zweimal nicht. Eine Lektion sitzt erst nach drei bis fünf Wiederholungen plus einem eigenen Stolpern — also einem Moment, in dem du selbst genau den Fehler machst, vor dem du gewarnt wirst. Das Stolpern ist der Klebstoff. Ohne eigenen Schmerz bleibt das Wissen abstrakt.
Deshalb wiederhole ich dieselben Patterns immer wieder. Nicht weil ich nichts Neues weiß, sondern weil ich weiß, dass Wiederholung der einzige Weg ist, wie ein Pattern aus dem Kopfwissen ins Reflexwissen wandert.
Wenn du jemanden hörst, der dasselbe Pattern zum dritten Mal erklärt — sei nicht genervt. Das ist die Person, bei der das Pattern beim nächsten Sprint nicht verfällt.
Wichtig: Wiederholung ist kein Eingeständnis von Schwäche. Sie ist der Mechanismus, durch den abstraktes Wissen zu robustem Verhalten wird.
Checkliste für dein nächstes Inventory
Wenn du das nächste Mal ein Manifest, eine Übersichts-Doku oder ein Inventory anlegst, geh diese sechs Punkte durch. Sie sind aus eigenem Schmerz destilliert.
- Source of Truth identifizieren. Gibt es schon eine Datei, aus der diese Information deterministisch ableitbar ist? Wenn ja — die ist die Wahrheit. Dein neues File ist abgeleitet.
- Generierungs-Tool schreiben. Ein Skript, das aus der Source of Truth die abgeleitete Doku produziert. Idempotent. Deterministisch. Kein AI. Kein Zufall.
- Drift-Test einrichten. Ein automatisierter Test, der das Tool aufruft und den Output gegen die committete Datei diff’d. Diff leer = grün. Diff nicht leer = rot.
- Pre-Commit-Hook setzen. Bei Änderung an der Source of Truth muss das Tool gelaufen sein. Sonst fail-with-instruction.
- Override-Pattern definieren. Für bewusste Ausnahmen eine benannte Umgebungsvariable (nicht den generischen no-verify-Schalter). Sichtbar im Befehl, dokumentiert, mit erwarteter Begründung im Commit-Body.
- Doku zeigt aufs Tool. Die Anleitung “Wie ergänze ich einen Eintrag?” zeigt auf das Generierungs-Tool, nie auf manuelles Editieren. Wer manuell editiert, hat den Punkt nicht verstanden.
Sechs Punkte. Setup-Aufwand pro Pattern: zwei bis vier Stunden, je nach Komplexität. ROI: jedes Mal, wenn dein nächster Sprint hektisch wird und du nicht mehr aufpassen musst.
Das ist der ehrlichste Trade, den ich kenne. Wenige Stunden jetzt gegen unbegrenzt viele Stolpermomente in Zukunft.
Fazit
Wissen über ein Pattern verhindert nicht, dass du dagegen verstößt. Das ist die zentrale Lehre aus diesem Stolpern. Disziplin verfällt, Aufmerksamkeit schwankt, Sprints werden hektisch. Was bleibt, ist die Struktur, die du dem Pattern gegeben hast — oder nicht gegeben hast.
Source of Truth, Tool, Hook. Drei Schichten. Setup-Aufwand übersichtlich. Wirkung dauerhaft.
Und wenn du dich beim nächsten Stolpern fragst, warum du es schon wieder getan hast: Du hast es nicht falsch verstanden. Du hast es nur nicht gehärtet.
Welche Doku in deinem Setup hat als letztes Update-Datum „vor X Wochen”? Genau die ist gerade dabei zu driften.
Dr. Ronald Kandelhard schreibt über KI-Workflows, Recht und das praktische Härten von Prozessen für Solopreneure und kleine Teams. Mehr unter evolutionki.de — von Staunen zu Starten.