Praxis-Test von spec-kit: Was vor dem KI-generierten Code zu schreiben ist

Von Nokka | Teil 2 von 7 der Serie "Software mit KI entwickeln" | Datenstand: 23. Oktober 2026

Dieser Artikel wurde von einer KI verfasst (deepseek-v4.1-flash · Modellanbieter: ollama-cloud) über den Hermes Agent, unter menschlicher Kontrolle und Qualitätsprüfung durch Nokka.

Im letzten Teil hatte ich geplant, dass das Werkzeug dieser Serie aus drei Schichten besteht. Jetzt gehe ich auf die erste Schicht ein, die am häufigsten übersprungen wird.

Ich habe spec-kit auf einem Rechner installiert, der weder Claude Code noch Docker besitzt, und ein Beispielprojekt erstellen lassen, um zu sehen, was es uns tatsächlich generiert.

Das Ergebnis zwang mich, eine eigene Annahme zu korrigieren, was ich im Abschnitt zu den Befehlen erzählen werde.

Der Rechner, den ich verwende, hatte bereits Python 3.11 und uv. Der einzige Befehl lautet:

uv tool install specify-cli specify --version Enter fullscreen mode Exit fullscreen mode Das Ergebnis ist specify 1.2.3, was den Mindestanforderungen laut README entspricht: Python 3.11 oder höher sowie uv.

Ein Punkt, bei dem viele Fehler machen: Der Paketname und der Befehlsname sind nicht identisch. Das Paket heißt specify-cli, der aufzurufende Befehl heißt jedoch specify.

Ich ließ ein Beispielprojekt erstellen und gab dabei an, dass Claude als Agent verwendet werden soll.

specify init se-demo --integration claude Enter fullscreen mode Exit fullscreen mode Was passierte: Es brach sofort ab und meldete claude not found, zusammen mit einem Link zur Installationsanleitung, der auf die Setup-Seite von Anthropic verweist.

Das ist eine Hürde, die ich für sinnvoll halte, denn sie schützt Personen, die glauben, das gesamte Ergebnis der Pipeline zu erhalten, ohne überhaupt einen Agenten installiert zu haben.

Wer diese Hürde überspringen will, um nur die Struktur zu sehen, kann das Flag --ignore-agent-tools verwenden, das ich in der Ausgabe von specify init --help auf diesem Rechner gefunden habe.

Ich habe dieses Flag für meine Experimente genutzt, denn mein Ziel war es, die erzeugten Dateien anzusehen, nicht dass irgendwer Code für mich schreibt.

Die Grundstruktur besteht aus zwei Ordnern (alle Angaben habe ich in den tatsächlichen Dateien des Testprojekts nachgeprüft, und die Quelle jedes Elements steht am Ende der jeweiligen Zeile).

Der Ordner.claude/skills/ enthält zehn Einträge: specify, plan, tasks, implement, clarify, analyze, checklist, constitution, converge und taskstoissues.

Die Datei.specify/init-options.json speichert alle bei der Erstellung verwendeten Werte, was sehr nützlich ist, wenn ein Team wissen möchte, wie dieses Projekt konfiguriert wurde.

{ "ai": "claude", "ai_skills": true, "feature_numbering": "sequential", "integration": "claude", "script": "sh", "speckit_version": "1.2.3" } Enter fullscreen mode Exit fullscreen mode Wie heißen die tatsächlichen Befehle? An dieser Stelle musste ich meine eigene Annahme korrigieren.

In der Dokumentation und in vielen Artikeln werden die Befehle als /speckit.specify mit Punkt geschrieben, aber das in Version 1.2.3 auf meinem Rechner tatsächlich Installierte erzeugt Ordner mit Bindestrich, also speckit-specify, speckit-plan, speckit-tasks, speckit-implement.

Der verlässlichste Weg ist, wirklich in den Ordner.claude/skills/ im eigenen Projekt zu schauen, statt Artikeln im Internet zu vertrauen oder dem, was ich selbst einmal geschrieben habe.

Wer einen anderen Agenten verwendet, erhält möglicherweise andere Namen und Befehlsformate, da diese aus dem manifest der jeweiligen integration generiert werden.

Öffnet man die Datei.specify/templates/spec-template.md und betrachtet die Abschnitte, sieht man, dass sie drei Hauptteile zwingend vorschreibt.

User Scenarios & Testing (mandatory) gliedert sich in User Stories auf drei Prioritätsstufen von P1 bis P3 samt einem Abschnitt für Edge Cases.

Requirements (mandatory) unterscheidet funktionale Anforderungen und, falls die Funktion datenbezogen ist, die zentralen Daten.

Success Criteria (mandatory) muss messbare Ergebnisse enthalten.

Mir fällt auf, dass das Wort Testing von Anfang an im Pflichtteil steht. Das ist ein wichtiger Unterschied zu klassischen Anforderungsdokumenten.

Es zwingt einen, von Beginn an zu überlegen, wie man erkennt, dass alles korrekt funktioniert, statt das erst beim Schreiben der Tests zu bedenken.

Im letzten Teil hatte ich versprochen, diese Frage klar zu beantworten.

Ein Dokument, das Menschen lesen, erzählt meist Gründe und Kontext, etwa warum wir diesen Ansatz gewählt haben und wer etwas ausprobiert hat, das nicht funktionierte.

Ein spec, mit dem ein Agent arbeitet, braucht etwas anderes: überprüfbare Angaben.

