Den Faden wieder aufnehmen können

Drei Empfänger, dieselbe Anforderung

Von Übergabe spricht man meist, wenn ein Projekt den Besitzer wechselt. Bei Lösungen, die mit Agenten gebaut werden, passiert sie viel öfter, und zwar an drei Empfänger.

Der erste ist der Kunde. Er muss das System ohne dich betreiben und weiterentwickeln können, und ohne die Sitzung, in der dein Agent alles wusste. Der zweite ist ein anderer Agent oder ein anderes Werkzeug, denn Werkzeuge wechseln, und mit ihnen der Agent. Der dritte bist du selbst, in drei Monaten, wenn das Projekt nur unregelmäßig weiterläuft und du nicht mehr weißt, warum die Tabelle so heißt.

Für alle drei gilt dasselbe: Was man zum Weitermachen braucht, muss im Repository stehen. Der Chatverlauf ist kein Ablageort. Er ist an ein Werkzeug und ein Konto gebunden, wird irgendwann zusammengefasst oder gelöscht, und der Kunde bekommt ihn ohnehin nicht. In Spec-driven Development: die zweite Schuld steht dazu der Satz, der hier gilt: Ein Agent liest keine Köpfe.

Dieser Teil der Serie beschreibt fünf Dinge, die ins Repository gehören, eines, das bewusst nicht hineingehört, und eine Probe, mit der du feststellst, ob es reicht.

Starten ohne Vorwissen

Die README ist die Datei, die ein Projekt vorstellt und erklärt. Für die Übergabe zählt daran ein Abschnitt: Wie bringt jemand das Projekt auf einem frischen Rechner zum Laufen? Welche Software muss installiert sein, welche Befehle in welcher Reihenfolge, woran sieht man, dass es geklappt hat, und wie laufen die Tests?

Dazu gehört die Konfiguration. Die Regel aus dem Twelve-Factor-Manifest lautet, Konfiguration strikt vom Code zu trennen, weil sie sich je Umgebung unterscheidet und der Code nicht. Praktisch heißt das: Im Repository liegt eine Beispieldatei, die jede nötige Einstellung mit Namen und Erklärung aufführt, aber ohne echte Werte.

Eine Anweisungsdatei, die jedes Werkzeug liest

Coding-Agenten lesen zu Beginn eine Datei mit Anweisungen zum Projekt: wie gebaut und getestet wird, welche Konventionen gelten, was verboten ist. Lange hatte jedes Werkzeug dafür einen eigenen Dateinamen. Wer wechselte, fing von vorn an.

AGENTS.md ist der Versuch, das zu vereinheitlichen. Das Format ist offen, entstand aus der Zusammenarbeit mehrerer Hersteller und wird inzwischen unter dem Dach der Linux Foundation betreut. Die Unterstützung sieht nach den jeweiligen Dokumentationen am 13.10.2026 so aus:

Daraus folgt eine einfache Ordnung. Die Regeln des Projekts stehen in AGENTS.md. Braucht ein Werkzeug seine eigene Datei, enthält sie nur, was für dieses Werkzeug besonders ist, und verweist für den Rest auf AGENTS.md. So gibt es eine Quelle, und ein Wechsel kostet eine kurze Datei statt eines Neuanfangs.

Was hineingehört, beschreibt die Seite des Formats selbst: alles, was man auch einem neuen Teammitglied sagen würde. Für eine Lösung mit professionellem Anspruch sind das mindestens die Regeln aus den anderen Teilen dieser Serie: Schemaänderungen nur als Migration, kein Zugriff auf Produktionsdaten, Anmeldung und Zahlung nur über die festgelegten Dienste, bei Fehlern erst ein Test.

Halte die Datei kurz. Die Dokumentation von Claude Code nennt als Richtwert unter 200 Zeilen je Datei und begründet das: Längere Dateien verbrauchen mehr Kontext, und die Anweisungen werden schlechter befolgt. Wie man eine Anweisungsdatei als knappe Karte mit Verweisen aufbaut, steht in Harness Engineering.

Entscheidungen mit ihrer Begründung

Der Code zeigt, was gebaut wurde. Warum es so gebaut wurde und was verworfen wurde, zeigt er nicht. Michael Nygard hat 2011 beschrieben, was daraus folgt: Wer neu in ein Projekt kommt und die Begründung einer Entscheidung nicht kennt, kann sie nur blind hinnehmen oder blind ändern. Beides geht irgendwann schief.

Sein Vorschlag sind kurze Entscheidungsdokumente, heute meist Architecture Decision Records genannt, kurz ADR. Jedes hält eine Entscheidung fest: den Kontext, die Entscheidung selbst und ihre Folgen. Die Dateien liegen im Repository neben dem Code und werden nicht nachträglich umgeschrieben. Ändert sich eine Entscheidung, kommt ein neues Dokument dazu, das das alte ablöst. Vorlagen, Werkzeuge und Hintergrund zu ADRs sammelt die Seite adr.github.io.

Bei der Arbeit mit Agenten fallen solche Entscheidungen ständig und beiläufig, mitten in einer Sitzung. Deshalb lohnt eine Regel in der Anweisungsdatei:

Für Nicht-Techniker ist das der Teil, den du selbst lesen und beurteilen kannst. Die Entscheidungen sind in normaler Sprache geschrieben, und oft sind es geschäftliche: welcher Zahlungsanbieter, welches Limit, welcher Datenstandort.

