Versionierung

Ein Agent arbeitet schnell und in der Breite. Ein Auftrag von zwei Sätzen kann zwanzig Dateien anfassen, davon fünfzehn richtig. Dass er Fehler macht, ist gesetzt. Was sich beeinflussen lässt, ist der Preis eines einzelnen.

Genau diese Frage beantwortet die Versionsverwaltung, und deshalb steht sie in diesem Kurs so weit vorn.

Git in einem Absatz

Git hält Stände fest. Ein Commit ist ein Standbild der Dateien, die in Git liegen, mit Zeitpunkt, Urheber und einem Satz dazu, warum er entstanden ist. Aus einer Reihe solcher Standbilder ergibt sich zweierlei: Sie können zu jedem dieser Stände zurück, und Sie können sehen, was sich zwischen zweien davon geändert hat.

Die Einschränkung steckt im ersten Satz. Was Git nicht verwaltet, steht in keinem Commit: die Zugangsdaten in der lokalen Umgebungsdatei, die installierten Abhängigkeiten, die Datenbank daneben. Der Rückweg führt zu einem Dateistand, er stellt kein Projekt wieder her.

Für die Arbeit mit einem Agenten sind beide Richtungen zentral. Der Rückweg macht einen Fehlversuch billig. Der Vergleich beantwortet die Frage, was da eigentlich gerade passiert ist, und zwar am Ergebnis statt am Bericht des Agenten.

Der Agent bucht selbst ein

Bei Aider, dem ältesten Werkzeug dieser Bauform, ist das die Voreinstellung:

Whenever aider edits a file, it commits those changes with a descriptive commit message. (externe Seite, aider.chat)

Bemerkenswert ist der Schritt davor. Findet Aider beim Start bereits geänderte Dateien vor, kommen die zuerst in einen eigenen Commit:

Aider will first commit any preexisting changes with a descriptive commit message. (externe Seite, aider.chat)

Der Grund dafür ist eine Trennlinie, die Sie sich merken sollten: Ihre Arbeit und die des Agenten sollen in verschiedenen Commits liegen. Sonst lässt sich hinterher nicht mehr auseinanderhalten, wer was getan hat, und der Rückweg nimmt Fremdes mit.

Eine zweite Voreinstellung derselben Seite zeigt in die andere Richtung, und sie ist leicht zu überlesen:

By default, aider skips pre-commit hooks (externe Seite, aider.chat)

Wie das geschieht, steht im selben Satz: Aider hängt an seinen Commit den Schalter --no-verify. Prüfungen, die vor jedem Commit laufen sollen, laufen hier also nicht. Wer sich darauf verlässt, dass ein Formatierer oder eine Suche nach Zugangsdaten den Commit aufhält, muss das eigens einschalten. Was solche Prüfungen leisten und warum sie den Rang einer Schranke haben, steht in Kapitel 08.

Andere Werkzeuge halten sich zurück und committen erst, wenn man sie darum bittet. Beide Wege sind vertretbar. Stundenlang ohne Commit zu arbeiten, ist es nicht.

Der eingebaute Rückweg

Die meisten Agenten haben inzwischen eine eigene Rücknahme, unabhängig von Git. Bei Claude Code heißt sie Checkpoint und entsteht ohne Zutun:

Every prompt you send that starts a turn creates a new checkpoint (externe Seite, code.claude.com)

Das ist bequem und im Alltag oft genau richtig: Ein Auftrag ging daneben, zwei Tastendrücke später ist der Stand von vorhin wieder da, samt Gesprächsverlauf.

Wichtiger ist allerdings, was diese Rücknahme nicht erfasst. Die Dokumentation nennt vier Lücken, und jede einzelne ist ein realer Alltagsfall:

Checkpointing does not track files modified by bash commands. (externe Seite, code.claude.com)

Alles, was über die Kommandozeile passiert, fällt heraus. Ein verschobenes Verzeichnis, ein Skript, das Dateien erzeugt, ein Paketmanager: nicht erfasst.

