Using GithHub Spec-Kit

Einleitung in Spec-Kit: Wie Du mit Cursor und Spec-Driven Development (SDD) Produktionsreife Anwendungen erstellst

Dieser Blogbeitrag wurde zu einem Teil mit Hilfe durch Gemini erstellt und basiert auf einer Analyse der folgenden Quellen:

• Leon van Zyl, YouTube: “Spec Kit: How to Build Production-Ready Apps with AI Agents”
• Den Delimarsky, YouTube: “Using GitHub Spec Kit with your EXISTING PROJECTS”
• Gemini 2.5 Recherche: “Spec-Driven Neuentwicklung mit GitHub Spec-Kit und Cursor” (Ergebnisse dieser Recherche flossen in meinen Text ein).

https://github.com/github/spec-kit

Warum Spec-Kit? Die Struktur, die KI-Agenten brauchen

Du kennst das Problem: Du hast eine großartige Idee für eine Anwendung, schreibst den Prompt, wirfst ihn Deinem Coding-Agenten zu und denkst: “Alles klar, los geht’s!”. Und dann erhältst Du Ergebnisse, die fehlerhaft sind, wichtige Funktionen vermissen lassen, oder der Agent hat sogar Dinge hinzugefügt, die Du gar nicht verlangt hast.

Coding-Agenten sind unglaublich leistungsfähig, aber sie brauchen Struktur. Sie benötigen dieselben Details, die auch echte Entwickler nutzen: Edge Cases, User Stories und Architekturentscheidungen.

Genau hier setzt GitHub Spec-Kit an. Es handelt sich um einen strukturierten Workflow, der Skripte und fein abgestimmte Prompts ausführt, um hochwertigen Kontext für Deinen KI-Agenten zu generieren. Im Wesentlichen führt Spec-Kit das Spec-Driven Development (SDD) in Deinen Workflow ein. SDD ist eine bewährte Methodik, bei der alles im Voraus geplant und dokumentiert wird.

Spec-Kit ist kein KI-Modell, sondern ein Open-Source-Framework und eine Kommandozeilenschnittstelle (CLI), die den strukturierten Prozess bereitstellt. Es fungiert als “Dirigent”, der die Partitur liefert und den Takt vorgibt.

Die Symbiose: Spec-Kit als Dirigent, Cursor als Virtuose

Spec-Kit ist agnostisch in Bezug auf den verwendeten Coding-Agenten. Du kannst es mit Claude, Codeex oder eben Cursor nutzen.

In dieser Arbeitsteilung ist Cursor der “Virtuose” oder der intelligente, KI-gestützte Code-Editor, der die Anweisungen des Spec-Kit-Frameworks ausführt.

Der Einsatz von Cursor

Wenn Du Spec-Kit zusammen mit Cursor verwendest, nutzt Du die integrierten Slash Commands. Anstatt manuell Prompts einzugeben, führst Du vordefinierte, kontextreiche Prompts aus, die Spec-Kit bereitstellt, wie zum Beispiel /Spec-Kit.constitution oder /Spec-Kit.specify. Die interne KI-Engine von Cursor liest diesen Prompt, versteht den Kontext aus den Spec-Kit-Vorlagen und generiert daraufhin die entsprechenden Dateien.

Ein entscheidender Vorteil bei der Nutzung von Cursor ist die Multi-LLM-Umgebung. Spec-Kit hat kein eigenes Sprachmodell (LLM); stattdessen wird das in der Cursor IDE ausgewählte und konfigurierte Modell verwendet. Dies bietet Dir maximale Flexibilität:

• Du kannst aus einer breiten Palette von Modellen wählen, darunter Claude 3.5 Sonnet und GPT-4o.
• Deine Fähigkeit verlagert sich von der reinen Codeerstellung zur Orchestrierung des richtigen KI-Modells für die richtige Aufgabe.

Der Spec-Kit-Workflow: Phasen des SDD

Der Spec-Kit-Workflow ist in mehrere kritische Phasen unterteilt, die sicherstellen, dass die KI alle notwendigen Informationen erhält, bevor sie mit dem Schreiben von Code beginnt:

1. Constitution (Die Gesetze des Projekts)

Dies ist oft der erste Schritt, den Du ausführst. Die Constitution legt die nicht verhandelbaren Projektprinzipien und -standards fest.

• Zweck: Definiert den Technologiestapel (z.B. Next.js 15), Architekturprinzipien und Testanforderungen.
• Ablauf in Cursor: Du startest eine neue Konversation und verwendest den /constitution-Befehl (oder /Spec-Kit.constitution).
• Wichtig: Die Constitution dient als Leitplanke für die KI, um unerwünschte Muster oder Technologien zu vermeiden, die Du hinter Dir lassen möchtest.

