Die SDK-Ordnerstruktur auf Papier skizzieren

Eine agentengebaute Codebasis wird entweder in drei Monaten zu Brei oder bleibt jahrelang kohärent - und der Unterschied wird entschieden, bevor eine einzige Zeile geschrieben ist. RakuAI zeichnete zuerst die Kästchen, damit die Agenten immer am richtigen Ort landen.

Es gibt eine Art von Design-Arbeit, die von außen unsichtbar und von innen tragend ist. Die Ordnerstruktur einer Codebasis ist eines dieser Dinge. Sie sieht wie Dateiverwaltung aus. Sie ist tatsächlich das Organigramm des Codes. Richtig hinbekommen, früh, und jeder PR für die nächsten zwei Jahre landet am richtigen Ort. Falsch gemacht, früh, und jeder PR für die nächsten zwei Jahre muss darüber streiten, wohin er gehört.

Dieser Samstag ging darin auf, es früh richtig hinzubekommen.

Was die Struktur unterstützen muss

Bevor ich Kästchen zeichnete, habe ich eine Liste von Einschränkungen aufgestellt, die die Struktur erfüllen muss.

Jede Demo bekommt ihr eigenes Zuhause. Die acht Demos, die ich letzten Monat spezifiziert habe, brauchen jeweils einen Ordner, in dem ihr Code, ihre Assets und ihre Docs zusammenleben. Ein Entwickler, der eine der Demos liest, sollte nicht durch vier verschiedene Teile des SDK springen müssen, um sie zu verstehen.

Gemeinsame Module sind von den Demos trennbar. Alles, was über Demos hinweg wiederverwendet wird (HUD-Rendering, Gesten-Input, Blickverfolgung, Multiplayer-Sync, Sprachsteuerung, visuelle Effekte), lebt an seinem eigenen Ort und wird von den Demos über eine öffentliche Oberfläche konsumiert.

Assets sind nach Typ organisiert, nicht nach Demo. Ein Lebensbalken-PNG ist ein HUD-Widget, kein Arena-Demo-Asset. Wiederverwendbare visuelle Assets leben in einem gemeinsamen Assets-Ordner, und die Demos, die sie brauchen, verlinken darauf.

Docs sind dort angesiedelt, was sie beschreiben. Das SDK-Installationsdokument liegt neben dem SDK. Der Demo-Guide liegt neben den Demos. Das HUD-API-Dokument liegt neben dem HUD-Modul. Die Auffindbarkeit von Docs hängt größtenteils vom Doc-Standort ab.

Config ist ein eigenes Anliegen. Die HUD-Konfigurationsdateien, die Standard-Layouts, die Multiplayer-Rollenkonfigurationen. Das ist kein Code, keine Assets, keine Docs. Sie bekommen ihr eigenes Zuhause.

Die Struktur

Nach einem Vormittag Whiteboarding sieht das Layout so aus.

Der Wurzelordner ist das SDK selbst. Darunter:

/apps/ ist, wo die Demos leben. Jede Demo bekommt einen Unterordner. arena_demo/ für Solo-Arena. coach_demo/ für AR-Coaching. hud_designer/ für den HUD-Overlay-Designer. streamer_demo/ für den Streamer-Modus. pos_demo/ für das Point-of-Service-Overlay. companion_demo/ für das AR-Companion-HUD. aimlab_demo/ für den AR-Zieltrainer. hudsync_demo/ für den Multiplayer-HUD-Sync. Jeder Demo-Ordner enthält seinen eigenen Quellcode, seine eigene Konfiguration, seine eigenen demo-spezifischen Assets und seine eigene README.

/modules/ ist, wo der gemeinsame Code lebt. Zu Beginn sechs Module. Der HUD-Renderer, den jede Demo konsumiert. Gesten-Input-Erkennung, die die meisten Demos konsumieren. Blickverfolgung, verwendet von den Demos, die sie brauchen. Multiplayer-Sync, verwendet von den LAN-Multiplayer-Demos. Der Overlay-Animator für visuelle Effekte. Die Sprachsteuerungs-Schnittstelle für die Demos, die Sprach-Input annehmen. Jedes Modul stellt eine kleine, stabile öffentliche Oberfläche bereit, an die die Demos anknüpfen.

/assets/ ist die gemeinsame Asset-Bibliothek. HUD-Widgets (Lebensbalken, Munitionszähler, Kompass-Overlays) als PNG und SVG. Audioeffekte für Treffer, Alarme, Voiceovers. Gesten-Icons, die dem Nutzer zeigen, wenn eine Geste erkannt wurde. Demos verlinken hier auf Assets, statt sie zu duplizieren.

/docs/ ist das Dokumentations-Zuhause. Eine README, die das SDK vorstellt und durch die Installation führt. Ein Demo-Guide, der erklärt, wie man jede der acht Demos ausführt. Eine API-Referenz für das HUD-Modul. Eine API-Referenz für das Sprachsteuerungs-Modul. Die Docs sind bewusst so angesiedelt, dass ein Entwickler, der wissen will, wie das HUD funktioniert, den Quellcode und das Dokument im selben Ordner lesen kann.

/config/ ist Konfiguration. Das Standard-HUD-Layout, das als Ausgangspunkt für neue Projekte verwendet wird. Beispiel-Layouts, exportiert aus dem HUD-Designer. Multiplayer-Rollendefinitionen. Config vom Code getrennt zu halten hält die Demos sauber und lässt einen Entwickler das Verhalten ändern, ohne neu zu kompilieren.

Die Stubs