Checkpointing only tracks files that have been edited within the current session. (externe Seite, code.claude.com)

Was Sie selbst im Editor geändert haben, ist nicht dabei. Was eine zweite Sitzung nebenan getan hat, auch nicht.

Drittens die Subagenten. Was einer von ihnen ändert, kommt in aller Regel nicht zurück, und die Dokumentation sagt für diesen Fall in vier Worten, was stattdessen hilft: Use git to revert them. (externe Seite, code.claude.com) Eine Ausnahme steht daneben, sie betrifft eine Bauart, die im Vordergrund und innerhalb Ihres eigenen Zuges arbeitet.

Und viertens die verknüpften Pfade:

Claude Code skips any tracked path that is a symlink or hard link (externe Seite, code.claude.com)

Das trifft zwei Dinge, die man sich selten aussucht: eine Konfigurationsdatei, die ein Verwaltungswerkzeug ins Projekt hineinverlinkt, und Abhängigkeiten, die ein Paketmanager als Hardlink ablegt. Die Rücknahme überspringt sie und sagt hinterher, wie viele es waren.

seitlich verschiebbar

eigene Darstellung, Stand 07.08.2026

Der Hersteller sagt das selbst und in derselben Reihenfolge:

For permanent version history and collaboration, continue using version control, such as Git, for commits, branches, and long-term history. (externe Seite, code.claude.com)

Klein und oft

Aus dem Tempo folgt der Takt. Wer nach drei Stunden Arbeit einen einzigen Commit macht, hat einen Stand, in dem sieben Dinge gleichzeitig stecken. Ist eines davon falsch, gibt es keinen Rückweg, der nur dieses eine betrifft.

Die brauchbare Gewohnheit: nach jedem abgeschlossenen Gedanken committen. Ein Commit sollte eine Sache enthalten und in einem Satz beschreibbar sein. Braucht der Satz ein „und“, um zwei verschiedene Absichten zu verbinden, waren es zwei Commits. Eine Änderung und der Test dazu sind eine Absicht.

Wer testgetrieben arbeitet, dreht die Reihenfolge um und bucht den Test zuerst ein. Der Commit davor wird damit zum Nachweis, dass die Erwartung vor dem Code dastand, siehe Erst der rote Test.

Das kostet wenig und zahlt sich beim ersten Fehlversuch aus.

Die Nachricht ist auch für die Maschine

Ein Detail, das man leicht übersieht: Der Branch, die nicht committeten Änderungen und die jüngsten Commits gehören zu dem, worauf ein Werkzeug wie Claude Code von sich aus zugreift. Der Hersteller führt es unter den Dingen auf, an die es in einem Projektverzeichnis herankommt:

Your git state. Current branch, uncommitted changes, and recent commit history. (externe Seite, code.claude.com)

Eine Commit-Nachricht ist damit doppelt adressiert. Sie erklärt einem Menschen in sechs Monaten, warum eine Änderung entstand, und sie erklärt es einem Agenten in der nächsten Sitzung. Was das für das Gedächtnis eines Projekts bedeutet, steht in Kapitel 05.

Sobald mehr als eine Sitzung läuft oder Sie neben dem Agenten selbst am Projekt arbeiten, hört der Commit auf, eine Formsache zu sein. Er wird zur Stelle, an der Arbeit verschwindet.

Der Schnitt

Ein Commit hat zwei Angaben: was hineinkommt und warum. Die zweite ist die Nachricht, über die viel geschrieben wird. Die erste wird meist auf einen Reflex reduziert, und dieser Reflex heißt git add -A.

Er bedeutet wörtlich: alles, was gerade im Verzeichnis anders ist. Solange Sie allein arbeiten und der Agent das Einzige ist, was sich bewegt, stimmt das zufällig. Sobald daneben etwas anderes liegt, buchen Sie es mit ein.

