OpenSpec für KI-Entwicklung: Warum Spezifikationen zum neuen Werkzeug im Coding-Workflow werden

Vor ein paar Monaten habe ich versucht, mit reinem Chat-Prompting eine mittelgroße Node-Anwendung umzubauen. Ergebnis: Die KI hat drei verschiedene Datenbankschemata vorgeschlagen, zwei davon widersprachen sich, und am Ende musste ich per Hand nachvollziehen, was sie sich überhaupt gedacht hatte. Klassisches Bastelprojekt, das im Chaos endete, weil niemand – auch nicht ich selbst – vorher aufgeschrieben hatte, was eigentlich gebaut werden sollte. Genau an diesem Punkt setzt OpenSpec an, ein Open-Source-Werkzeug, das gerade in der Coding-Community für Gesprächsstoff sorgt. Spoiler: Es geht nicht um noch mehr KI, sondern um weniger Raten.

OpenSpec ist ein leichtgewichtiges Framework für spezifikationsgetriebene Entwicklung, kurz Spec-Driven Development, das speziell für die Zusammenarbeit mit KI-Coding-Assistenten wie Claude Code, Cursor oder Windsurf gebaut wurde. Die Grundidee ist unspektakulär und trotzdem wirkungsvoll: Bevor die KI Code schreibt, schreibt sie eine Spezifikation. Erst wenn diese Spezifikation steht und von einem Menschen abgenickt wurde, geht es in die Implementierung. Klingt nach Bürokratie? Vielleicht. Aber genau diese Bürokratie verhindert das Chaos, das ich mir mit meinem Node-Projekt selbst eingehandelt habe.

Was OpenSpec technisch eigentlich macht

OpenSpec ist als CLI-Tool über npm verfügbar und lässt sich mit dem Paket @fission-ai/openspec installieren. Entwickelt wurde es vom Team hinter Fission-AI, und laut offizieller Dokumentation unterstützt es mittlerweile eine zweistellige Zahl an KI-Programmierwerkzeugen. Nach der Installation initialisiert der Befehl openspec init das Projekt, danach übernimmt der KI-Chat die Regie über eigene Slash-Commands. Nerd-Alarm: Wer schon mit Git-Workflows oder Ticketsystemen wie Jira gearbeitet hat, wird sich hier schnell zurechtfinden, denn die Struktur erinnert stark an einen klassischen Change-Request-Prozess, nur eben KI-gestützt und in Markdown statt in Formularen.

Im Kern verwandelt OpenSpec vage Chat-Prompts in strukturierte Markdown-Spezifikationen. Statt „Baue mir eine Login-Funktion“ tippt man einen Änderungswunsch, und das Tool erzwingt, dass daraus zunächst ein Anforderungsdokument wird. Das Prinzip ist in der offiziellen OpenSpec-Dokumentation gut nachvollziehbar beschrieben: Spezifikation vor Implementierung, nicht danach. Wer das für pedantisch hält, hat vermutlich noch keine KI-generierte Pull Request mit siebzehn ungewollten Nebenwirkungen debuggt.

Der OPSX-Workflow im Alltag

Der eigentliche Ablauf, von den Entwicklern OPSX genannt, gliedert sich in vier Schritte, die sich direkt im KI-Chat aufrufen lassen: /opsx:explore, /opsx:propose, /opsx:apply und /opsx:archive. Man beginnt mit einer Erkundungsphase, in der die KI den bestehenden Code und Kontext scannt. Danach folgt der Vorschlag, quasi ein Proposal mit Spezifikation, Design-Überlegungen und einer Aufgabenliste. Erst nach menschlichem Review wird angewendet, und am Ende landet die abgeschlossene Änderung im Archiv der Spezifikationen.

Dieses Vier-Schritte-Modell ist mehr als Kosmetik. Es zwingt sowohl Mensch als auch Maschine, Zwischenstopps einzulegen. Im Coding-Workflow bedeutet das: Bevor irgendein Zeichen Code entsteht, existiert bereits ein Dokument, das man lesen, kommentieren und notfalls verwerfen kann. Für Teams, die bislang mit reinem Prompt-Ping-Pong gearbeitet haben, ist das ein handfester Kulturwechsel. Wer schon einmal versucht hat, im Nachhinein zu rekonstruieren, warum eine KI vor drei Wochen eine bestimmte Architekturentscheidung getroffen hat, weiß, wie wertvoll ein archiviertes Proposal sein kann.

Interessant wird dieser Workflow besonders dann, wenn man ihn mit modernen API-basierten KI-Architekturen kombiniert, wie sie etwa bei der OpenAI Responses API für strukturierte Agenten-Workflows zunehmend üblich werden. Dort wie hier gilt: Je klarer die Schnittstelle zwischen Mensch, Spezifikation und Modell definiert ist, desto weniger Raum bleibt für Interpretationen, die später teuer werden.

