Eine Spec, sie alle zu knechten: eine einzige Quelle der Wahrheit für Firmware, Tests und Doku

Agentic Engineering ist eine Software Entwicklungsdisziplin, in der Menschen Ziele, Randbedingungen und Qualitätsstandards definieren, während AI Agenten Code autonom planen, schreiben, testen und weiterentwickeln, unter strukturierter menschlicher Aufsicht.

Als methodische Basis dafür nutzen wir Spec Driven Development (SDD), ein Vorgehen, das Spezifikationen als ausführbare Verträge behandelt und aus ihnen den Code ableitet. Den methodischen Vergleich mit Wasserfall, Scrum® und SAFe® haben wir in einem eigenen Artikel zusammengefasst: Spec Driven Development, Scrum, SAFe und Wasserfall — was wann taugt →

Die konkrete Form, die wir für unsere Embedded Geräte gewählt haben, ist eine Single Source of Truth (SSOT) in JSON, aus der Firmware, Tests und Handbuch generiert werden. Dieser Artikel beschreibt, wie das in der Praxis aussieht.

Die folgenden Erfahrungen basieren auf Claude™ Opus 4.7 mit 1 M Kontextfenster, betrieben im Modus high bis max.

Die Architektur in einem Bild

Ein schlanker Nachrichtenbus (nicht viel mehr als ein Postfach pro Rolle, mit Persistenz) verbindet mehrere AI Instanzen. Zusammen fahren sie einen weitgehend autonomen Zyklus aus Firmware, Test und Interface Dokumentation für unsere Embedded Geräte.

Wir besetzen fünf Rollen, alle durch AI Instanzen:

• Domain Experte / Spec Owner: besitzt den Vertrag und ist der einzige, der ihn ändert.
• Firmware Entwickler: implementiert gegen den generierten Code und schreibt den Generator für seinen Code (Header Files) selbst.
• Testagent: schreibt die Tests selbst, fährt die Hardware-in-the-Loop Durchläufe und triagiert jeden Fehlschlag gegen die Spec.
• Doku und Tooling: pflegt die Generatoren, das Handbuch und die Build- und Testpipeline.
• Monitor: hat den Bus implementiert und überwacht das System. Wir nutzen ihn, um zu analysieren, wo das Messaging klemmt, und um Rollen bei Bedarf zu verfeinern.

Der Mensch sitzt ausserhalb des Zyklus. Ziel ist, ihn so weit wie möglich aus der Schleife herauszunehmen. Er greift ein, wenn etwas klemmt, und entscheidet bei den Fragen, die delegiert nicht beantwortet werden können: Architektur, Kundenwünsche, Priorisierung, letzte Freigabe.

In der Realität gibt es zusätzlich genug Überraschungen, die einen ungefragt wieder an die Tastatur holen: Windows® bootet den Host neu, Claude hat einen Ausfall, die Credits sind aufgebraucht, oder der Tortoise Cache läuft mal wieder Amok und friert das System mit seiner wilden Indexiererei ein.

Das Problem: drift

Ein Embedded Gerät hat ein Interface, eine Liste von Werten mit Adresse, Typ, erlaubtem Bereich, Default und Bedeutung. Dieser Vertrag muss an drei Stellen gleichzeitig wahr sein: in der Firmware, in den Tests und im Handbuch.

In normaler Praxis driften diese drei Kopien fast sofort auseinander. Jemand erweitert einen Wertebereich in der Firmware. Das Handbuch zeigt den alten Bereich. Ein Test prüft das alte Maximum und schlägt aus dem falschen Grund fehl. Nach einem halben Jahr ist niemand mehr sicher, welche der drei Stellen recht hat.

Die einzige dauerhafte Heilung: nicht drei Kopien pflegen, sondern eine.

Die SSOT in JSON

Der Interface Vertrag liegt in einer einzigen, versionierten JSON Datei. Jede Änderung ist über die Versionshistorie genau nachvollziehbar. Jeder Wert ist genau einmal definiert und trägt alles, was weiter unten gebraucht wird: Adresse, Datentyp, erlaubter Bereich, benannte Zustände, Zugriffsregeln (read-only, read/write, geschützt), Einschaltwert und Klartextbeschreibung.

JSON, weil eine Maschine es direkt lesen kann. Menschenlesbar wird die Spec dadurch, dass aus ihr automatisch eine vollständige Interface Referenz für das Handbuch generiert wird. Es gibt also nicht zwei Formate (eines für Maschinen, eines für Menschen), sondern ein Format und einen Generator.

Was generiert wird

Aus der Datei regenerieren wir bei jeder Änderung:

• Firmware Code: Tabellen für jeden Wert mit Bereich, Zuständen, Zugriffsregeln und Default. Keine Hand-Adressen, keine Magic Numbers; die Read-, Write- und Validate-Pfade laufen über die generierten Tabellen.
• Hostseitiger Treiber: Tools und Tests sprechen über dieselben Definitionen mit dem Gerät.
• Testerwartungen: Bereiche, Defaults, benannte Zustände und Zugriffsregeln kommen aus der Spec. Ein Test kann nichts prüfen, was die Spec nicht definiert.
• Kundenhandbuch: vollständige Interface Referenz, in der Mastersprache plus einseitige Übersetzungen in 28 Zielsprachen.

