Spec Kit Anleitung 2026: Installation und Praxis der spezifikationsgetriebenen Entwicklung unter Windows, macOS und Linux

Spec Kit, gepflegt von GitHub, macht spezifikationsgetriebene Entwicklung zu einer CLI, die ihr installiert, und zu Skills, die der Agent aufruft. Das PyPI-Paket heißt specify-cli. Das Quell-Repository ist github/spec-kit. Es ersetzt weder Cursor noch Claude Code, GitHub Copilot oder Codex. Es zwingt diese Agenten, zuerst das beobachtbare Verhalten zu schreiben, danach die Technikwahl und zuletzt die Änderungen am Repository. Stand November 2026 nutzt Windows PowerShell-Skripte direkt. WSL muss nicht zuerst installiert werden. Diese Seite ist die Installation, die Verzeichnisstruktur und die Befehlsreihenfolge. Warum eine Spezifikation vor dem Code existieren muss, steht im Leitfaden zur spezifikationsgetriebenen Entwicklung. Wo Skill-Dateien liegen, steht im Agent-Skills-Leitfaden.

Warum „bau mir ein Board“ schon der falsche Anfang ist

Der Konflikt zwischen altem und neuem Weg ist konkret. Der alte Weg ist sitzungszentriert. Ziel, Stack und Ordnerlayout landen in einem Chat. Der Agent rät und ändert Dateien. Wechselt die Maschine oder die Person, ist der Kontext weg. Der neue Weg ist artefaktzentriert. Prinzipien stehen in .specify/memory/constitution.md. Verhalten und der Grund dafür stehen in specs/<feature>/spec.md. Der Stack wartet auf plan.md. Die ausführbare Reihenfolge wartet auf tasks.md. Das aktive Feature ist das Verzeichnis, auf das .specify/feature.json zeigt, nicht die Erinnerung an den letzten Thread.

2026 ist das ein Installationsproblem, kein Haltungsproblem, aus drei Gründen. Erstens spaltet sich die Aufrufschreibweise nach Agent. Cursor, Claude Code und der Standard-Skills-Modus von Copilot nutzen /speckit-specify. Codex nutzt $speckit-specify. Die Punktform in der Dokumentation ist nur eine Referenzschreibweise. Zweitens lässt eine Installation mit uv und eine zweite mit pipx zwei specify-Binaries zurück. Die alte Kopie auf dem PATH lehnt --integration ab. Drittens kann die optionale Git-Erweiterung nummerierte Branches anlegen, aber git checkout selbst schaltet das aktive Feature nicht um. Alle drei Dinge passieren vor der ersten Zeile Produktcode.

Wie Spec Kit die Arbeit in Schichten teilt

Behandelt die neun Slash-Skills nicht als eine flache Checkliste. Sie landen auf drei Arten von Artefakten, und nur zwei Pfade sind zulässig.

Die Prinzipienschicht gibt es einmal pro Repository. /speckit-constitution hält harte Grenzen für Qualität, Tests, Rechte und Nutzung fest. Spätere Schritte werden an dieser Datei gemessen. Die Feature-Schicht gibt es einmal pro Feature. /speckit-specify beantwortet nur, was eine Nutzerin beobachten kann und warum es existieren soll. /speckit-clarify fragt die unklaren Stellen und schreibt die Antworten in die Spezifikation zurück. Die Implementierungsschicht ist der erste Ort, an dem ein Framework oder ein Verzeichnis erlaubt ist. /speckit-plan erzeugt Plan, Recherche, Datenmodell und Verträge. /speckit-tasks zerlegt den Plan in Abhängigkeitsreihenfolge und markiert parallele Arbeit mit [P]. /speckit-implement ändert Dateien in dieser Reihenfolge. /speckit-converge vergleicht den Code mit den Artefakten, hängt fehlende Aufgaben an und wiederholt das, bis es Converged meldet.