Eine Ordnerstruktur für sich ist nur ein leeres Dateisystem. Das andere, was ich heute entworfen habe, ist eine Reihe von Code-Stubs, die den Agenten (wenn sie irgendwann anfangen, Code gegen diese Struktur zu schreiben) zeigen, wie eine echte Implementierung an jedem Einstiegspunkt aussehen sollte.

Die Stubs sind vorerst in Python-Pseudocode. Sie werden in die Produktionssprache übersetzt (C++ für die Runtime, mit Bindings nach Python und andere Ökosysteme), sobald das Engine-Repo öffnet. Die Python-Form ist das, was mich über die Schnittstellen nachdenken lässt, ohne mich in Implementierungsdetails zu verlieren.

Ein Beispiel-Stub, für das Gesten-Input-Modul. Ungefähr:

def detect_gesture(frame):
    """Detect gestures like swipe, point, raise, duck in a single sensor frame."""
    if is_swipe(frame):
        return "swipe"
    elif is_raise(frame):
        return "raise_arm"
    else:
        return None

Das ist nicht der Produktionscode. Es ist der Vertrag. Der Produktionscode wird is_swipe und is_raise durch echte Computer-Vision-Pipelines ersetzen. Die Schnittstelle bleibt gleich. Die Signatur ist das, wogegen die Demos programmieren werden. Die Signatur früh festzulegen bedeutet, dass ich die Demos ausliefern kann, bevor die CV-Pipeline kugelsicher ist, weil die Demos nicht von der Implementierung abhängen, sondern von der Schnittstelle.

Ich habe Stubs dieser Art für jedes Modul im /modules/-Ordner entworfen. Sechs kleine Python-Dateien. Keine davon implementiert etwas. Alle definieren den Vertrag, den die eventuellen Implementierungen einhalten müssen.

Warum die Agenten das brauchen

Das ist die Verbindung zurück zum Agentenaufgebot von vor ein paar Samstagen.

Wenn die Zeit kommt, den echten Code zu schreiben, werden die Agenten die Architektur nicht erfinden. Die Architektur steht auf Papier. Die Ordnerstruktur sagt ihnen, wohin der neue Code geht. Die Modul-Stubs sagen ihnen, welche Schnittstelle zu implementieren ist. Die Asset-Organisation sagt ihnen, wo sie nach den Dingen suchen sollen, die sie brauchen. Die Docs-Struktur sagt ihnen, wo sie die Docs ablegen sollen, die sie schreiben.

Das ist der Unterschied zwischen einer agentengebauten Codebasis, die nach drei Monaten zu Brei wird, und einer, die jahrelang kohärent bleibt. Die Struktur ist die Disziplin. Die Agenten erben die Disziplin durch die Struktur.

Ohne diese Vorarbeit würde ein Agent, der gebeten wird, „Gesten-Input zu implementieren”, einen Ordner erfinden, eine API erfinden, den Code schreiben und etwas produzieren, das isoliert funktioniert. Multipliziert über sechs Module produziert dieser Ansatz sechs inkompatible Mini-Engines. Die Struktur verhindert diesen Fehlermodus, indem sie die Kästchen zeichnet, in die die Agenten schreiben müssen.

Was daran schwierig ist

Ein paar ehrliche Dinge.

Ordnerstrukturen wollen wachsen. In sechs Monaten werde ich ein siebtes Modul hinzufügen wollen. Die Struktur muss das erlauben, ohne zur Krimskrams-Schublade zu werden. Die Regel, die ich mir selbst auferlege: Jeder neue Top-Level-Ordner muss rechtfertigen, warum er kein Unterordner eines bestehenden ist. Die meisten neuen Dinge stellen sich als Unterordner heraus.

Die Stubs brauchen Pflege. Während die echten Implementierungen landen, werden die Stubs veraltet. Die Agenten, die die Stubs als „den Vertrag” lesen, erben jede Drift zwischen Stub und echter Implementierung. Die Lösung ist, die Stubs zur Quelle der Wahrheit zu machen und zu verlangen, dass die echten Implementierungen sie aktualisieren, wenn sich der Vertrag ändert.

Manche dieser Ordner sind spekulativ. Der /config/-Ordner ist eine Wette darauf, dass Runtime-Konfigurationsdateien in diesem SDK eine echte Artefaktkategorie sein werden. Wenn sich herausstellt, dass sie es nicht sind, schrumpft der Ordner oder verschmilzt mit etwas anderem. Damit bin ich einverstanden. Es ist billiger, einen Ordner später zu entfernen, als in einem Jahr einen zu erfinden, wenn die Konvention schon abgedriftet ist.

Was als Nächstes kommt

Der nächste Samstag ist das API-Oberflächen-Design. Jedes der sechs oben genannten Module braucht seine öffentliche Oberfläche spezifiziert. Das bedeutet, zu entscheiden, welche Datentypen die Grenze überqueren, welche Fehlercodes zurückgegeben werden, welche Events ausgelöst werden. Mit der fertigen Ordnerstruktur hat das API-Design einen Ort, an dem es landen kann.

Danach kommt die demo-für-demo-Spezifikation, welche Module jede Demo konsumiert und in welcher Reihenfolge. Dann die Runtime-Architektur. Dann, endlich, öffnet das Engine-Repo.

Der Patentbestand wartet seit einem Jahrzehnt. Ein paar weitere Wochen Design-Arbeit, um es richtig hinzubekommen, werden nicht das sein, was uns das Zeitfenster kostet.

Ordnerstruktur fertig. Die Codebasis hat jetzt eine Form, auch wenn noch kein Code darin ist.