Format „Ziel → Weg": ein erklärtes Ziel, sauber gefasst. Dazu ein Weg, den Sie mit eigenen Daten prüfen.
Das erklärte Ziel#
Ein Plattformentwickler schrieb diese Woche auf LinkedIn sinngemäß: Bei uns liegen Spec und Code beieinander. Abweichungen werden direkt sichtbar und behoben. Die Doku liegt im Repository. Agenten pflegen sie bei jeder Änderung teilweise mit.
Das Ziel einer sauberen Doku ist richtig. Der Weg dorthin ist länger als der Umzug ins Repository.
Unter dem Beitrag stand die entscheidende Frage: Wer prüft, ob Spec und Code noch zusammenpassen? Ein Agent oder ein Mensch im Review?
Die Antworten darunter zeigen alle in eine Richtung. Dokumente näher an den Code. Dokumente automatisch nachziehen. Dokumente in beide Richtungen synchronisieren. Das hilft. Die Frage beantwortet es nicht.
Das Ziel sauber gefasst#
- Wer: die Entwicklungsleitung, in kleineren Firmen die Geschäftsführung.
- Was: Eine Abweichung zwischen Vorgabe und Umsetzung wird sichtbar, wenn sie entsteht. Nicht im Test, nicht bei der Abnahme, nicht im Audit.
- Bis wann: Pilot in drei Monaten (Schritt 3).
- Messgröße: der Fundort-Anteil. Von allen Abweichungen zwischen Vorgabe und Umsetzung eines Jahres: Wie viele wurden erst nach der Freigabe gefunden?
Diese Zahl liegt in Ihrem Ticketsystem. Sie erheben sie selbst. Sie brauchen dafür weder mich noch ein neues Werkzeug.
„Direkt sichtbar" ohne diese Zahl ist eine Behauptung. Mit der Zahl wird es prüfbar.
Was üblicherweise gemacht wird#
| Maßnahme | Was sie leistet | Was offen bleibt |
|---|---|---|
| Doku ins Repository | gleiche Versionierung, gleicher Review | Der Text weiß nicht, wann sich sein Gegenstand ändert. |
| Agent pflegt mit | weniger Handarbeit | Der Agent beschreibt, was gebaut wurde. Nicht, warum. |
| Synchronisation in beide Richtungen | Kopien bleiben gleich | Zwei gleiche Kopien sind noch keine Prüfung. |
| Wissensbasis im Zentrum, Code generiert | Vorgabe steht vor der Umsetzung | Ist die Wissensbasis Text, stellt sich dieselbe Frage eine Ebene höher. |
Jede dieser Maßnahmen wird zum Test, sobald jemand den Fundort-Anteil vorher und nachher misst. Ohne Messung bleibt sie eine Behauptung.
Allen gemeinsam ist eines: Die Begründung bleibt Text neben dem Gegenstand. Ein Text hat keine Verbindung zu dem, was er beschreibt. Ändert sich der Gegenstand, meldet der Text nichts. Prüfen kann dann nur, wer beides liest und vergleicht. Das ist ein Mensch mit Zeit. Oder ein Sprachmodell mit Wahrscheinlichkeit.
Doku veraltet nicht, weil sie im falschen Werkzeug liegt. Sie veraltet, weil sie eine Kopie ist.
Wo das Warum wirklich sitzt#
Eine Unterscheidung, die sich bei mir über die Jahre gehalten hat:
- Wissen heißt, einen Baustein zu kennen.
- Know-how heißt, die Verbindungen und die Auswirkungen zu kennen. Welche Stelle dreht man, damit sich was wie verändert?
- Fähigkeit heißt, diesen Pfad nachweislich bedient zu haben.
Das Warum einer Anforderung steckt fast nie im Baustein selbst. Es steckt in der Verbindung. Diese Funktion gibt es, weil sie ein Ziel für einen benannten Adressaten verfeinert. Diese Lösung gibt es, weil sie die Funktion realisiert. Dieses Merkmal gibt es, weil es die Funktion misst. Diese Randbedingung gilt für genau diese Funktion.
Legen Sie die Begründung an die Verbindung, ändert sich die Mechanik:
- Jede Verbindung hat einen Typ, eine Herkunft und einen Status: bestätigt, abgeleitet oder offen.
- Ändert sich ein Baustein, fallen seine Verbindungen auf offen. Das entscheidet eine Regel, kein Modell. Niemand muss daran denken.
- Ein Mensch bestätigt die Verbindung neu oder passt sie an. Ein Agent darf vorschlagen. Bestätigen darf er nicht.
- Die Doku ist eine Sicht über Bausteine und Verbindungen. Sie wird erzeugt, nicht gepflegt.
Damit ist die Frage aus dem Kommentar beantwortet. Den Bruch meldet die Maschine, deterministisch. Ob die Begründung noch trägt, entscheidet ein Mensch. Er vergleicht dafür keine zwei Texte. Er sieht genau die Verbindungen, die offen sind.
Die Lücke zwischen dem bestätigten und dem aktuellen Stand ist damit sichtbar. Das ist kein Nebeneffekt. Das ist der Zweck.
Der Weg in drei Schritten#
Schritt 1: Fundort messen#
- Prüfschritt: Ziehen Sie aus dem Ticketsystem alle Abweichungen zwischen Vorgabe und Umsetzung der letzten 12 Monate. Ordnen Sie jede ihrem Fundort zu: bei der Änderung, im Review, im Test, bei der Abnahme, im Feld, im Audit.
- Messgröße: Anteil der Funde nach der Freigabe.
- Trennschärfe: Liegt der Großteil bei Änderung und Review, sehen Sie Abweichungen schon früh. Liegt er nach der Freigabe, weiter mit Schritt 2.
- Abbruch: Überwiegen die frühen Funde, endet die Prüfung hier. Dann ist die Doku nicht Ihre Baustelle.
Schritt 2: Ursache trennen#
Nehmen Sie 10 bis 20 späte Funde. Stellen Sie je Fund drei Fragen:
- Gab es die Vorgabe schon vor der Umsetzung?
- War die Begründung irgendwo festgehalten?
- Hat bei der Änderung etwas oder jemand gemeldet, dass die Vorgabe betroffen ist?
Trennschärfe:
- Vorgabe fehlte: Die Reihenfolge stimmt nicht. Steht die Vorgabe nicht vor der Umsetzung, beschreibt jede Doku nur, was gebaut wurde. Verbindungen helfen hier noch nicht.
- Vorgabe und Begründung da, aber keine Meldung: Die Verbindung fehlt. Das ist der Fall für Schritt 3.
- Meldung kam, niemand hat reagiert: Es fehlt Kapazität oder ein Entscheider. Verbindungen erzeugen dann nur mehr ungelesene Meldungen.
Abbruch: Überwiegt der erste oder der dritte Fall, ist Schritt 3 nicht Ihr Hebel. Klären Sie zuerst die Reihenfolge oder die Entscheidung.
Schritt 3: Pilot an einem Baustein#
- Maßnahme: Führen Sie für eine Baugruppe oder ein Modul die Begründungen als Verbindungen. Für den Pilot reicht eine Tabelle: Quelle, Ziel, Typ, Begründung, Status, Datum. Dazu eine Regel: Jede Änderung an Quelle oder Ziel setzt den Status auf offen. In der Software leistet das ein Commit-Hook. In der Mechanik leistet es der Änderungsprozess.
- Messgröße: Fundort-Anteil des Pilotbausteins gegen die Baseline aus Schritt 1.
- Frist: drei Monate.
- Abbruch: Sinkt der Anteil später Funde nicht, war die fehlende Verbindung nicht die Ursache. Abbruch auch dann, wenn offene Verbindungen gesammelt und ungeprüft wieder bestätigt werden. Dann wird abgenickt, nicht geprüft.
Als Prüfsatz: Ist die fehlende Verbindung die Ursache, senkt die Verbindung mit Status den Anteil spät gefundener Abweichungen am Pilotbaustein innerhalb von drei Monaten. Sinkt er nicht, suchen Sie weiter.
Was es kostet, nichts zu tun#
Späte Funde bleiben spät. Das Warum bleibt in einzelnen Köpfen und geht mit ihnen. Mit Agenten wird schneller geändert. Bleibt das Verfahren gleich, wächst mit jeder Änderung der Abstand zwischen Vorgabe und Umsetzung.
So mache ich das in OTSM#
Anbieteraussage: OTSM ist mein eigenes Werkzeug.
- Verbindungen liegen in OTSM als eigene Datensätze mit Typ, Herkunft, Bestätigung und Begründung. Nicht als Text neben dem Baustein.
- Funktionale Abhängigkeiten setze ich nicht von Hand. Sie entstehen aus der Fehlerverknüpfung. Wie das funktioniert, steht in Drei Traces. Immer.
- Wird ein Systemelement verschoben, brechen die Fehlerketten, die nur der Strukturbaum getragen hat. Ketten ohne Deckung zeigt das Netz als offen. Gelöscht wird nur nach Bestätigung.
- Die Doku ist eine Sicht über diese Daten.
Prüfweg: Den Mechanismus zeige ich am Referenzsystem, auf Anfrage live. Messwerte zur Wirkung bei Kunden habe ich noch nicht. Messen Sie Ihren Fundort-Anteil. Dann reden wir über Ihre Zahl, nicht über meine.