Zwei Qualitätstore liegen dazwischen. Verwechselt sie nicht mit „der Code ist fertig“. /speckit-checklist baut eine Liste der Anforderungsqualität, die bei der prüfenden Person bleibt. Ein Haken bedeutet, die Anforderung ist klar, nicht, dass das Feature implementiert ist. /speckit-analyze ist nur lesend. Es meldet Konflikte zwischen spec.md, plan.md und tasks.md und ändert das Repository nicht. Die eingebaute Datei checklists/requirements.md pflegen specify und clarify. Eigene Checklisten bleiben bei der prüfenden Person. Implement hält an und fragt, wenn Kästchen offen sind. Es hakt sie nicht für euch ab.

Der kurze Pfad passt zu einer kleinen Änderung, deren Grenze schon klar ist: specify, plan, tasks, implement, converge. Der volle Pfad passt zu allem, das ihr ausliefern wollt: constitution einmal pro Projekt, danach specify, clarify, plan, checklist, tasks, analyze, implement, converge. Ein Defekt folgt dem offiziellen Bug-fixing-Schnellstart. Eine Idee, der ihr euch noch nicht verpflichtet habt, folgt der Idea-Assessment. Beides ist keine Voraussetzung dieses spezifikationsgetriebenen Pfads.

Installation unter Windows, macOS und Linux

Die gemeinsamen Voraussetzungen sind Python 3.11 oder neuer, Git nur wenn ihr die Git-Erweiterung aktiviert, und der Agent, mit dem ihr tatsächlich Code schreibt. Nutzt uv für eine dauerhafte Installation. Das Terminal startet die CLI. Slash-Skills laufen im Agent-Chat.

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv tool install specify-cli
specify version
specify self check
specify init deskboard --integration cursor-agent --script ps

curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install specify-cli
specify version
specify self check
specify init deskboard --integration cursor-agent --script sh

Nach der Installation prüft zwei Dinge. specify version beweist nur, dass der Befehl läuft und eine Version ausgibt. Es beweist nicht, ob die Binary von PyPI oder von GitHub stammt. specify self check ist nur lesend. Es sagt, ob ein neueres Release existiert, und ändert die Installation nicht. Die Dokumentation zeigt Release-Tags mit führendem v, zum Beispiel v0.12.11. Eine Quellen-Installation pinnt ihr mit uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z, das v bleibt. Ein PyPI-Pin ist uv tool install specify-cli==X.Y.Z. Aktualisiert mit demselben Werkzeug wie bei der Erstinstallation: uv tool install --force specify-cli, pipx install --force specify-cli oder pip install --upgrade specify-cli.

Initialisiert ein Repository mit vorhandenem Code nicht auf einem schmutzigen Arbeitsbaum. Zuerst committen oder sichern, danach specify init --here --force --non-interactive --integration claude. --force bedeutet nur, dass ihr das Zusammenführen der Vorlagen in bestehende Dateien akzeptiert. CI ohne Tastatur braucht --non-interactive, sonst bleibt init in einem Pfeiltasten-Menü stehen. Liegt die Agent-Binary auf einer anderen Maschine, ergänzt --ignore-agent-tools und überspringt die lokale Prüfung. Nicht-interaktives init nimmt Copilot, solange ihr kein anderes --integration übergebt.

Ratet den Integration-Schlüssel nicht. Cursor ist cursor-agent, nicht cursor. Weitere übliche Schlüssel sind claude, copilot, gemini, pi, omp und codebuddy. Ein interaktives Terminal fragt, wenn ihr --integration weglasst. Ein Skript oder eine Pipe muss den Schlüssel setzen.

Zeigt specify version eine alte Nummer, schaut zuerst mit which specify auf den Pfad. Bleibt eine 0.1-Binary liegen, wird --integration zu No such option: --integration, und das alte --ai meldet No matching release asset found. Das ist kein Netzfehler. Der vordere PATH-Eintrag zeigt auf eine andere Installation. Entfernt nur die Kopie, die ihr nicht nutzt, und aktualisiert mit dem ursprünglichen Werkzeug plus --force oder --upgrade. Wer beide Werkzeuge abwechselnd benutzt, hat danach wieder zwei Binaries.

Neun Befehle: wo sie laufen, was sie ändern dürfen, für wen sie sind

Die nächsten beiden Tabellen teilen sich dieselben Spalten. Der echte Unterschied ist der Einstieg und die Ausführungsgrenze, nicht der Modellname.