Der Gegenentwurf ist eine Zeile länger und in jedem Fall richtig:

git commit -- src/api/handler.ts src/api/handler.test.ts

Zwei Pfade, ein Zweck, nichts sonst. Der Zusatz nach den zwei Strichen nimmt genau diese Dateien, unabhängig davon, was jemand anders vorbereitet hat.

Der Fall, der das lehrt

An diesem Projekt liefen an einem Tag im Juli 2026 zwei Sitzungen gleichzeitig im selben Verzeichnis. Beide arbeiteten an verschiedenen Dingen, beide fanden beim Committen einen Worktree vor, in dem mehr lag als die eigene Arbeit. Das Ergebnis war ein Commit, der die Änderungen der anderen Sitzung enthielt und wieder auseinandergenommen werden musste.

Der Fehler war weder ein Versehen noch schlechtes Werkzeug. Er war die vorhersehbare Folge davon, dass zwei Schreiber sich einen Worktree teilen. Ein Agent kann nicht wissen, welche der geänderten Dateien ihm gehören, und git status sieht für beide gleich aus.

Daraus folgen zwei Antworten, eine kleine und eine strukturelle.

Die kleine Antwort: pfadgenau

Der Agent bucht nur ein, was er selbst angefasst hat. Das lässt sich als Regel in die Projektanweisung schreiben, und es hilft in den meisten Fällen. Es bleibt allerdings eine Bitte, mit allem, was in Kapitel 03 dazu steht.

Aider löst dasselbe Problem von der anderen Seite und bucht Vorgefundenes zuerst separat ein, damit die eigene Arbeit sauber daneben liegt.

Die strukturelle Antwort: getrennte Worktrees

Git kann ein Repository mehrfach auschecken. Jeder dieser Worktrees hat eigene Dateien und einen eigenen Branch und teilt sich mit den anderen die Historie:

Running each Claude Code session in its own worktree means edits in one session never touch files in another, so one session can build a feature while a second fixes a bug. (externe Seite, code.claude.com)

Der Unterschied zur Regel eine Ebene höher ist grundsätzlich. Eine Regel kann befolgt werden. Bei getrennten Worktrees gibt es nichts zu befolgen, weil die fremde Datei physisch woanders liegt. Aus einer Verhaltensfrage wird eine Eigenschaft des Aufbaus.

seitlich verschiebbar

eigene Darstellung, Stand 03.08.2026

Dieselbe Trennung gibt es inzwischen eine Ebene tiefer. Wenn ein Agent Subagenten parallel arbeiten lässt, kann jeder von ihnen seinen eigenen Worktree bekommen, und wann sich das lohnt, steht in Kapitel 09.

Wann derselbe Worktree trotzdem reicht

In der Praxis laufen häufig mehrere Sitzungen nebeneinander im selben Verzeichnis, und meistens geht das gut. Die Bedingung dafür ist benannt, und zwar ausgerechnet dort, wo mehrere Agenten sich bewusst kein eigenes Verzeichnis nehmen: in der Dokumentation zu Agententeams.

Two teammates editing the same file leads to overwrites. Break the work so each teammate owns a different set of files. (externe Seite, code.claude.com)

Das ist die ganze Regel, und sie erklärt beides. Solange die Zuständigkeiten sich nicht überschneiden, merkt niemand etwas, und die Arbeitsweise fühlt sich verlässlich an. Verlässlich ist sie genau so lange, wie die Aufteilung hält.

Der Unterschied zu getrennten Worktrees ist damit derselbe wie eine Überschrift weiter oben: Hier schützt eine Absprache, dort eine Eigenschaft. Wer die Absprache im Kopf hat, kommt damit weit, und wird sie einmal übersehen, sieht das Ergebnis aus wie der Vorfall am Anfang dieses Textes.