Warum Spezifikationen gerade jetzt zum Werkzeug werden

Die Frage, die sich viele stellen: Warum ausgerechnet jetzt? KI-Coding-Assistenten sind seit Jahren im Einsatz, warum braucht es plötzlich eine zusätzliche Spezifikationsschicht? Die Antwort liegt in der schieren Menge an Code, die inzwischen ohne echtes Verständnis entsteht. Vibe Coding, also das intuitive Programmieren per Prompt ohne tiefes Codeverständnis, hat vielen Menschen den Einstieg ins Programmieren geöffnet – das ist grundsätzlich eine gute Entwicklung. Aber in professionellen Projekten mit echten Nutzern, echten Daten und echten Konsequenzen reicht Bauchgefühl nicht mehr aus.

OpenSpec adressiert genau diese Lücke, indem es Spezifikationen zum lebenden Artefakt macht statt zu einem einmalig geschriebenen Pflichtdokument, das ohnehin niemand mehr liest. Die Spezifikation wird gemeinsam von Mensch und KI gepflegt, wächst mit jedem Proposal und bleibt im Archiv nachvollziehbar. Das ist im Ernst ein Unterschied zu klassischen Lastenheften, die oft schon veraltet sind, bevor die erste Zeile Code geschrieben wurde.

Brownfield statt nur Greenfield: der eigentliche Clou

Viele Spec-Tools, die aktuell diskutiert werden, sind vor allem für neue Projekte gedacht, für den sprichwörtlichen weißen Fleck auf der Landkarte. OpenSpec positioniert sich bewusst anders: als brownfield-first, also besonders stark beim Verändern bestehender Codebasen. Das ist relevant, denn die meisten Coding-Projekte im Berufsalltag sind keine Neubauten, sondern Renovierungen an einem Haus, in dem längst jemand wohnt.

Ein bestehendes System mit hunderten Dateien, undokumentierten Abhängigkeiten und historisch gewachsenen Workarounds ist für eine KI ohne Spezifikation ein Minenfeld. Jede Änderung kann irgendwo eine stillschweigende Annahme verletzen, die vor drei Jahren mal Sinn gemacht hat. OpenSpec begegnet dem, indem jede Änderung als eigenes Proposal mit klar definiertem Delta zur bestehenden Spezifikation dokumentiert wird. Wer sich schon einmal mit Refactoring über Microservice-Grenzen hinweg beschäftigt hat, kennt das Problem: Ohne klaren Rahmen verselbstständigt sich jede noch so kleine Änderung schnell zu einem Rattenschwanz an Folgeeffekten.

Das Halluzinationsproblem und wie Proposals gegensteuern

Ein wiederkehrendes Ärgernis bei KI-Coding-Assistenten sind Halluzinationen: Die KI erfindet Funktionen, die es nicht gibt, referenziert Bibliotheken, die nie installiert wurden, oder behauptet felsenfest, ein Test bestehe, obwohl er längst rot ist. Der Proposal-Workflow von OpenSpec wirkt dem entgegen, weil die KI gezwungen wird, ihre Annahmen explizit zu machen, bevor überhaupt Code entsteht. Wer eine Spezifikation formulieren muss, kann sich weniger leicht in vagen Andeutungen verstecken.

Wichtig für die Einordnung: Deterministisch im mathematischen Sinn wird dadurch kein KI-Modell. Die zugrunde liegenden Sprachmodelle bleiben probabilistisch, das ändert auch die schönste Spezifikation nicht. Was sich verändert, ist die Nachvollziehbarkeit des Workflows. Man kann prüfen, kommentieren, ablehnen, bevor der Schaden im Repository landet. Das ist ein Unterschied wie zwischen einem Auto ohne Bremsen und einem Auto mit Bremsen, die man notfalls auch mal überreizen kann – besser als gar keine Bremse ist es in jedem Fall.

Team-Dynamik: Wenn mehrere Personen am selben Code arbeiten

Ein Aspekt, der in der technischen Diskussion oft zu kurz kommt, ist die Wirkung von OpenSpec auf die Zusammenarbeit im Team. In klassischen Settings mit mehreren Entwicklerinnen und Entwicklern, vielleicht sogar verteilt über Zeitzonen hinweg, ist asynchrone Kommunikation ohnehin schon eine Herausforderung. Kommt jetzt noch eine KI als dritte Akteurin ins Spiel, potenziert sich das Koordinationsproblem. OpenSpec schafft hier einen gemeinsamen Referenzrahmen: Das Proposal liegt im Repository, jeder Beteiligte kann es lesen, kommentieren, gegenlesen – unabhängig davon, wer den Prompt ursprünglich formuliert hat.