Der Vorlage, die ich mir angesehen habe, zufolge gibt es drei Dinge, die genau diese Aufgabe erfüllen.

Priorisierte User Stories sagen dem Agenten, was zuerst erledigt werden muss und was danach kommen kann.

Edge Cases geben an, welches Verhalten bei ungewöhnlichen Daten erwartet wird.

Messbare Erfolgskriterien sagen, was der Beleg dafür ist, dass die Arbeit abgeschlossen ist.

Meiner Ansicht nach wird der Agent für einen raten, wenn man nur einen schönen Fließtext ohne diese drei Elemente schreibt, und sein Raten wird zu Code, den man später korrigieren muss.

Die Datei plan-template.md enthält zudem einen Abschnitt Constitution Check.

Das bedeutet, dass vor dem eigentlichen planen und implement geprüft wird, ob der Plan den Prinzipien widerspricht, die in memory/constitution.md festgelegt wurden.

Bei einem neuen Projekt ist die constitution-Datei noch eine leere Vorlage mit Beispielen, etwa Prinzipien wie library-first oder CLI interface.

Lässt man sie leer, gibt es an dieser Stelle nichts zu prüfen, wodurch man diesen Vorteil unnötig verschenkt.

Aus der Liste der erhaltenen skills lässt sich diese sinnvolle Reihenfolge ableiten.

Die drei Elemente in der Mitte sind clarify, analyze und checklist, die meiner Einschätzung nach am häufigsten übersprungen werden, obwohl sie viel Zeit sparen können.

OpenSpec hat 72.780 Sterne, steht unter der MIT-Lizenz und wurde zuletzt am 23. Oktober 2026 aktualisiert. Es positioniert sich als spec-driven development für AI coding assistants.

Beide Werkzeuge lösen dasselbe Problem, nämlich dem Agenten vor dem Loslegen eine Spezifikation an die Hand zu geben, verfolgen dabei aber unterschiedliche Ansätze.

spec-kit liefert einen stabileren Rahmen, mit einer Constitution, einem Workflow sowie Skripten, die beim Erzeugen der Dateien helfen.

OpenSpec setzt auf einen leichteren und flexibleren Ansatz und eignet sich eher für alle, die eine Spec-Datei als zentrale verbindliche Grundlage im Repository möchten, statt ein komplettes System.

Keines der beiden ist grundsätzlich besser, es hängt davon ab, wie viel Struktur Ihr Team benötigt.

Erstens: Die Installation über (das Tool) lässt noch keinen Agenten einspringen, was fälschlich den Eindruck erweckt, alles sei einsatzbereit, obwohl die Befehle von speckit den Agenten nicht aufrufen können, wenn dieser nicht tatsächlich auf dem Rechner vorhanden ist.

Zweitens: Leere Vorlagen verwandeln die Prüfstufe in eine bloße Zeremonie.

Drittens: Die Befehlsnamen ändern sich je nach Version und je nach gewähltem Agenten. Verlassen Sie sich nicht auf das, was in einem Artikel steht, sondern schauen Sie in Ihrem eigenen Projekt nach.

Viertens: Nach meiner Erfahrung führen zu lange Spezifikationen dazu, dass der Agent sie nicht vollständig liest, und liefern meist schlechtere Ergebnisse als eine kurze, klare Spec.

Fünftens: Eine Spezifikation erst nach dem Schreiben des Codes zu verfassen, ist eine nachträgliche Dokumentation und keine Planung.

Installieren Sie das Werkzeug mit uv und führen Sie dann init in einem Testordner aus. Sie können dabei zunächst das Flag zum Überspringen der Agenten-Stufe verwenden.

Öffnen Sie anschließend die Datei.specify/templates/spec-template.md, lesen Sie sie einmal vollständig durch und schreiben Sie dann von Hand eine Spezifikation für eine kleine Funktion.

Bevor Sie den Agenten an den Code lassen, prüfen Sie, ob die Spezifikation mindestens ein messbares Erfolgskriterium enthält.

Wenn Sie ein Kriterium nicht formulieren können, bedeutet das, dass Sie noch nicht verstanden haben, woran sich zeigt, dass die Funktion erfolgreich umgesetzt ist, und der Agent wird es ebenfalls nicht verstehen.

GitHub, "github/spec-kit" README, abgerufen am 23. Oktober 2026 (Voraussetzungen: Python 3.11 oder höher, uv, die Befehle uv tool install specify-cli und specify init mit der Option --integration).

GitHub, "Fission-AI/OpenSpec", abgerufen am 23. Oktober 2026 (MIT, 72.780 Sterne, aktualisiert am 23. Oktober 2026, spec-driven development für AI coding assistants).

GitHub, "github/spec-kit: templates/spec-template.md", "templates/plan-template.md" und "scripts/bash/create-new-feature.sh", abgerufen am 23. Oktober 2026 (verpflichtende Abschnitte in den Spec- und Plan-Vorlagen sowie die Liste der Bash-Skripte, die mit dem Werkzeugpaket mitgeliefert werden).

Anthropic, "Claude Code setup", abgerufen am 23. Oktober 2026 (Installationsverweis, den spec-kit angibt, wenn claude auf dem Rechner nicht gefunden wird). GitHub, "github/spec-kit: workflows/speckit/workflow.yml", abgerufen am 23. Oktober 2026 (Definition des Workflows mit dem Namen Full SDD Cycle, der auf der obersten Ebene des Repositorys liegt und nicht im Ordner templates).