2. Specify (Was und Warum)

Dies ist der Beginn des Feature Life Cycles. In dieser Phase teilst Du dem Agenten mit, welche Funktion Du bauen möchtest, ausschließlich anhand von geschäftlichen Anforderungen und User Stories.

• Ergebnis: Die KI erstellt automatisch einen neuen Branch für die Funktion und die Datei spec.md, die Anwendungsfälle, Akzeptanzszenarien und funktionale Anforderungen enthält.

3. Clarify (Die Optionalität der Präzision)

Dieser optionale Schritt ist sehr zu empfehlen. Der Agent analysiert die erstellte spec.md und stellt klärende Fragen zu Unklarheiten oder fehlenden Details (z.B. zur Sortierreihenfolge oder Paginierung).

• Nutzen: Dieser Schritt zwingt Dich als Entwickler dazu, über Edge Cases nachzudenken und die Anforderungen detailliert auszuarbeiten. Die spec.md wird mit den neuen Informationen aktualisiert.

4. Plan (Das Wie)

Der Planungsphase folgt auf die finalisierte Spezifikation.

• Zweck: Erstellung des technischen Implementierungsplans. Hier kannst Du technische Details und Regeln hinzufügen (z.B. “verwende Local Storage, um Daten zu persistieren” oder Angabe des genauen Tech Stacks).
• Ergebnis: Die KI generiert die Datei plan.md, die Details zur Systemarchitektur, zum Datenbankschema (falls relevant) und API-Verträge enthält.

5. Tasks (Granulare Schritte)

Der Plan wird in individuelle, ausführbare Schritte zerlegt.

• Zweck: Erstellung einer granularen, priorisierten Checkliste von Entwicklungsaufgaben (z.B. T001, T002).
• Ergebnis: Die Datei tasks.md wird erstellt.

6. Implement (Die Code-Ausführung)

Dies ist der Schritt, in dem der Coding-Agent den eigentlichen Code schreibt.

• Best Practice: Du solltest die Implementierung in kleinen Abschnitten ausführen (z.B. nach Phase 3.1), um die Kontextfenster des LLM optimal zu nutzen und die Ausgabequalität zu sichern.
• Qualität: Spec-Kit fördert Test-Driven Development (TDD), wobei der Agent zuerst Tests schreibt, die fehlschlagen, und dann die Funktionalität implementiert, bis die Tests bestehen.

Fortgeschrittene Technik: Kontextsteuerung mit Cursor

Für komplexe Projekte, insbesondere bei der Neuentwicklung (Greenfield), musst Du möglicherweise Logik aus Altsystemen analysieren.

• Die Zwei-Arbeitsbereiche-Strategie: Für die Neuentwicklung ist es ratsam, zwei separate Arbeitsbereiche zu verwenden: Arbeitsbereich A (“Das Museum”) für den Legacy-Code (nur lesend) und Arbeitsbereich B (“Die Gießerei”) für das neue, leere Repository, in dem Spec-Kit ausgeführt wird. Dies ist eine unmissverständliche Best Practice, um technische Schulden zu vermeiden.
• Chirurgisches Prompting mit Cursor: Wenn die KI auf spezifische Legacy-Logik zugreifen muss, ohne den neuen Kontext zu verunreinigen, ermöglicht Cursor @file-Referenzen. Du kannst im Prompt des neuen Projekts auf eine Datei im Legacy-Projekt verweisen (z.B. @../legacy-project/src/utils/pricing-calculator.php), um die KI anzuweisen, nur die Geschäftslogik zu extrahieren und sie in den neuen Stack zu übersetzen. Du wirst dabei zum Informationsarchitekten.

Fazit

Spec-Kit und Cursor bieten zusammen eine strukturierte, transparente und skalierbare Methodik für die moderne Softwareentwicklung. Der Prozess ist dialogorientiert und erfordert von Dir eine sorgfältige Überprüfung und Verfeinerung aller generierten Artefakte. Indem Du die Prozesse (Spec-Kit) und die Intelligenz (Cursor/LLM) klar trennst, behältst Du die Kontrolle über die Architektur und stellst sicher, dass Deine KI-Agenten Anwendungen bauen, die tatsächlich Deinen Vorstellungen entsprechen.

Die generierten Dokumente (spec.md, plan.md, tasks.md) sind dabei nicht nur Anweisungen für die KI, sondern werden zu einer lebenden Dokumentation für Dein Team und sind unschätzbare Werkzeuge für Code-Reviews. Du kannst diese Spezifikationen in Zukunft wiederverwenden, selbst wenn Du den gesamten Technologiestapel wechselst.