Kurzen oder vollen Pfad nach der Lage wählen

Das laufende Beispiel ist ein Notizboard, das auf einer Maschine bleibt. Nichts wird hochgeladen. Die erste Phase hat kein Passwort. Drei festgelegte Mitglieder. Vier Spalten unter einem Projekt: Zu erledigen, In Arbeit, Bestätigung nötig, Fertig. Eine Karte wechselt die Spalte per Ziehen. Einen Kommentar darf nur die Autorin ändern. Specify hält dieses Verhalten und den Grund fest. Im Plan steht erst „lokales SQLite, keine Remote-API“. Steht die Datenbank schon in specify, wird die erste technische Ahnung zu einer Anforderung, die niemand mehr infrage stellen darf.

Der specify-Text im Chat bleibt auf dieser Körnung. Drei feste Personen öffnen ein Projekt und ziehen Karten zwischen vier Spalten. Bearbeiten und Löschen eines Kommentars darf nur die Autorin. Beim Start wird kein Passwort gefragt. Speicherort, Framework und Tabellenname gehören nicht hinein. In dem Moment, in dem sie dort stehen, überholt die Spezifikation den Plan. Erst im Plan legt ihr fest: Speicherung in lokalem SQLite, eine Seite, kein Netz.

Agent, Skripttyp und eine isolierte Maschine zusammenbringen

Schreibt ihr dieses Repository schon in Cursor, nehmt cursor-agent und den Skripttyp der Maschine: ps unter Windows, sh unter macOS und Linux. Nach init ruft ihr im Chat einen Skill nach dem anderen auf, auf dem kurzen oder dem vollen Pfad. Lest das Artefakt, bevor der nächste Skill kommt. Fügt nicht alle neun Befehle in einen Prompt ein.

Nutzt ihr vor allem Claude Code, ist der Schlüssel claude. Drängen viele Skill-Beschreibungen den Kontext, initialisiert mit --integration-options="--no-model-invocation", damit die Kernbefehle nur laufen, wenn ihr /speckit-specify tippt. Copilot bleibt beim Standard-Skills-Layout. --commands nur, wenn ihr ausdrücklich die älteren Agent-Dateien wollt.

Implement ändert Dateien und startet Befehle. Den ersten Durchlauf nicht auf einem Laptop mit Produktionsschlüsseln machen. Legt das Repository auf einen Remote-Mac, lest den Diff und merget danach zurück. Wie ihr einen Knoten bestellt, steht unter Mac mini mieten. Das Budget steht unter Preise. Enthält die Spec einen macOS-Build oder eine Signatur, läuft diese Phase auf einem echten Mac-Knoten und bleibt mit OpenClaw-Cloud-Automatisierung vom Alltagsrechner getrennt. Schlägt die Installation fehl, prüft Verbindung und Systemvoraussetzungen im Hilfe-Center, bevor ihr Spec Kit die Schuld gebt.

Fünf Fehler, die den Rest der Arbeit neu erzwingen

1. Framework und Datenbank schon in specify schreiben. Der Stack gehört in den Plan. Steht in der Spec „muss diese Bibliothek nutzen“, verbringen clarify und analyze ihre Zeit damit, diese Wahl zu verteidigen.
2. /speckit-specify im Terminal tippen. Slash-Skills gibt es nur im Agent-Chat. Das Terminal startet specify selbst.
3. Den Punkt-Befehl aus der Doku in Cursor einfügen. Der Cursor-Skill heißt /speckit-specify. Die Punktform ist Referenzschreibweise.
4. Mit uv und pipx installieren. Eine alte 0.1.x-Binary meldet No such option: --integration oder bei --ai No matching release asset found. Führt which specify aus, bevor ihr entscheidet, welche Kopie weg soll.
5. git checkout als Feature-Schalter benutzen. Ändert .specify/feature.json oder setzt SPECIFY_FEATURE_DIRECTORY. Ein Branch-Wechsel allein lässt die Befehle auf das vorherige Feature-Verzeichnis zeigen.

Sieben Schritte