Zur Größenordnung nennt dieselbe Seite einen Wert: Sie rät, mit drei bis fünf Beteiligten anzufangen, weil jeder weitere die Kosten linear erhöht und den Abstimmungsaufwand mit. Wohin die Entwicklung geht, zeigt daneben eine Voreinstellung: In der Anwendung für den Rechner bekommt jede neue Sitzung ihren eigenen Worktree, ohne dass jemand danach fragt (externe Seite, code.claude.com).

Was ein frischer Worktree nicht mitbringt

Die Kante, über die man beim ersten Mal stolpert: Ein Worktree ist ein frischer Auscheckvorgang. Was nicht in Git liegt, ist nicht da. Zugangsdaten in einer lokalen Umgebungsdatei, installierte Abhängigkeiten, lokale Einstellungen: alles fehlt.

Dafür gibt es eine Mitnahmeliste, und ihre Regel ist eng gefasst:

Only files that match a pattern and are also gitignored are copied, so tracked files are never duplicated. (externe Seite, code.claude.com)

Nur wer beides erfüllt, kommt mit. Eine committete Datei kann eine solche Liste damit nicht überschreiben.

Die zweite Bedingung ist allerdings der Punkt. Was in einem Projekt nicht in Git liegt, sind meistens die Zugänge, und das Beispiel der Dokumentation sagt es offen:

This .worktreeinclude copies two env files and a secrets config into each new worktree (externe Seite, code.claude.com)

Jeder neue Worktree bekommt also eine weitere Kopie der Zugangsdaten. Dahinter steht die schwerere Folge: Zwei Sitzungen mit derselben Umgebungsdatei greifen auf dieselbe Datenbank und denselben Fremdzugang zu. Die Trennung reicht bis zu den Dateien. Was die Befehle darin anfassen, liegt für beide am selben Ort.

Dazu kommt, dass die Liste für jeden Worktree gilt, den das Werkzeug anlegt, auch für die der Subagenten. Für die Liste heißt das: so kurz wie möglich, und wo es geht mit Testzugängen darin statt der echten. In Kapitel 03 steht dieselbe Regel für die Projektanweisung, und sie steht dort aus demselben Grund.

Branches sind billig

Für die Arbeit mit einem Agenten lohnt sich eine Gewohnheit, die in manchen Teams als Umstand gilt: für jeden Auftrag ein eigener Branch.

Der Grund ist der Rückweg. Ein Branch, der nichts taugt, wird gelöscht, und in der Hauptlinie bleibt keine Spur davon. Ein Auftrag, der direkt dort ausgeführt wurde, muss zurückgenommen werden, und das ist eine Änderung, die wieder in der Historie steht.

Praktisch heißt das auch: Der Branch ist das Zeichen für fertig. Solange er danebenliegt, ist an der Hauptlinie nichts passiert. Was gilt, entscheidet der Mensch beim Zusammenführen.

Wer committet

Es gibt zwei brauchbare Aufteilungen, und beide funktionieren:

Der Agent bucht ein, was er getan hat. Schnell, lückenlos, und die Historie zeigt jeden Schritt. Der Preis sind viele kleine Commits, die vor dem Zusammenführen gebündelt werden wollen.

Der Mensch bucht ein. Jeder Commit ist durchgesehen. Der Preis ist, dass zwischen zwei Commits Arbeit liegt, für die es keinen Rückweg gibt, und dass diese Lücke genau dann am längsten wird, wenn es hektisch wird.

Was gar nicht funktioniert, ist die dritte Variante: Man nimmt sich vor, später selbst zu committen, und tut es dann nicht.

Die Versionsverwaltung wird meist als Sicherheitsnetz beschrieben. Das ist die halbe Sache. Die andere Hälfte ist, dass sie ein durchsuchbares Protokoll des Projekts führt, und dass ein Agent es lesen kann.

Ein Protokoll, das sich befragen lässt

Der Unterschied zu jeder anderen Dokumentation: Die Historie ist datiert, maschinenlesbar und entsteht beim Arbeiten. Sie enthält die Stände, die jemand committet hat, in der Reihenfolge, in der das geschah.

