Ende August habe ich angefangen, mein Wissen in ein Git-Repository zu schreiben. Nicht, weil ich meine Notizen nicht wiederfand. Sondern weil ich es leid war, bei jedem neuen Problem dieselbe Vorgeschichte zu erzählen: welche Systeme ich betreibe, wie meine Projekte heißen, was ich vor drei Wochen entschieden habe und warum.
Die verbreitete Antwort auf dieses Problem ist ein besserer Prompt oder ein größeres Kontextfenster. Beides geht am Engpass vorbei. Der Engpass ist nicht, wie viel ein Modell auf einmal lesen kann. Der Engpass ist, was überhaupt in einer Form vorliegt, aus der es lesen kann, bevor Sie die Frage stellen.
Neun Tage später besteht das System aus 334 Markdown-Dateien. Neun Automatisierungen schreiben hinein, ohne dass ich sie anstoße, und ein Grafana-Dashboard sagt mir, wenn eine davon aufhört. Was folgt, ist was sich gehalten hat, was nicht, und welcher Teil davon für ein Team gilt und nicht nur für eine Person.
Das Problem war nicht Vergessen, sondern Wiederholung
Mein Wissen lag dort, wo es bei den meisten liegt: in Mails, in Chatverläufen, in einem Dokumentenarchiv, in einzelnen Projekt-Repositories und zu einem unangenehm großen Teil im Kopf. Das war lange kein Problem, weil ich der einzige Leser war und weil ich weiß, wo ich suche.
Zum Problem wurde es, als ein Agent anfing, ernsthaft mitzuarbeiten. Jede Sitzung begann bei null. Ich erklärte, dass es zwei Marken gibt und wofür jede steht. Ich erklärte, welcher Server was betreibt. Ich erklärte eine Entscheidung, die ich getroffen hatte, weil sonst wieder die Variante vorgeschlagen wurde, die ich schon verworfen hatte.
Das Teure daran war nicht das Tippen. Das Teure war, dass jede Antwort auf einer Zusammenfassung beruhte, die ich in dem Moment aus dem Gedächtnis gebaut hatte. Sie war jedes Mal ein bisschen anders und jedes Mal ein bisschen unvollständig. Der Agent war nicht schlecht. Er arbeitete nur auf einer Quelle, die es nicht gab.
Die entscheidende Verschiebung war deshalb keine über Ablage. Sie war die Frage, was ein Modell lesen können muss, bevor es antwortet. Alles andere folgt daraus.
Warum Markdown und Git und nichts Klügeres
Die Gründungsentscheidung ist vom 31. August und steht als Entscheidungsprotokoll im Repository selbst: einfache Markdown-Dateien in einem Git-Repository sind die einzige gültige Quelle. Drei naheliegende Alternativen habe ich dabei verworfen, und die Begründungen sind wichtiger als die Wahl.
Ein Obsidian-Vault als Basis. Verworfen wegen Werkzeugbindung. Sobald Datenbankfunktionen und Plugins die Struktur tragen, kann nur noch dieses Programm die Struktur lesen. Als Betrachter und Editor ist Obsidian weiter nützlich, das Repository funktioniert damit, aber es hängt nicht daran.
Das Gedächtnis der Modelle selbst. Jeder Anbieter hat inzwischen eine eigene Erinnerungsfunktion. Verworfen, weil sie fragmentiert, undurchsichtig und nicht portierbar ist. Ich sehe nicht, was gespeichert wurde, ich kann es nicht versionieren und ich bekomme es nicht heraus. Als flüchtiger Zwischenspeicher ist das in Ordnung, als Quelle der Wahrheit nicht.
Eine Datenbank. Verworfen, weil sie bei dieser Größenordnung nichts gewinnt und zwei Dinge verliert: Lesbarkeit für Menschen und eine brauchbare Historie. Eine Zeile in einer Tabelle sagt nicht, warum sie sich geändert hat. Ein Git-Diff sagt es.
Was Markdown und Git dagegen liefern, ist unspektakulär und genau deshalb tragfähig. Jeder Agent, der Dateien lesen kann, bedient das System. Git liefert Historie, Abgleich über mehrere Geräte, ein Prüfprotokoll und das Sicherheitsnetz, das autonomes Umbauen überhaupt vertretbar macht.
Die Betriebsanleitung ist selbst eine Datei. AGENTS.md beschreibt modellneutral, wie gelesen, geschrieben und entschieden wird; die Datei für Claude Code importiert sie nur. Fünfzehn Skills sind dünne Hüllen über sechzehn Arbeitsabläufen, die ebenfalls modellneutral geschrieben sind. Ein anderes Modell folgt denselben Dokumenten direkt. Das ist kein Purismus, sondern eine Wette darauf, dass ich in zwei Jahren ein anderes Werkzeug benutze als heute.
Gebaut für einen Leser, der eine Maschine ist
Oben liegen zehn nummerierte Verzeichnisse, grob danach geordnet, wo ein Agent zuerst nachsehen soll: die Steuerebene mit Architektur, Prinzipien, Indizes und Vorlagen, ein Posteingang, das Journal, Projekte, Dauerthemen, Personen, Wissen, Entscheidungen, Material von außen und das Archiv.
Wichtiger als der Baum ist die Lesereihenfolge, und die steht als Regel in der Betriebsanleitung: niemals alles laden. Erst die Datei mit dem aktuellen Fokus, dann die Indizes, dann die eine zuständige Datei, dann was daran hängt, und das Journal nur, wenn die Frage die Vergangenheit betrifft. Wer eine Retrieval-Strategie baut, kennt die Bewegung; hier ist sie nur in Verzeichnissen statt in einem Index formuliert.
Eine einzige Beobachtung hat den Entwurf danach stärker verändert als jede Strukturüberlegung: Ich lese diese Dateien nicht. Ich frage ein Modell, das darin sucht. Als mich der Agent fragte, welche von drei Aufgabenlisten ich tatsächlich öffne, war die ehrliche Antwort: keine.
Daraus folgen drei Dinge, die dem widersprechen, was in den meisten Ratgebern steht.
Doppelte Ablage ist der teuerste Fehler. Zwei Kopien einer Aussage driften auseinander, und keine trägt ein Kennzeichen, welche gilt. Ein Modell beantwortet dieselbe Frage dann je nach geladener Datei verschieden, und zwar beide Male überzeugend. Eine lange kanonische Datei ist besser als zwei kurze.
Umfang ist erlaubt, Redundanz nicht. Eine Größenwarnung ist ein Anlass zu prüfen, kein Auftrag zu kürzen. Was hinter einem Verweis einmal vollständig steht, darf ausführlich sein.
Auffindbarkeit schlägt Schönheit. Sprechende Überschriften und eindeutige Anker zahlen sich aus. Ein hübscher, flacher Verzeichnisbaum zahlt sich nicht aus, wenn niemand ihn ansieht.
Der Posteingang, den niemand benutzt
Jede Anleitung zu persönlichen Wissenssystemen beginnt gleich: erst alles einsammeln, später sortieren. Der Posteingang ist die zentrale Idee, und ich habe ihn pflichtschuldig angelegt, mit einer Datei je Notiz, damit mehrere Geräte gleichzeitig hineinschreiben können, ohne dass Git in Konflikte läuft.
Dann hat der Agent nachgezählt. Über die gesamte Historie des Repositories ist genau eine Notiz durch den Posteingang gegangen, während über zweihundert Dokumente direkt an ihren zuständigen Ort geschrieben wurden. Heute ist er leer.
Der Grund ist einfach: Wenn ich im Gespräch etwas beisteuere, ist der richtige Ort meistens offensichtlich, und ihn erst in einen Zwischenspeicher zu legen ist eine Zeremonie ohne Nutzen. Der Posteingang bleibt trotzdem, aber für den Fall, für den er gedacht war: eine Notiz unterwegs, ohne Sitzung, ohne Ablageentscheidung.
Das ist eine kleine Sache mit einer allgemeinen Lehre. Ein Ablauf, der in einem Buch überzeugend klingt, lässt sich an der eigenen Historie messen, statt ihn jahrelang zu glauben. Es kostet einen Zählbefehl.
Wissen bleibt, Struktur darf sich ändern
Das Leitprinzip des Systems steht in einem Satz: Wissen bewahren, Struktur weiterentwickeln. Informationen sind dauerhaft, Ordnung ist Version eins und darf sich verbessern.
Praktisch heißt das, dass ein Agent Dateien verschieben, umbenennen, zusammenlegen und aufteilen darf, ohne zu fragen, solange er alle Verweise nachzieht und den Umbau protokolliert. Was er ohne ausdrückliche Zustimmung nicht darf, steht genauso klar da: historische Angaben löschen, Rohnotizen unwiderruflich entfernen, vertrauliche Inhalte nach außen geben, Geheimnisse speichern, groß angelegt aufräumen. Im Zweifel wird archiviert, nicht gelöscht.
In neun Tagen sind auf diese Weise 64 protokollierte Strukturänderungen zusammengekommen, jede mit Beobachtung, Änderung, Begründung, Ergebnisfeld und der Angabe, ob sie umkehrbar ist. Das klingt nach viel, und es ist viel. Es ist nur deshalb vertretbar, weil Git darunter liegt: Jede dieser Änderungen ist ein Diff, den ich lesen kann, und jede lässt sich zurücknehmen.
Autonomie ohne Versionskontrolle wäre fahrlässig. Mit Versionskontrolle ist sie der Grund, warum das System heute besser sortiert ist als an dem Tag, an dem ich es entworfen habe.
Eine Regel, die kein Mechanismus prüft, hält nicht
Das ist die Lektion, für die sich der ganze Aufbau gelohnt hat, und ich habe sie an einer Lappalie gelernt.
Ich will in Texten keine langen Gedankenstriche sehen. Der Grund ist nicht Typografie, sondern dass sie für mich nach maschinell erzeugtem Text aussehen. Die Regel stand an vier Stellen: in der Betriebsanleitung, in der Datei für Claude Code, im Musterkatalog und zusätzlich im Gedächtnis des Modells.
Sie wurde zweimal von Sitzungen gebrochen, die sie kannten. Einmal in Chatantworten, einmal in zwanzig hinzugefügten Zeilen eines nächtlichen Aufräumlaufs. Gefunden hat sie beide Male nicht das Lesen, sondern ein Suchbefehl über den Diff.
Dasselbe Muster an zwei weiteren Stellen im selben Zeitraum. Erfundene Werte in den Metadaten: vier wurden zurückgedreht und die Regel festgeschrieben, in den zwei Tagen danach entstanden drei neue. Erst als eine maschinelle Prüfung dazukam, wurde der nächste sofort gemeldet statt eingecheckt. Und ein Lebenszeichen für die Cloud-Läufe, das in zwei Ablaufdokumenten beschrieben und in keinem der Prompts umgesetzt war: die Überwachung gegen stille Ausfälle war selbst einer.
Die Schlussfolgerung ist unbequem, weil sie den bequemen Reflex ausschließt. Wenn eine Konvention gebrochen wird, ist der falsche Hebel, sie schärfer zu formulieren. Wer eine Regel nicht liest, liest auch die fett gedruckte nicht. Die Frage lautet stattdessen: Lässt sich derselbe Satz als Prüfung schreiben? Wenn ja, ist die Prüfung die Regel, und der Text daneben ist nur noch die Begründung.
Heute laufen drei solche Prüfungen, bevor etwas eingecheckt wird: eine über Links, Anker und Metadatentypen, ein Suchbefehl über den Diff für die Gedankenstriche und einer, der versehentliche Löschungen findet. Die Grenze der Methode gehört dazu: Sie gilt für Konventionen über Form, Metadaten und Ablage, die sich mechanisch entscheiden lassen. Was als Fakt gilt und was vollständig protokolliert wird, entscheidet weiter ein Mensch.
Wenn Ihnen das bekannt vorkommt: Genau das ist der Kern dessen, was ich beim Einführen von Claude Code in Teams baue. Eine Architekturregel, die ein Agent lesen soll, ist keine Regel. Eine Architekturregel, die eine Pipeline erzwingt, ist eine.
Eine Prüfung, die still grün meldet
Die Fortsetzung dieser Lehre kam vier Tage später und war teurer.
Das Skript, das interne Links und Anker prüft, hielt eine Prosazeile für den Anfang eines Codeblocks, weil sie mit drei Backticks begann. Der Block wurde nie geschlossen, also übersprang das Skript den Rest der Datei. Etwa 520 von 1015 Zeilen blieben vier Tage lang ungeprüft. In dieser Zeit meldete jeder Lauf zuverlässig: null Befunde.
Aufgefallen ist es nur, weil ein Umbau in genau diesem Bereich echte Fehler erzeugte und die Prüfung sie nicht sah.
Der Schaden ist dabei nicht die Lücke. Der Schaden ist das Vertrauen, das die grüne Meldung erzeugt und nicht deckt. Wer keine Prüfung hat, sieht selbst nach. Wer eine grüne Meldung hat, sieht nicht mehr nach.
Die Antwort darauf ist ein Kanarienvogel: eine Datei mit einem absichtlich kaputten Link, den jeder vollständige Lauf finden muss. Findet er ihn nicht, bricht er mit einem Fehler ab, statt Erfolg zu melden. Daneben steht eine zweite Prüfung auf genau die aufgetretene Ausfallart, nämlich jede Datei, die innerhalb eines Codeblocks endet. Der Kanarienvogel allein hätte den Fall nicht gefunden, denn die Maschinerie lief ja.
Die Frage, die seitdem beim Bau jeder Überwachung am Anfang steht, ist: Wie sieht ihr Ausfall aus? Wenn die Antwort „wie Erfolg" lautet, ist die Überwachung nicht fertig. Praktisch heißt das: kein stilles Überspringen, kein Weiterlaufen ohne Zählung, kein leeres Ergebnis, das nicht von „nichts gefunden" unterschieden wird.
Auf meiner Seite zum Einführen von Observability steht der verwandte Satz: Ein Ausfall wird vom Kunden gemeldet, nicht vom System. Den habe ich für Kundensysteme geschrieben. Dass er genauso für die Prüfungen gilt, die ich über meine eigenen Notizen laufen lasse, ist mir erst hier aufgefallen.
Was das System heute ohne mich tut
Neun Automatisierungen schreiben in das Repository oder lesen daraus, ohne dass ich einen Befehl gebe.
Vier holen Material herein. Ein Lauf um 06:30 destilliert neue Dokumente aus dem Dokumentenarchiv in die zuständigen Dateien, ein Commit je Dokument. Um 07:15 macht ein zweiter dasselbe mit relevanten Mail-Verläufen und zieht Fakten, Zusagen, Fristen und Personen heraus. Um 05:00 fasst ein dritter die Nachrichten des Vortages in die Tagesnotiz. Um 04:30 liest ein vierter alle Kalender und schreibt die Terminübersicht neu, heute bis 180 Tage voraus.
Zwei halten das System in Form. Ein Lauf in der Cloud legt morgens fehlende Journalnotizen an, ein zweiter leert abends den Posteingang in die kanonischen Ordner. Ein leerer Lauf schreibt nichts außer seinem Lebenszeichen, was wichtiger ist, als es klingt: Was jede Nacht läuft, findet meistens nichts, und eine Automatisierung, die dann trotzdem etwas produziert, erzeugt Rauschen statt Ruhe.
Drei arbeiten an der Oberfläche. Ein Exporter liest das Repository alle 15 Minuten und schreibt nie hinein. Ein Morgenbriefing stellt um 06:30 Termine, Fristen und Liegengebliebenes in einen privaten Kanal, dazu stündlich eine Eskalationsprüfung, die nur bei einem harten Auslöser meldet. Und ein Agent liest denselben Kanal, antwortet aus dem Repository heraus und ändert es, wenn ich ihn ausdrücklich dazu auffordere, mit einer Aktion je Commit, damit jede einzeln zurückgenommen werden kann.
Darüber liegt dieselbe Überwachung, die ich bei Kunden baue: Kennzahlen als Dateien, Prometheus, ein Dashboard, neun Alarmregeln. Zwei davon überwachen nicht die Automatisierungen, sondern das Repository selbst: eine für jeden internen Link, dessen Ziel es nicht gibt, und eine für den Fall, dass die Prüfung dahinter aufgehört hat zu prüfen.
Was das für mich ändert, ist banaler, als die Liste vermuten lässt. Ich werde morgens an Dinge erinnert, die ich sonst verschiebe. Liegengebliebenes wird sichtbar, statt still älter zu werden. Und ein Teil meiner Aufgaben entsteht inzwischen, ohne dass ich sie aufschreibe, weil sie aus einer Mail oder einem Termin herausfallen.
Eine Sache daran ist nicht sauber, und ich sage sie lieber selbst: Das Briefing trägt vertrauliche Inhalte in einen Chatkanal hinaus. Das ist ein bewusster Handel, abgesichert nur dadurch, dass der Kanal privat ist. Die Absicherung liegt im Kanal, nicht im Inhalt.
Was nicht funktioniert
Das System hat eine Lernschleife: beobachten, Muster erkennen, Hypothese bilden, kleine umkehrbare Änderung machen, benutzen, auswerten, behalten oder zurücknehmen. Sie ist ordentlich dokumentiert, und sie dreht zuverlässig bis „Änderung gemacht".
Dann hört sie auf. Von den 64 protokollierten Änderungen tragen 59 im Ergebnisfeld immer noch „offen". Vier sind ausgewertet. Das heißt: Das System dokumentiert seine Umbauten vorbildlich und bewertet sie so gut wie nie. Dass eine zurückgenommene Änderung als Erfolg gilt, steht in der Beschreibung. Es funktioniert nur, wenn jemand nachsieht, und das ist bisher der Schritt, der ausfällt.
Zweitens die Gedankenstriche aus dem vorletzten Abschnitt. Neue Texte sind sauber, weil eine Prüfung dazwischen steht. Im Bestand enthalten weiterhin 248 Dateien das Zeichen. Nicht nachgezogen, weil das ein Diff über das halbe Repository wäre, und die Aufgabe steht in einem Rückstand, was eine höfliche Art ist zu sagen: nicht gemacht.
Drittens, und das relativiert alles darüber: Neun Tage sind kein Beleg. Jede Zahl in diesem Artikel stammt aus einem System, das neun Tage alt ist. Ob die Ordnung nach einem Jahr noch trägt, ob die Automatisierungen dann noch laufen und ob ich die Auswertungsschleife jemals schließe, weiß ich nicht. Wer Ihnen nach neun Tagen eine Methode verkauft, verkauft eine Vermutung.
Was davon auf ein Team übergeht
Das hier ist ein persönliches System, und der Verzeichnisbaum darin ist der uninteressanteste Teil. Übertragbar sind drei Sätze, und sie gelten für ein Team härter als für eine Person.
Ein Fakt, ein Ort. Sobald dieselbe Aussage an zwei Stellen gepflegt wird, beantwortet ein Agent dieselbe Frage unterschiedlich, je nachdem was er geladen hat. In einem Team mit einem Wiki, einem Ticketsystem und drei Repositories ist das der Normalzustand, nicht die Ausnahme.
Eine Regel ohne Mechanismus hält nicht. Das gilt für Architekturregeln in einer Codebasis genauso wie für Gedankenstriche in Notizen. Wenn Sie Agenten auf Ihren Code lassen, brauchen Sie die erzwingende Schicht vorher, nicht danach.
Eine Prüfung, die still grün meldet, ist schlechter als keine. Das ist keine neue Erkenntnis aus dem Betrieb verteilter Systeme. Neu ist nur, wie schnell man sie in einem Wissenssystem wieder lernt.
Der Grund, warum mich das beruflich beschäftigt, steht in meinem eigenen Legacy Risk Score: Wissen und Abhängigkeiten sind dort eine von vier Dimensionen, und es ist die, bei der die Antwort nie ein Werkzeug ist. Ein Team, in dem drei Leute wissen, wie deployt wird, hat kein Dokumentationsproblem. Es hat ein Problem damit, dass sein Wissen nirgends in einer Form liegt, die jemand anders lesen kann, Mensch oder Maschine.
Wie das konkret aussieht, wenn Agenten in einer Codebasis mitarbeiten sollen, habe ich im Artikel zu Agentic Coding mit Spec-Driven Development beschrieben. Dieser Artikel hier ist die Ebene darunter: das Wissen, aus dem eine Spezifikation überhaupt erst entstehen kann.