1. Installiert uv und specify-cli. Führt specify version und specify self check aus. Bestätigt, dass der PATH genau eine Binary trifft.
2. Wählt --script nach Betriebssystem und --integration nach dem Agenten, den ihr wirklich nutzt, und startet specify init. Bei einem bestehenden Repo zuerst committen und --here --force ergänzen.
3. Führt /speckit-constitution einmal im Agent-Chat aus. Nur Prinzipien: Eingaben prüfen, Kommentare darf nur die Autorin ändern, die erste Phase lädt nichts hoch.
4. Beschreibt Verhalten und Grund des Notizboards mit /speckit-specify. Wollt ihr es ausliefern, folgt /speckit-clarify und schließt die Fragen zu Ziehen, Rechten und einem leeren Projekt.
5. Erst wenn die Spec stabil ist, /speckit-plan. Danach checklist, tasks und analyze. Meldet analyze einen Konflikt, korrigiert das Quellartefakt. Flickt ihn nicht während implement.
6. Startet /speckit-implement auf einem isolierten Mac oder in einem sauberen Verzeichnis. Ist die Aufgabenliste lang, arbeitet phasenweise. Schluckt nicht die ganze tasks.md in einem Durchlauf.
7. Startet /speckit-converge, bis Converged kommt. Dann den Diff lesen: Dateien außerhalb der Spec und jedes Geheimnis, das ins Repository geschrieben wurde.

Fragen, die die Installation entscheiden

Worin unterscheidet sich Spec Kit vom Chatten in Cursor?

Ein Chat bleibt in dieser Sitzung. Wechseln Person oder Maschine, ist er weg. Spec Kit schreibt Prinzipien, Spec, Plan und Aufgaben als Markdown ins Repository. Das aktive Feature ist das Verzeichnis in .specify/feature.json, nicht die Erinnerung an den letzten Thread.

Heißt der Befehl /speckit-specify oder /speckit.specify?

Cursor, Claude Code und der Standard-Skills-Modus von GitHub Copilot nutzen die Bindestrichform im Agent-Chat, nicht im Terminal. Der Skills-Modus von Codex nutzt $speckit-specify. Die Punktform in der Dokumentation ist Referenzschreibweise. Fügt sie nicht in Cursor ein.

Braucht Windows zuerst WSL?

Nein. 2026 nimmt Spec Kit unter Windows standardmäßig PowerShell. Übergebt bei init --script ps. macOS und Linux nehmen bash, das ist --script sh.

Darf ich mit uv und pipx installieren?

Nein. Ihr behaltet zwei specify-Binaries. Die alte Kopie vorn im PATH lehnt --integration ab oder meldet No matching release asset found. Aktualisiert mit dem ursprünglichen Werkzeug, mit --force oder --upgrade.

Wechselt git checkout das aktive Feature?

Nein. Das aktive Feature ist .specify/feature.json. Überschreibt es mit SPECIFY_FEATURE_DIRECTORY. Die optionale Git-Erweiterung kann nummerierte Branches anlegen, ein Checkout allein aktualisiert diesen Zustand nicht.

Zuerst den richtigen Befehl installieren, dann den Agenten ins Repository lassen

Spec Kit ist nicht wertvoll, weil es einen weiteren Slash-Befehl gibt. Es ist wertvoll, weil „Spec, dann Plan, dann Dateien ändern“ zu Dateien im Repository wird, die eine andere Person prüfen kann. Windows nutzt PowerShell. macOS und Linux nutzen bash. Cursor nutzt cursor-agent und Bindestrich-Skills. Eine kleine Änderung nimmt den kurzen Pfad. Ein Feature, das ihr ausliefert, nimmt den vollen Pfad. Implement läuft auf einem isolierten Knoten. Der nächste Schritt ist keine weitere Prompt-Sammlung. Führt specify version aus und bestätigt, dass die Binary vor euch die gerade installierte ist. Stimmt die Nummer nicht, korrigiert den PATH, bevor ihr einen Skill tippt.

Weiterlesen

• Spezifikationsgetriebene Entwicklung: die Methode, nicht der Installer →
• Agent Skills: was wohin gehört →
• OpenClaw-Automatisierung auf einem Remote-Mac →