Die Entwicklung lässt sich nicht einfach pausieren. Das ist die erste Erkenntnis, die man akzeptieren muss. Tickets treffen ständig ein, Kunden erwarten Lieferungen

Man kann die Entwicklung nicht einfach pausieren. Das ist das Erste, was man akzeptieren muss. Tickets treffen ständig ein, Kunden erwarten Lieferungen, und Ihr bestehender Code hört nicht auf zu laufen, nur weil Sie beschlossen haben, ihn zu dokumentieren. Kein Engineering Manager wird einen einmonatigen Stillstand genehmigen, damit das Team die Spezifikation schreibt, die eigentlich vom ersten Tag an hätte existieren sollen. OpenSpec wurde für die Realität entwickelt, nicht für Greenfield-Fantasien. Es funktioniert am besten, wenn man es an das anbaut, was man bereits hat – inklusive der Kunden.

Das Ziel ist hier kein Rewrite. Es ist ehrliche Archäologie. Sie graben das aus, was tatsächlich in der Produktion läuft, beschreiben es genau und lassen diese Beschreibung mit Ihrem Code mitwachsen. Wenn Ihre Spezifikation mit Ihrem System übereinstimmt, machen Sie das Leben für die Ingenieure einfacher, die im nächsten Quartal dazustoßen, und für die KI-Tools, die nun in Ihrer IDE sitzen. Hier ist die Anleitung, wie Sie das schaffen, ohne eine einzige Veröffentlichung zu verpassen.

Beginnen Sie mit dem, was Sie tatsächlich tun

Öffnen Sie Ihr Repository, und Sie werden Ordner mit den Namen controllers, models, services und utils sehen. Das sind technische Schichten, und sie belügen Sie. Sie beschreiben nicht, was Ihr System für das Geschäft tut. Ein Ordner voller JavaScript-Dateien erklärt nicht, wie aus einer Bestellung eine Lieferung wird. Um OpenSpec nachträglich zu implementieren, müssen Sie in Fähigkeiten (Capabilities) denken.

Suchen Sie nach den stabilen Geschäftsprozessen, die überleben würden, selbst wenn Sie den gesamten Stack in einer anderen Sprache neu schreiben würden. In den meisten Produktunternehmen tauchen diese immer wieder auf: Bestellungen, Abrechnung, Inventar, Kunden und Benachrichtigungen. Benennen Sie fünf bis acht dieser Kernfähigkeiten.

Beantworten Sie für jede dieser Fähigkeiten fünf spezifische Fragen. Welches reale Problem löst diese Fähigkeit? Wo befindet sich der Code tatsächlich – in einem Service, drei Microservices oder einem Legacy-Modul, das niemand anfassen will? Was löst sie aus: ein Benutzerklick, ein geplanter Cronjob, ein eingehender Webhook? Welche Daten fließen hinein und welche fließen heraus? Und schließlich: Welche anderen Systeme hängen davon ab – das heißt, was geht kaputt, wenn dieses Teil aufhört zu funktionieren?

Seien Sie schonungslos ehrlich. Wenn Ihre „Kunden“-Fähigkeit über einen Rails-Monolithen, eine Node-API und ein externes CRM verteilt ist, schreiben Sie das genau so auf. Ihre Karte muss wie das Gelände aussehen, nicht wie der Traum eines Architekten.

Schreiben Sie die Wahrheit, nicht die Wunschliste

Der gefährlichste Satz in jedem Dokumentationsprojekt lautet: „Während wir das sowieso aufschreiben, können wir es auch gleich reparieren.“ Stopp. Sie gestalten den Checkout-Prozess nicht neu. Sie beschreiben den Checkout-Prozess, der gerade echte Kreditkarten abrechnet.

Wenn eine Bestellung eine sofortige Zahlungsabwicklung auslöst und dann eine E-Mail über einen Background-Worker versendet, dokumentieren Sie genau diese Sequenz. Fügen Sie keine Event-Queue ein, die Sie erst im nächsten Quartal hinzufügen wollen. Tun Sie nicht so, als fände die Validierung an der API-Edge statt, wenn sie in Wirklichkeit tief in einer Service-Klasse sitzt. Genauigkeit ist weitaus wichtiger als Ambition.

Falsche Dokumentation ist schlimmer als gar keine. Sie bringt neue Mitarbeiter dazu, ein Verhalten zu erwarten, das nicht existiert. Sie führt KI-Coding-Assistenten auf imaginäre Pfade, die auf Wunschdenken basieren. Wenn Ihre Spezifikation mit der Produktion übereinstimmt, schaffen Sie eine zuverlässige Basis. Das Debugging wird schneller, weil Sie aufhören, über den „beabsichtigten“ Ablauf zu rätseln. Das Refactoring wird sicherer, weil Sie wissen, dass der Ausgangspunkt real ist.