Das klingt banal, ist aber in der Praxis ein erheblicher Hebel. In Remote-Teams beobachte ich regelmäßig, dass mündlich abgestimmte KI-Änderungen nach zwei Wochen niemand mehr zuordnen kann. War das jetzt der Vorschlag von Kollege A oder die Idee aus dem Pair-Programming am Dienstag? Mit einem archivierten Proposal gibt es diese Unschärfe nicht mehr. Das Archiv wird de facto zu einer Art Entscheidungstagebuch, das auch neue Teammitglieder deutlich schneller onboardet als ein Haufen Chatverläufe in irgendwelchen Tools.

Gleichzeitig entstehen durch diese Transparenz neue Fragen: Wer ist befugt, Proposals abzusegnen? Braucht es ein Review-Quorum oder reicht eine Freigabe? OpenSpec selbst gibt hier keine organisatorischen Regeln vor, es liefert nur die technische Basis. Die konkreten Spielregeln muss jedes Team selbst aushandeln – was ehrlich gesagt auch gesund ist, denn vorgefertigte Prozessvorgaben passen selten auf reale Teams.

OpenSpec im Vergleich zu anderen Spec-Ansätzen

OpenSpec ist nicht das einzige Werkzeug in diesem Bereich. Tools wie Spec Kit oder Kiro verfolgen ähnliche Grundideen, setzen aber stärker auf Greenfield-Szenarien, also komplett neue Projekte von null. Der Unterschied zu OpenSpec liegt im erwähnten Brownfield-Fokus und in der engen Integration über Slash-Commands direkt im KI-Chat, statt über separate Web-Oberflächen oder zusätzliche Konfigurationsebenen.

Manche Stimmen in der Community bezeichnen OpenSpec als leichtgewichtiger im Vergleich zu Alternativen, weil der komplette Workflow über wenige Befehle läuft und keine zusätzliche Infrastruktur benötigt. Das ist eine subjektive Einschätzung einzelner Reviewer, keine gemessene Kennzahl, aber sie deckt sich mit meinem eigenen Eindruck: Wer schon mit komplexeren DevOps-Workflows gekämpft hat, weiß, wie befreiend ein Tool sein kann, das ohne zusätzlichen Server, ohne Datenbank und ohne Lizenzserver funktioniert. Man installiert das npm-Paket, tippt vier Befehle, fertig.

Praktische Schritte für den Einstieg

Wer OpenSpec ausprobieren möchte, braucht kein aufwendiges Setup. Die Installation läuft über npm, danach initialisiert man das Projekt lokal, und schon im nächsten KI-Chat stehen die Slash-Commands zur Verfügung, sofern das jeweilige Tool sie unterstützt. Bei Assistenten, die keine Slash-Commands anbieten, funktioniert OpenSpec über Kontext-Regeln, die man dem Modell mitgibt – etwas umständlicher, aber machbar.

Ein sinnvoller erster Testlauf: ein kleines, überschaubares Feature in einem bestehenden Projekt über den kompletten OPSX-Zyklus schicken, statt gleich das ganze System umzukrempeln. Erst explorieren lassen, dann den Proposal lesen – wirklich lesen, nicht nur überfliegen –, danach anwenden und am Ende archivieren. Wer diesen Zyklus einmal bewusst durchlaufen hat, merkt schnell, ob sich der zusätzliche Schritt für das eigene Projekt lohnt oder ob er im konkreten Fall nur Overhead produziert. Für kleine Skripte oder einmalige Spielereien ist die Spezifikationsschicht vermutlich übertrieben. Für Produktionscode mit mehreren Mitwirkenden dagegen zahlt sie sich meiner Erfahrung nach schnell aus.

Häufige Anti-Patterns: Was man vermeiden sollte

Wie bei jedem Werkzeug gibt es auch bei OpenSpec Nutzungsweisen, die mehr schaden als nützen. Das häufigste Anti-Pattern, das ich in Diskussionen beobachte: Proposals werden blind abgenickt, weil der Text ja plausibel klingt. Damit verlagert man das Problem nur – statt ungeprüftem Code hat man jetzt ungeprüfte Spezifikationen, die später genauso schwer zu debuggen sind. Ein Proposal ist kein Feigenblatt, sondern ein Review-Dokument, das mit derselben Sorgfalt behandelt werden sollte wie ein Pull Request.