Zwei Einschränkungen gehören in denselben Absatz, weil sie beim Wort „Protokoll“ gern mitgedacht werden. Zwischen zwei Commits liegt Arbeit, von der nichts erhalten bleibt. Und committete Stände lassen sich nachträglich ändern: Wie gewöhnlich dieser Vorgang ist, zeigt ein Befehl, den Git im April 2026 dafür bekommen hat.

Rewrite history by rearranging or modifying specific commits in the history. (externe Seite, git-scm.com)

Er heißt git history, führt in seiner eigenen Überschrift das Wort EXPERIMENTAL und kann eine Änderung in einen älteren Commit hineinlegen, eine Nachricht ersetzen oder einen Commit in zwei zerlegen. Neu ist der Befehl, nicht die Möglichkeit.

Drei Befehle machen aus der Historie einen Suchraum, und alle drei kann ein Agent selbst absetzen:

Wer hat diese Zeile zuletzt angefasst und warum. git blame beantwortet die erste Hälfte, der zugehörige Commit die zweite. Gemessen wird dabei die letzte Änderung an der Zeile. Eine Umformatierung schiebt sich also davor und verdeckt die Herkunft. Für die Frage „warum steht das hier so“ ist es trotzdem oft schneller als jede Suche im Code.

Wann kam dieser Satz ins Projekt. git log -S sucht nach dem Zeitpunkt, an dem eine Zeichenfolge auftauchte oder verschwand. Bei der Frage, ob eine merkwürdige Zeile Absicht war, führt das direkt zum Commit, in dem sie entstand.

Ab wann ist es kaputt. git bisect halbiert die Historie so lange, bis der Commit übrig bleibt, der einen Fehler eingeführt hat. Das ist mechanisch und damit genau die Art Arbeit, die man abgeben kann.

Der Wert dieser drei steht und fällt mit dem Takt aus Ebene 1. In einer Historie aus Tagescommits findet git bisect einen Stand mit sieben Änderungen, und die Antwort lautet dann „irgendwo hier drin“.

Was in die Nachricht gehört

Wenn eine Maschine mitliest, verschiebt sich, was eine gute Commit-Nachricht ausmacht. Das Was steht ohnehin im Diff und muss nicht wiederholt werden. Wertvoll ist das Warum, weil es sonst nirgends steht.

Ein Beispiel aus diesem Projekt. Die Nachricht lautete sinngemäß: Der Prüflauf committet nur auf der Hauptlinie, weil nachts ein anderer Lauf im selben Verzeichnis auf einem eigenen Branch steht und die Prüfergebnisse sonst dorthin geschoben würden. Das ist ein Satz, den niemand aus dem Diff rekonstruieren kann, und er beantwortet die Frage, die ein halbes Jahr später aufkommt.

Eine feste Form hilft dabei, weil sie maschinenlesbar ist. Verbreitet sind Präfixe wie feat, fix, docs und refactor, gefolgt vom Bereich. Der Nutzen liegt weniger in der Ordnung als darin, dass sich eine Historie danach filtern lässt.

Git steht ohnehin im Kontext

Ein Punkt, der die Rechnung ändert: Branch, Zustand und die letzten Commits gehören zu dem, was ein Werkzeug wie Claude Code beim Start vor sich hat, ohne dass jemand danach gefragt hätte.

Wo genau, sagt die Herstellerseite zum Kontextfenster. Sie führt die Umgebungsangaben als eigenen Posten mit rund 280 Token auf, dazu gehören Arbeitsverzeichnis, Plattform, Shell und die Frage, ob überhaupt ein Git-Repository vorliegt. Branch, Zustand und die jüngsten Commits kommen nach derselben Stelle (externe Seite, code.claude.com) als eigener Block ganz am Ende der Systemanweisung dazu.