Extrahieren Sie Verträge aus Ihren APIs

Ihre API-Endpunkte erzwingen bereits Regeln. Sie halten sie nur implizit. OpenSpec nachträglich zu implementieren bedeutet, diese Regeln offen zu legen.

Beginnen Sie mit Inputs und Validierung. Was akzeptiert der Endpunkt tatsächlich? Dokumentieren Sie die Typen, die Pflichtfelder, die maximalen Längen und die Abhängigkeiten zwischen den Feldern. Beschreiben Sie dann das geschäftliche Verhalten. Erzeugt dieser Aufruf einen Datensatz, löst er einen Side Effect aus oder validiert er lediglich einen Zustand gegenüber einem anderen Service? Seien Sie spezifisch.

Katalogisieren Sie schließlich die Antworten. Was gibt ein Erfolg zurück? Wie lauten die genauen Fehlercodes und unter welchen Bedingungen treten sie auf? Schreiben Sie nicht „gibt einen Fehler zurück“. Schreiben Sie „gibt 422 zurück, wenn die Rechnungsadresse fehlt, und 409, wenn der Lagerbestand bereits durch einen anderen Prozess reserviert wurde“. Dieses Maß an Präzision verwandelt eine vage Route in einen Vertrag, dem Frontend-Teams, QA-Ingenieure und automatisierte Tools vertrauen können.

Spüren Sie die verborgenen Regeln auf

Ein Teil des kostspieligsten Wissens in Ihrem System verbirgt sich in den Lücken. Es ist in bedingten Blöcken innerhalb von Service-Klassen vergraben, in Datenbank-Triggern versteckt oder in Stored Procedures geschrieben, die seit zwei Jahren niemand mehr angefasst hat. Das sind Ihre Geschäftsregeln, und sie werden meist erst während eines Ausfalls oder dadurch wiederentdeckt, dass man den einen Ingenieur ausfindig macht, der von Anfang an dabei war.

Holen Sie diese ans Licht. Beginnen Sie mit denen, die Sie bereits kennen. Bestellungen über einem bestimmten Wert benötigen die Genehmigung eines Managers, bevor sie bearbeitet werden. Inaktive Benutzerkonten können keine neuen Bestellungen erstellen. Rückerstattungen sind nur zulässig, bevor die Abrechnung abgeschlossen ist. Schreiben Sie jede Regel neben die Funktion, die sie steuert, in einer Sprache, die so klar ist, dass ein Produktmanager sie ohne Übersetzer lesen könnte.

Wenn Sie diese Regeln zentralisieren, tun Sie mehr als sie nur zu dokumentieren. Sie machen Duplikate sichtbar. Sie decken Konflikte auf. Und Sie geben dem gesamten Team einen zentralen Ort, um Richtlinien zu diskutieren, bevor jemand eine einzeilige Änderung committet, die versehentlich eine Einschränkung verletzt, von deren Existenz Sie vergessen hatten.

Die Infrastruktur kartieren

Moderne Systeme basieren auf Ereignissen. Eine Aktion in einem Service wirkt sich auf ein halbes Dutzend andere aus, bevor etwas Sichtbares beim Benutzer ankommt. Sie müssen diese Auswirkungen kartieren. Bilden Sie den Fluss von einem Ereignis zum nächsten für Ihre Kern-Workflows ab. „Bestellung erstellt“ führt zu „Lagerbestand reserviert“, was wiederum auf „Zahlung bestätigt“ wartet. Zeichnen Sie die gesamte Kette, auch wenn sich einige Verbindungen instabil anfühlen oder unterschiedliche Protokolle verwenden.

Halten Sie nicht bei internem Datenverkehr an. Externe Dienste sind Teil Ihres Systems, egal ob Sie das so behandeln oder nicht. Halten Sie für jede Integration deren Zweck fest, wie sich Ihre Anwendung authentifiziert und wie sie im Fehlerfall reagiert. Löst das Payment-Gateway nach dreißig Sekunden ein Timeout aus und gibt einen generischen 500-Fehler zurück? Liefert die Versand-API am Wochenende fehlerhaftes JSON? Entzieht der Identity Provider Refresh-Token früher, als es seine eigene Dokumentation behauptet? Diese Details wirken trivial