Ein zweites Anti-Pattern ist die Über-Spezifikation. Manche Teams neigen dazu, jedes Detail bis in die letzte Zeile Pseudocode auszuformulieren, bevor die KI arbeiten darf. Das bremst den Workflow massiv aus und nimmt der KI genau die Stärke, für die man sie einsetzt: eigenständig Implementierungsdetails zu lösen. Die goldene Mitte liegt erfahrungsgemäß irgendwo zwischen „vage Idee“ und „vollständiger Algorithmus auf Papier“ – also bei einer Beschreibung des Was und Warum, nicht des Wie in jeder Einzelheit.

Ein dritter Punkt: Das Archiv ernst nehmen. Wenn archivierte Proposals veralten, weil sich das System in der Zwischenzeit weiterentwickelt hat, wird aus dem Entscheidungstagebuch schnell eine Quelle für falsche Annahmen. Ein gelegentlicher Aufräumprozess, bei dem veraltete Einträge markiert oder entfernt werden, gehört zum Workflow dazu – auch wenn das kein Tool der Welt automatisch für einen erledigt.

Wo die Grenzen liegen

Ganz ohne Nebenwirkungen ist der Ansatz nicht. Jede zusätzliche Spezifikationsebene bedeutet zusätzlichen Zeitaufwand, gerade am Anfang, wenn Team und KI sich erst an den Workflow gewöhnen müssen. Wer unter Zeitdruck schnell einen Prototyp braucht, wird den formalen Proposal-Prozess vermutlich als Bremse empfinden. Auch die Anzahl der unterstützten KI-Tools ist eine Momentaufnahme: Was heute gut funktioniert, kann sich mit dem nächsten Modell-Update wieder verschieben, wie das im gesamten Feld der KI-Coding-Assistenten üblich ist – siehe die ständigen Aktualisierungen bei Anthropic oder OpenAI.

Ein weiterer Punkt: OpenSpec ersetzt kein Testing. Eine Spezifikation, die korrekt formuliert, aber inhaltlich falsch ist, führt trotzdem zu falschem Code, nur eben mit mehr Papierkram davor. Wer sich auf die Spezifikation verlässt und die Ergebnisse nicht mehr prüft, hat am Ende nur eine neue Fehlerquelle gegen eine alte ausgetauscht. Die alte Regel gilt weiterhin: Review bleibt Pflicht, egal wie strukturiert der Weg dorthin war.

Wohin die Reise gehen könnte

Spannend wird die mittelfristige Entwicklung solcher Spec-Werkzeuge. Denkbar ist, dass Spezifikationen in Zukunft nicht nur als Markdown-Dateien im Repository leben, sondern direkt mit automatisierten Tests, Linting-Regeln und CI-Pipelines verknüpft werden. Ein Proposal würde dann nicht nur beschreiben, was gebaut werden soll, sondern gleich die Erfolgskriterien in maschinenlesbarer Form mitliefern – und die KI könnte selbst überprüfen, ob die Implementierung zur Spezifikation passt. Erste Experimente in diese Richtung gibt es bereits, auch wenn sie noch nicht produktionsreif sind.

Eine andere denkbare Entwicklung: Spezifikationen werden projektübergreifend geteilt und wiederverwendet. Wenn ein Team einmal eine saubere Spezifikation für ein Authentifizierungsmodul geschrieben hat, warum sollte ein anderes Team in derselben Organisation nicht darauf aufbauen? OpenSpec liefert mit seinem Archiv-Ansatz zumindest die technische Grundidee dafür, auch wenn die organisatorischen Hürden – Berechtigungen, Datenschutz, Wiederverwendbarkeit – noch weitgehend ungelöst sind.

Was bleibt?

OpenSpec ist kein Wundermittel, aber ein ehrlicher Versuch, dem KI-gestützten Coding-Workflow wieder etwas mehr Struktur zu geben, ohne dabei in schwergewichtige Enterprise-Prozesse zurückzufallen. Die Idee, dass Spezifikationen zum eigenständigen Werkzeug werden statt zum lästigen Pflichtdokument, wirkt zeitgemäß für eine Phase, in der KI-Entwicklung immer mehr Verantwortung an Maschinen abgibt. Ob sich dieser Ansatz gegenüber Alternativen wie Spec Kit durchsetzt, bleibt offen – das Rennen um den besten Spec-Workflow hat gerade erst begonnen. Wer selbst mit KI-Assistenten an bestehenden Projekten arbeitet, sollte sich zumindest den Quellcode auf GitHub einmal ansehen und den Vier-Schritte-Zyklus an einem unkritischen Feature ausprobieren. Vielleicht spart das beim nächsten Bastelprojekt genau die Nachtschicht, die ich mit meinem verunglückten Node-Umbau investieren musste.