Ist das Projekt schon weit, lassen sich die wichtigsten Entscheidungen nachtragen. Der Agent kann aus dem Repository eine Liste der Stellen erstellen, an denen eine Begründung fehlt. Die Begründungen selbst musst du liefern. Erfindet der Agent sie, steht im Repository eine plausible Geschichte, die niemand geprüft hat.

Stand und nächste Schritte

Die dritte Datei ist die unscheinbarste und hilft dir selbst am meisten. Sie beantwortet, wo das Projekt gerade steht: was zuletzt getan wurde, was angefangen und nicht fertig ist, was als Nächstes kommt und was bekannt kaputt ist.

Geschrieben wird sie am Ende jeder Sitzung, solange der Agent den Zusammenhang noch hat:

Wir arbeiten selbst so: Das Konzept dieser Serie endet mit einer Tabelle, in der der Stand jedes Teils steht.

Betrieb und Auslieferung

Die fünfte Datei beschreibt, wie die Anwendung in die Welt kommt und dort bleibt: wie ausgeliefert wird, wie man eine Auslieferung zurücknimmt, wo die Datenbank liegt, wo die Backups, welche Überwachung läuft und wer die Alarme bekommt. Vieles davon ist in den anderen Teilen der Serie schon entstanden. Das Protokoll vom Restore-Test, die Liste der Limits und die Datei mit den Zuständigkeiten gehören hierher oder werden von hier verlinkt.

Den Entwurf kann der Agent aus dem Repository ableiten. Prüfen musst du ihn, indem du ihm folgst: einmal ausliefern und einmal zurücknehmen, streng nach Anleitung, in der Testumgebung. Jede Stelle, an der du etwas aus dem Kopf ergänzt, ist eine Lücke im Text.

Was nicht ins Repository gehört

Zugangsdaten. Passwörter, API-Schlüssel und Tokens stehen in einem Passwortmanager oder im Geheimnisspeicher der Plattform, nie in einer Datei im Projekt und nie im Chat.

Ins Repository gehört dafür ein Verzeichnis der Konten, und das führst du von Hand. Es nennt für jeden Dienst, von dem die Lösung abhängt: wofür er gebraucht wird, auf wen das Konto läuft, wer Zugang hat, wo die Zugangsdaten liegen und wie man einen Schlüssel erneuert. Dazu gehören auch die unscheinbaren Dinge wie die Domain, der E-Mail-Versand und das Konto beim App-Store.

Dieses Verzeichnis ist der Teil, an dem Übergaben in der Praxis scheitern können, ohne dass eine Zeile Code fehlt. Der Code liegt vollständig vor, aber die Domain läuft auf ein privates Konto und der Zahlungsanbieter auf die E-Mail-Adresse von jemandem, der nicht mehr da ist. Ein Agent kann dir sagen, welche Dienste der Code anspricht. Wem die Konten gehören, weiß nur ein Mensch.

Die Probe mit einem frischen Agenten

Ob das alles reicht, lässt sich ausprobieren. Öffne das Repository in einer neuen Sitzung ohne jeden Verlauf, am besten mit einem anderen Werkzeug als dem, mit dem gebaut wurde, und in einem frischen Verzeichnis ohne deine lokalen Dateien.

Die Liste am Ende ist das Ergebnis. Jede Stelle, an der der Agent raten musste, ist eine Stelle, an der der Kunde, der Nachfolger oder du selbst in drei Monaten ebenfalls raten wirst. Behebe sie und wiederhole die Probe, bis die Liste kurz ist.

Zwei Grenzen hat der Test. Ein Agent kann geschickt raten und mit einer lückenhaften Anleitung weiter kommen als ein Mensch, der das Fach nicht kennt. Der Satz "Folge der Dokumentation, nicht deiner Erfahrung" mildert das, hebt es aber nicht auf. Und alles, was außerhalb des Repositorys liegt, sieht er nicht: die Konten, die Zugänge, die Absprachen mit dem Kunden.

Die Übergabe an den Kunden

Beim Kundenauftrag kommt zu den Dateien ein Termin. Was übergeben wird, lässt sich als Liste abhaken:

• das Repository mit vollständiger Historie, im Konto des Kunden
• alle Konten bei externen Diensten, auf den Kunden laufend, mit entzogenem Zugang für dich, sobald er nicht mehr gebraucht wird
• die fünf Dateien von oben und das Verzeichnis der Konten
• das Protokoll des Reviews vor dem Start und des Restore-Tests
• die Überwachung mit ihren Alarmen und den eingetragenen Empfängern
• die Limits bei den Anbietern und wer sie ändern darf

Der Termin selbst hat eine Aufgabe: Der Kunde, oder wer für ihn weitermacht, führt die Probe selbst durch, mit dem eigenen Werkzeug und den eigenen Zugängen, während du noch erreichbar bist. Klappt das, ist die Übergabe geschafft. Klappt es nicht, zeigt sich das an dem Tag, an dem es sich noch beheben lässt.

Für Auftraggeber gilt umgekehrt: Vereinbare diese Probe vorher als Teil der Abnahme. Wie die Abnahme sonst aussieht, steht im Serienteil Was ein Mensch vor dem Start prüfen muss.

Womit du heute anfängst

Mit der Probe. Sie zeigt dir in einer Stunde, wie viel von deinem Projekt nur in deinem Kopf und in alten Chats steht. Aus ihrer Liste ergibt sich, welche der fünf Dateien zuerst dran ist.

Ab der nächsten Sitzung kommt der Prompt für den Stand dazu, jedes Mal am Ende. Das kostet wenig Zeit und ist die Gewohnheit, von der du selbst am schnellsten etwas hast.