𝗠𝗲𝗶𝗻𝗲 𝗥𝗘𝗔𝗗𝗠𝗘 𝘀𝗮𝗴𝘁𝗲 𝟴𝟬 𝗧𝗼𝗼𝗹𝘀. 𝗠𝗲𝗶𝗻 𝗖𝗼𝗱𝗲 𝗵𝗮𝘁𝘁𝗲 𝟵𝟲. 𝗡𝗶𝗲𝗺𝗮𝗻𝗱 𝗵𝗮𝘀𝘁 𝗪𝗼𝗰𝗵𝗲𝗻𝗹𝗮𝗻𝗴𝗲 𝘂𝗻𝗯𝗲𝗮𝗰𝗵𝘁𝗲𝗱.
Ich leite ein Open-Source-Projekt. Es nutzt Browser-Automatisierung für KI-Agenten.
In meiner README stand, dass das Projekt 80 Tools besitzt. Ich habe diese Zahl im Slogan, in der Navigation und in den Social-Media-Texten verwendet.
Letzte Woche habe ich ein Audit durchgeführt. Ich habe meine README mit meinem tatsächlichen Code verglichen.
Der Code registrierte 96 Tools.
Ich hatte drei verschiedene Wahrheiten in einer einzigen Datei:
- Die Marketing-Zahl: 80
- Die dokumentierte Liste: 83
- Der tatsächliche Code: 96
Dreizehn Tools waren völlig undokumentiert. Die Nutzer wussten nicht einmal, dass sie existierten.
Der gefährlichste Teil war die Lücke. Vier dieser undokumentierten Tools waren High-Level-System-Tools. Sie nutzten Ereignisse auf Betriebssystemebene, um Tastatur und Maus zu steuern. Das ist der leistungsstärkste und sensibelste Teil meines Projekts.
Das hat mich eine harte Lektion über Documentation Drift gelehrt.
Drift ist nicht zufällig. Er ist voreingenommen. Man dokumentiert die einfachen, langweiligen Dinge. Man vergisst, die neuen, leistungsstarken oder sensiblen Tools zu dokumentieren, die man in Eile veröffentlicht.
Wenn du den riskantesten Teil eines Projekts finden willst, lies nicht die Dokumentation. Schau dir die Lücke zwischen der Dokumentation und dem Code an.
Ich habe versucht, die Zahl zu korrigieren. Das war ein Fehler. Die Zahl zu korrigieren, bekämpft nur das Symptom.
Das Problem ist die manuelle Wartung. Wenn ein Mensch einen Fakt eintippt, wird dieser Fakt irgendwann falsch sein.
Die einzige echte Lösung besteht darin, es unmöglich zu machen, die Zahl falsch anzugeben.
Man muss Fakten aus der Source of Truth ableiten.
Mein Projekt hatte bereits eine Lösung: den Smoke-Test. Der Test fragt den Server, wie viele Tools er hat, und prüft die Anzahl. Er verwendet keine hartcodierte Zahl. Der Test kann niemals abweichen, da er niemals eine statische Zahl speichert.
Hör auf zu versuchen, disziplinierter beim Schreiben zu sein. Disziplin versagt. Automatisiere stattdessen deine Fakten:
- Generiere Zählungen per Skript zur Build-Zeit.
- Generiere Tool-Listen direkt aus deiner Code-Registry.
- Nutze Menschen nur für die Prosa und Erklärungen.
Wenn ein Fakt ableitbar ist, tippe ihn nicht von Hand ein. Er ist nur ein drohender Drift.
Führe dieses Audit noch heute in deinem eigenen Projekt durch:
- Zähle die tatsächlichen Elemente in deinem Code.
- Zähle das, was deine Dokumentation behauptet.
- Wenn sie voneinander abweichen, finde heraus, was sich in dieser Lücke befindet.
Die Elemente in der Lücke sind meistens die wichtigsten Teile deines Projekts.
Optionale Lern-Community: https://t.me/GyaanSetuAi