Damit ist die Historie kein Nachschlagewerk, das man erst öffnen muss. Sie ist Teil dessen, was der Agent über das Projekt weiß, und eine gepflegte Historie ist deshalb eine Investition in jede künftige Sitzung. Die Fortsetzung dieses Gedankens steht in Kapitel 05.

Was Git nicht beantwortet

Und jetzt die Grenze, an der dieses Projekt selbst hängengeblieben ist.

Git kennt jeden committeten Stand. Es weiß, was auf welchem Branch liegt und was auf dem Server steht. Eine Frage beantwortet es von sich aus nicht: welcher dieser Stände draußen bei den Lesern angekommen ist.

Das klingt nach einer Kleinigkeit und ist es nicht. Ein Automat, der veröffentlichen soll, muss wissen, worauf er aufsetzt. Ohne diese Angabe kann er nur raten, und die naheliegende Vermutung „der letzte Commit auf der Hauptlinie“ ist regelmäßig falsch: Über dem veröffentlichten Stand liegt fast immer Arbeit, die bewusst noch nicht draußen ist.

Vereinbaren lässt sich das durchaus in Git, über eine Marke, einen eigenen Branch oder eine Notiz am Commit. Nur entsteht die Angabe nicht von selbst, und sie muss den Weg von der Veröffentlichung zurück ins Repository finden. Diese Website führt deshalb einen eigenen Vermerk mit, der bei jedem Veröffentlichen fortgeschrieben wird: der Commit, der live ging, und die einzelnen Dateien, die darüber hinaus mitgingen. Fehlt der Vermerk, bricht der Vorgang ab. Der Satz dahinter ist eine Regel für alle Automaten dieser Art: Wer nicht weiß, was gilt, veröffentlicht nicht.

seitlich verschiebbar

eigene Darstellung, Stand 07.08.2026

Automatik und ihre zwei Fallen

Sobald Sicherung und Veröffentlichung an Jobs übergeben werden, kommen zwei Fehler dazu, die beide eine gemeinsame Form haben: Sie sehen im Betrieb aus wie Erfolg.

Ein Automat, der alles committet, ist die Ebene-2-Falle mit größerem Radius. Ein nächtlicher Job, der git add -A fährt, nimmt jede halbfertige Datei mit, die jemand liegen gelassen hat. Die Antwort ist dieselbe wie oben, pfadgenau, und zusätzlich eine Entscheidung: Ein Job, der sichert, sollte nur pushen und niemals committen. Was einzubuchen ist, entscheidet ein Mensch.

Ein Job, der stillschweigend scheitert. An diesem Projekt lief die nächtliche Sicherung neun Läufe lang ins Leere, weil ein Schlüssel fehlte. Im Protokoll stand ein Fehler, gemeldet wurde nichts, und von außen sah der Job aus wie ein Job, der läuft. Der Vault war in dieser Zeit nirgends gesichert.

Daraus wurde eine Regel, die über Git hinausgeht: Ein Automat, der etwas sichern soll, muss seinen eigenen Fehlschlag melden können. Sonst misst man das Vorhandensein eines Jobs und hält es für das Vorhandensein einer Sicherung.

Was Checkpoints dafür nicht leisten

Zum Abschluss die Abgrenzung aus Ebene 1, eine Stufe genauer. Die tooleigene Rücknahme ist an die Sitzung gebunden und kennt weder Branches noch einen zweiten Rechner. Sie überlebt das Wiederaufnehmen einer Sitzung, hat dann aber eine Frist:

Claude Code deletes a session’s file snapshots in the retention sweep, by default about 30 days after the session last saved one. (externe Seite, code.claude.com)

Die Frist lässt sich verstellen. Für die Frage „nimm die letzten fünf Minuten zurück“ ist die Rücknahme trotzdem das bessere Werkzeug, weil sie den Gesprächsverlauf mitnimmt.

Für alles, was jemand anders sehen soll, ist sie es nicht.