Die Spec ist nicht von Anfang an fehlerfrei. Ein falscher Bereich, ein vergessener Zustand, eine unklare Beschreibung gehört zum Iterationsalltag. Solche Fehler werden in der Spec behoben, danach wird alles darunter neu generiert. Mit zunehmender Reife passiert das immer seltener.

Der Mensch muss die JSON Datei nicht von Hand pflegen, dazu reicht ein Auftrag an den Domain Experten / Spec Owner. Und in der generierten Dokumentation ist alles menschengerecht aufgearbeitet und lässt sich ausgiebig reviewen.

Testen auf echtem Target

Jede Iteration wird auf echter Hardware getestet, ein Aufbau, den man Hardware-in-the-Loop (HIL) nennt. Grund: Timing- und Nebenläufigkeitsfehler zeigen sich nur dort. Das Target in seiner kompletten Hardware zu simulieren ist nur in Teilen möglich, also ist der einfachste Weg, gleich auf dem echten Gerät zu laufen.

Die Agenten haben aber zusätzlich Skills für die Vorklärung: statisch Code analysieren, lokal auf dem Host Scripts ausführen, gegen eine Simulation des Geräts laufen. Vieles wird so vorab geklärt; nicht jede Frage muss aufs Target. Für die abschliessende Prüfung gilt aber: das Silizium ist der Richter, und es wird gegen die Spec gemessen.

Audit Gates: der Build stoppt bei Drift

Generierung allein reicht nicht. Jemand kann von Hand Drift einbauen, also bricht der Build (nicht nur die Tests) bei Verstössen ab:

• keine von Hand geschriebenen Adressen oder Magic Numbers in der Firmware,
• kein Symbol im Code ohne Eintrag in der Spec, und umgekehrt,
• gemeinsame Definitionen konsistent über alle Produktvarianten,
• Schutz- und Zugriffsregeln in der Firmware passen zu dem, was die Spec deklariert.

Die Prüfungen sind langweilig. Genau das ist der Punkt. Aus “bitte alle synchron halten” wird “der Build geht nicht weiter, wenn nicht”.

Dabei muss man ein Mittelmass finden zwischen Iterationsgeschwindigkeit und Qualität. Meine Lieblingsanweisung an die Agenten dazu: Wir schneiden alte Zöpfe ab. Und zwar jetzt. Diese Anweisung steht für den Agenten natürlich im klaren Widerspruch zu der ebenso gültigen Regel “die Codebasis ist stabil und reif, wir machen nur minimale Änderungen”. Mit beiden gleichzeitig leben zu müssen, ist Teil des Jobs, für Menschen wie für Agenten.

Die Spec gewinnt

Wenn Verhalten und Spec nicht übereinstimmen, ist das ein Fehler in der Firmware oder ein Fehler in der Spec, nie eine Erlaubnis, den Test still anzupassen. Die Korrektur fliesst immer in eine Richtung:

Spec ändern → regenerieren → bauen → flashen → HIL Durchlauf.

Diese Regel ist es, die die Quelle der Wahrheit über Jahre tatsächlich wahr hält. Sie macht auch die Mehrsprachigkeit zum Nicht-Ereignis: Mastersprache einmal pflegen, Übersetzung fliesst einseitig.

In der Praxis läuft eine Spec-Anpassung wie folgt ab. Die Agenten kommunizieren in natürlicher Sprache miteinander. Der Firmware Entwickler stösst zum Beispiel auf einen Registerwert, dessen Verhalten der Testagent als nicht korrekt einstuft. Auf Nachfrage erklärt der Firmware Entwickler seine Implementierung, gemeinsam finden sie eine Lösung. Eine kurze Rückfrage, ob das Problem wirklich verstanden wurde, gehört dazu. Anschliessend wird die Anpassung an den Domain Experten / Spec Owner gemeldet. In der Regel kann dieser sie umsetzen und kommuniziert die Änderung an die betroffenen Stellen weiter.

Skills, Regeln und typische Probleme

Jede Rolle bekommt klare Skills mit. Beobachten wir im Verhalten ein Problem, verfeinern wir die Skills oder die Regeln, statt das Problem manuell aufzufangen. Was uns dabei immer wieder auffällt: die Agenten imitieren menschliches Verhalten in echten Teams ziemlich genau. Drei Klassiker:

• Greenwashing: es wird nur ein Stub programmiert, die eigentliche Implementierung als spätere Aufgabe vor sich her geschoben. Gegenmittel: Skills, die zwischen “fertig” und “Stub” unterscheiden; Audit Gates, die unimplementierte Pfade markieren.
• Schlampigkeit: statt die generierten Werte zu verwenden, werden eigene Konstanten erfunden, die zufällig passen. Gegenmittel: die Audit Gates für Magic Numbers und unbekannte Symbole.
• Weg des geringsten Widerstandes: Tester und Firmware geraten in ein Streitgespräch. Die Firmware besteht darauf, dass der Tester erst beweist, dass ein Fehler vorliegt, bevor man weiter macht. Der Tester verweigert weitere Läufe, bis alle Firmware Bugs behoben sind. Gegenmittel: proaktive Anweisung an die Firmware (“liefere, dann diskutieren wir”), und an den Tester die Anweisung “keep it rolling”, also weiter testen, Fehler protokollieren, nicht blockieren.

Diese Muster sind dieselben, die jeder Engineering Manager aus echten Teams kennt. Sie verschwinden mit klaren Skills, klaren Regeln und einer Spec, die jede Streitfrage entscheidet.

Anekdoten aus der Praxis

• Zwei Agenten gaben sich gegenseitig die Schuld an einem fehlschlagenden Test, jeder bestand darauf, dass der andere kaputt sei. Die Spec als Schiedsrichter beendete das Fingerzeigen sofort.
• Einmal habe ich nach einer Stunde die Augen gerieben, weil nicht die AI das Problem war, sondern die BI, die biologische Intelligenz vor dem Bildschirm. Die AI hatte das Problem längst isoliert, sie konnte es nur nicht so kommunizieren, dass ich es verstand. Ich war im “Flitzpiepe, was hast du jetzt wieder gemacht” Denken gefangen, sie hatte die ganze Zeit recht.
• Ein Sprachmodell hat keinen eingebauten Sinn für Zeit. Beschreibt man Abläufe als geordnete Liste mit expliziten Wartezeiten (tu dies, warte, dann erwarte das), versteht der Testagent plötzlich Timing-Fehler, für die er vorher blind war.
• Im dedizierten Testbuild (nie in der ausgelieferten Firmware) führen wir interne Signale auf ein Test Interface heraus: Zustand einer Zustandsmaschine, gesehene Ereignisse eines Tasks. Eine Informationsflut, die für einen Menschen Tage Auswertung wäre, hilft dem Agenten in Sekunden, das interne Verhalten direkt zu lesen statt zu erschliessen. Vorher wurde er kreativ und brachte Ursachen ins Spiel, die weit über die Metaphysik hinausgehen, von kosmischer Strahlung bis zur Mondphase. Das ist überhaupt das grosse Problem in der Technik: der Kontext ist entscheidend. Sitzt der Agent einmal richtig im Kontext, wird vieles deutlich einfacher. Deshalb sind kleine Iterationen meist besser als grosse, wobei manchmal der Big Bang erstaunlich gut funktioniert und ein grösseres Refactoring, das gegen den Rat des Agenten gestartet wird, oft erstaunlich glatt durchgeht.
• Sich selbst überlassen friert ein Agent ein. Wir halten ihn mit einer Warteaufgabe wach, die erst endet, wenn die nächste Nachricht kommt. Einmal lief dieser Waiter doppelt; das Wakeup verschluckte sich; der Agent kam nicht zurück. Ein Nebenläufigkeitsfehler im Werkzeug, das Nebenläufigkeitsfehler jagt.

Die Spec ist die Leitplanke. Der gezeichnete Zyklus wird angestossen, wenn die JSON Spec angepasst werden muss. Der autonome Ping-Pong zwischen Testagent und Firmware läuft separat und ständig weiter.

Was wir bewusst nicht gebaut haben

Kein schwergewichtiges Orchestrierungs Framework. Die Maschinerie bleibt klein: eine Spec Datei, eine Reihe von Generatoren, ein Hardware Testrunner, eine Handvoll Audit Prüfungen, ein schlanker Bus. Klein genug, dass ein neuer Ingenieur das Ganze an einem Nachmittag lesen kann.

Zum Mitnehmen

• Ein maschinenlesbarer Vertrag in JSON, alle Artefakte daraus generiert.
• Tests auf echtem Target, gegen Erwartungen aus genau diesem Vertrag.
• Audit Gates, die den Build bei Drift stoppen.
• Eine Regel: die Spec gewinnt.
• Klare Skills und Regeln pro Rolle, damit Agenten nicht in menschliche Dysfunktionsmuster verfallen.
• Der Mensch sitzt ausserhalb der Schleife, greift korrigierend und beratend ein, entscheidet bei Architektur und Kundenfragen.

Funktionelle Tests, die für eine Zertifizierung relevant sind, laufen ausserhalb dieses Zyklus, mit eigenen Protokollen, Auditpfaden und Freigaben.

Schlüsselwörter: Single Source of Truth, Spec Driven Development, Agentic Engineering, Firmware Codegenerierung, Hardware in the Loop, JSON Interface Vertrag, AI Agenten Firmware Beratung, Audit Gates, Claude Opus, Embedded Testing HIL, Embedded Consulting Schweiz, swissEmbedded Firmware Entwicklung