Von der Spezifikation zum Code: Softwareentwicklung mit Spec Kit

Dieser Artikel ist Teil der XPRT. Magazin Nr. 21

Die spezifikationsgesteuerte Entwicklung geht von einer einfachen Beobachtung aus: Spezifikationen werden in der Regel verworfen. Man verfasst eine Spezifikation, um eine gemeinsame Ausrichtung zu erreichen, die Entwicklung beginnt, und schon innerhalb einer Woche ist die Spezifikation veraltet. Was zählt, ist der Code. Die Spezifikation diente lediglich als Gerüst.

Die spezifikationsgesteuerte Entwicklung kehrt diese Annahme um. Die Spezifikation wird nicht verworfen. Sie dient vielmehr als Eingabe, die die Codegenerierung direkt steuert. Sie beschreiben, was Sie erstellen möchten und warum, und ein KI-Agent setzt dies im Rahmen eines strukturierten, wiederholbaren Prozesses in eine funktionsfähige Implementierung um.

Spec Kit ist das Open-Source-Toolkit von GitHub, das genau dafür gedacht ist. Eine Befehlszeilenschnittstelle (CLI) erstellt ein Grundgerüst für Ihr Projekt und registriert eine Reihe von Slash-Befehlen in dem KI-Agenten Ihrer Wahl. Von dort aus durchlaufen Sie sechs Schritte: Festlegung der Projektgrundsätze, Erstellung der Spezifikation, Klärung von Randfällen, Definition des Tech-Stacks, Erstellung einer Aufgabenaufschlüsselung und Implementierung. Für jeden Schritt gibt es einen eigenen Befehl. Zwei optionale Befehle (/speckit.clarify zur Klärung von Unklarheiten und /speckit.analyze zur Überprüfung der Konsistenz zwischen verschiedenen Artefakten) kommen bei Bedarf zum Einsatz. Ein dritter optionaler Befehl, /speckit.checklist, generiert Qualitätschecklisten, die die Anforderungen auf Vollständigkeit und Konsistenz überprüfen. Der Arbeitsablauf sorgt dafür, dass Sie sich auf die Ergebnisse konzentrieren können, anstatt sich mit der Erstellung von Prompts zu beschäftigen.

Das Projekt hat über 82.000 Sterne auf GitHub und unterstützt von Haus aus Claude Code, GitHub Copilot, Cursor, Gemini CLI sowie über 25 weitere Agenten.

Dieser Artikel führt Sie durch den gesamten Arbeitsablauf, von der Installation bis hin zur funktionsfähigen Implementierung, und behandelt dabei sowohl Neuprojekte als auch die Erweiterung einer bestehenden Codebasis.

Erste Schritte

Sie benötigen Python 3.11 oder höher, Git sowie einen unterstützten KI-Agenten. Der Paketmanager „ uv “ kümmert sich um den Rest.

Installieren Sie die „ specify “-CLI einmal und nutzen Sie sie überall:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

Sie können das Programm auch ohne Installation nutzen, indem Sie es direkt mit dem Befehl „ uvx “ ausführen:

uvx --from git+https://github.com/github/spec-kit.git specify init my-project

Sofern Sie „ specify “ global installiert haben, können Sie ein neues Projekt für den KI-Agenten Ihrer Wahl initialisieren. Das Flag „ --ai “ legt fest, welche Slash-Befehle registriert werden:

specify init my-project --ai copilot

So arbeiten Sie in einem bestehenden Verzeichnis, anstatt ein neues zu erstellen:

specify init --here --ai copilot

Führen Sie nach der Initialisierung den Befehl „ specify check “ aus, um zu überprüfen, ob Ihr Agent und alle erforderlichen Tools korrekt erkannt wurden.

‌

Wenn alles in Ordnung zu sein scheint, öffnen Sie Ihren KI-Agenten im Projektordner. Dort werden Ihnen die Befehle „ /speckit.* “ angezeigt. Dies ist die Bestätigung dafür, dass die Einrichtung erfolgreich war.

‌

Die sechs Befehle bilden eine festgelegte Abfolge. Jeder Schritt erzeugt Artefakte, die vom nächsten Schritt gelesen werden. Hier ist der vollständige Arbeitsablauf, bevor wir die einzelnen Teile im Detail durchgehen:

‌

Festlegung von Grundsätzen mit /speckit.constitution

Das erste Programm, das Sie nach der Einrichtung ausführen. Es sind keine Argumente erforderlich, Sie können jedoch Anweisungen übergeben:

/speckit.constitution Create principles focused on testability, simplicity,
and consistency across all generated code

‌

Der Befehl lautet „ .specify/memory/constitution.md “ und wurde im Rahmen von „ specify init “ als Vorlage dort abgelegt. Er füllt die Platzhalterwerte anhand der von Ihnen bereitgestellten Vorgaben sowie anhand aller Kontextinformationen aus, die er aus Ihrem Repository ableiten kann: der README-Datei, der vorhandenen Dokumentation und früherer Versionen der Satzung. Das Ergebnis ist ein strukturiertes Dokument mit nummerierten Grundsätzen, einem Abschnitt zur Unternehmensführung und einer semantischen Versionsnummer.

Eine minimale Ausgabe sieht wie folgt aus:

# My Project Constitution

## Core Principles

### I. Test-First (NON-NEGOTIABLE)
TDD mandatory: tests written and approved before any implementation code.
Red-Green-Refactor cycle strictly enforced.

### II. Simplicity
YAGNI principles. Maximum 3 projects for initial implementation.
Additional complexity requires documented justification.

### III. Observability
Structured logging required across all modules.
Text I/O ensures debuggability.

## Governance
Constitution supersedes all other practices. Amendments require documentation,
approval, and a migration plan.

**Version**: 1.0.0 | **Ratified**: 2026-03-25

Warum dies für spätere Schritte von Bedeutung ist

Die vorrangige Ausführung der Konfiguration ist keine rein zeremonielle Angelegenheit. Wenn Sie /speckit.plan aufrufen, liest der Agent diese und führt eine Reihe von Konformitätsprüfungen durch, bevor er irgendetwas generiert:

### Phase -1: Pre-Implementation Gates

#### Simplicity Gate (Article II)
- [ ] Using ≤3 projects?
- [ ] No future-proofing?

#### Test-First Gate (Article I)
- [ ] Tests written before implementation?
- [ ] Contract tests defined?

Ohne eine Verfassung gibt es für diese Prüfschritte keine Maßstäbe. Mit einer Verfassung werden sie zu verbindlichen Vorgaben. Jeder Plan, der einen Prüfschritt nicht besteht, muss entweder überarbeitet werden oder eine begründete Ausnahme in einem eigens dafür vorgesehenen Abschnitt zur Komplexitätsverfolgung dokumentieren.

Die Konfiguration wird zudem weiterverbreitet. Nach der Aktualisierung überprüft der Befehl, ob die Planvorlage, die Spezifikationsvorlage und die Aufgabenvorlage weiterhin synchron sind. Wenn ein neuer Grundsatz eine neue Aufgabenkategorie erfordert (beispielsweise einen obligatorischen Schritt zur Sicherheitsüberprüfung), kennzeichnet der Befehl dies als ausstehende Aktualisierung und listet es in einem Synchronisationsauswirkungsbericht auf.

Was soll man schreiben?

Der Befehl akzeptiert entweder eine konkrete Angabe oder gar keine. Sie können genau sein:

/speckit.constitution Enforce 80% test coverage minimum, prefer composition over
inheritance, never wrap framework APIs in custom abstractions

Oder allgemein:

/speckit.constitution Prioritize user experience consistency and performance

Wenn Sie keine Angaben machen, leitet das System Grundsätze aus dem Repository-Kontext ab. Für ein neues Projekt ohne vorhandene Dokumentation sind die Standardeinstellungen sinnvolle Ausgangspunkte: „Test-First“-Entwicklung, Einfachheit, CLI-Schnittstellen und Integrationstests anstelle von Mocks.

Sie können den Befehl jederzeit erneut ausführen. Bei jeder Aktualisierung wird die Versionsnummer gemäß dem semantischen Versionierungsschema erhöht: „PATCH“ für redaktionelle Änderungen, „MINOR“ für neue Grundsätze und „MAJOR“ für Streichungen. Auf diese Weise können Sie nachvollziehen, wann und warum sich die geltenden Regeln geändert haben.

Halten Sie die Spezifikation kurz. Der Agent liest sie bei jedem nachfolgenden Befehl vollständig vor. Vier bis sechs Grundsätze, die Ihre tatsächlichen unverhandelbaren Anforderungen abdecken, reichen aus. Das Ziel ist nicht die Dokumentation. Es handelt sich um eine Referenz, die so kompakt ist, dass sie während des gesamten Arbeitsablaufs relevant bleibt.

Erstellen der Spezifikation mit /speckit.specify

Hier wird die eigentliche Funktionsbeschreibung eingefügt. Bei der Beschreibung handelt es sich um eine in einfacher Sprache verfasste Darstellung dessen, was Sie entwickeln möchten. Keine Angaben zum Tech-Stack, keine Implementierungsdetails – lediglich eine Beschreibung dessen, was die Funktion ist und warum sie existiert:

/speckit.specify Build a photo organizer that groups photos into albums by date.
Albums can be reordered by drag and drop. Within each album, photos are shown in
a tile grid. Albums are never nested inside other albums.

‌

Der Befehl erstellt einen Git-Zweig, benennt ihn anhand der Feature-Beschreibung und schreibt eine Datei „ spec.md “ in den Ordner „ specs/<branch-name>/ “. Es muss kein Scaffolding manuell erstellt werden.

Was die Spezifikation enthält

Die Ausgabe folgt einer festgelegten Vorlage mit drei obligatorischen Abschnitten:

Anwendungsszenarien und Tests: Die Funktion wird in unabhängig voneinander testbare User Stories unterteilt, die jeweils eine Priorität sowie Akzeptanzszenarien im „Given/When/Then“-Format aufweisen:

### User Story 1 - View Photo Albums (Priority: P1)
A user opens the app and sees their photos grouped into date-based albums.

**Acceptance Scenarios**:
1. Given the user has photos, When they open the app, Then albums are displayed
   grouped by date in reverse chronological order.
2. Given an album is empty, When the user navigates to it, Then a placeholder
   is shown rather than a blank screen.

Funktionale Anforderungen: nummerierte, überprüfbare Aussagen darüber, was das System leisten muss:

- **FR-001**: System MUST group photos into albums by calendar date.
- **FR-002**: Users MUST be able to reorder albums via drag and drop.
- **FR-003**: System MUST display a tile grid within each album.
- **FR-004**: Albums MUST NOT be nested inside other albums.

Erfolgskriterien: messbare, technologieunabhängige Ergebnisse:

- **SC-001**: Users can create and reorder three albums in under 60 seconds.
- **SC-002**: Photo tile grid loads within 2 seconds for albums of 100 photos.

Was die Spezifikation nicht enthält

Die Spezifikationsvorlage ist bewusst restriktiv gehalten. Sie verbietet ausdrücklich Implementierungsdetails: keine Namen von Frameworks, keine Angaben zu Datenbanken, keine API-Struktur. Nach dem Verfassen der Spezifikation wird eine Checkliste durchlaufen, die die Spezifikation als fehlerhaft einstuft, falls Implementierungsdetails darin enthalten sind. Sollten in Ihrer Beschreibung Begriffe wie „React“ oder „PostgreSQL“ vorkommen, müssen Sie damit rechnen, dass diese entfernt oder markiert werden.

Genau diese Trennung ist der entscheidende Punkt. Die Spezifikation definiert, was die Nutzer benötigen. Die Entscheidung über den Technologie-Stack erfolgt erst später als Eingabe für /speckit.plan. Indem Sie diese beiden Aspekte voneinander trennen, können Sie dieselbe Spezifikation im Planungsschritt mit unterschiedlichen Technologieoptionen durchlaufen lassen und die Ergebnisse vergleichen.

Erläuterungszeichen

Sollte Ihre Beschreibung so mehrdeutig sein, dass dies den Anwendungsbereich oder das Verhalten erheblich beeinflussen würde, fügt der Befehl „ [NEEDS CLARIFICATION] “-Markierungen ein und stellt Ihnen bis zu drei Fragen mit Antwortvorschlägen vor:

## Question 1: Authentication scope

**Context**: "Users can reorder albums via drag and drop."

**What we need to know**: Is reordering persisted across sessions, or only for
the current session?

| Option | Answer | Implications |
|--------|--------|--------------|
| A      | Persisted | Requires a storage model for order state |
| B      | Session only | Simpler implementation, resets on reload |
| Custom | Provide your own answer | |

Die Obergrenze liegt bei drei Fragen. Für alles, was unterhalb dieser Grenze liegt, wird ein angemessener Standardwert zugewiesen, der im Abschnitt „Annahmen“ der Spezifikation dokumentiert ist. Das Modell wählt die relevantesten Unklarheiten aus. Umfang und Sicherheit haben Vorrang vor Layout-Präferenzen oder der Standard-Sortierreihenfolge.

Sofern oberhalb des Schwellenwerts keine Unklarheiten bestehen, wird die Spezifikation ohne Rückfragen verfasst, und Sie fahren direkt mit „ /speckit.clarify “ oder „ /speckit.plan “ fort.

Anforderungen mit /speckit.clarify klären

Dieser Schritt ist bedingt. Falls „ /speckit.specify “ keine wesentlichen Mehrdeutigkeiten gefunden hat, fahren Sie direkt mit „ /speckit.plan “ fort. Falls das Programm eine oder mehrere „ [NEEDS CLARIFICATION] “-Markierungen eingefügt hat, führen Sie zunächst „clarify“ aus, um diese zu beseitigen.

Der Befehl liest die aktuelle Spezifikation „ spec.md “ ein und führt zwei Schritte durch: Er stellt jeden ungelösten Marker als strukturierte Frage dar und wartet auf Ihre Antwort, und er durchsucht die Spezifikation nach Lücken, die den Marker-Schwellenwert zwar nicht erreicht haben, aber dennoch bei der Planung zu Problemen führen könnten. In diesem zweiten Durchgang liegt der größte Nutzen. Eine Spezifikation, die vollständig erscheint, enthält oft unausgesprochene Annahmen, die auf diese Weise erkannt werden können, bevor sie zu technischen Entscheidungen werden.

Führen Sie das Programm ohne Argumente aus:

/speckit.clarify

Oder um sich auf einen bestimmten Bereich zu konzentrieren:

/speckit.clarify Focus on the data persistence and offline behaviour questions

Beantwortung einer Frage zur Klarstellung

Jede offene Frage wird in demselben Format dargestellt, das bereits bei der Erstellung der Spezifikation verwendet wurde. Sie beantworten die Frage, indem Sie eine Option auswählen oder eine eigene Antwort eingeben:

## Question 1: Album reorder persistence

**Context**: "Users MUST be able to reorder albums via drag and drop." (FR-002)

**What we need to know**: Is the new order persisted across sessions, or
only for the current session?

| Option | Answer | Implications |
|--------|--------|--------------|
| A      | Persisted across sessions | Requires a storage model for order state |
| B      | Current session only | Simpler implementation, resets on reload |
| Custom | Provide your own answer | |

Your answer: A

Nachdem Sie geantwortet haben, aktualisiert der Befehl „ spec.md “ direkt an Ort und Stelle. Die Markierung „ [NEEDS CLARIFICATION] “ wird durch die aufgelöste Anforderung ersetzt, und alle relevanten Einschränkungen werden dem Abschnitt „Assumptions“ angehängt. Die Versionsnummer der Spezifikation wird erhöht.

Wenn Sie im obigen Beispiel Option A ausgewählt haben, würde sich die funktionale Anforderung wie folgt ändern:

- **FR-002**: Users MUST be able to reorder albums via drag and drop.
  Album order MUST be persisted across sessions.
  **Resolved**: 2026-03-25, persisted via local storage or equivalent.

Wenn sich durch Klarheit neue Fragen ergeben

Die Ausführung von „clarify“ anhand einer Spezifikation kann zu Fragen führen, die bei der Ausführung von „ /speckit.specify “ nicht identifiziert wurden. Dies geschieht, wenn der Befehl eine logische Lücke zwischen zwei Anforderungen feststellt und nicht etwa eine Mehrdeutigkeit innerhalb einer einzelnen Anforderung.

Das Beispiel zum Foto-Organizer: Unter FR-001 heißt es, dass Fotos nach Kalenderdatum gruppiert werden, und unter FR-003 wird angegeben, dass innerhalb jedes Albums ein Kachelraster angezeigt wird. Diese beiden Anforderungen geben keinen Aufschluss darüber, was geschieht, wenn dasselbe Foto in mehreren Datumsbereichen vorkommt. Diese Lücke ist nicht gekennzeichnet, wirkt sich jedoch unmittelbar auf die Datenmodellierung aus. Die Frage ergibt sich aus dem Zusammenspiel der Anforderungen und nicht aus einer der beiden für sich genommen.

Es gibt keine Begrenzung für Folgefragen, jedoch werden in jeder Runde nur die Punkte angesprochen, die in der aktuellen Spezifikation noch ungeklärt sind. Sobald Sie eine Runde ohne neue Fragen abgeschlossen haben, ist die Spezifikation fertiggestellt, und Sie können zu „ /speckit.plan “ übergehen.

Was Sie hier nicht antworten sollten

Der Klärungsschritt sollte auf der funktionalen Ebene bleiben. Wenn eine Frage in den Bereich der Umsetzung abgleitet („Sollten wir IndexedDB oder localStorage für die Persistenz verwenden?“), handelt es sich nicht um eine Klärungsfrage. Es ist eine Frage zum Tech-Stack, die in „ /speckit.plan “ gehört. Die Antwort, die im Klärungsschritt gegeben werden sollte, ist die Anforderung: „Der Bestellstatus muss über Browser-Sitzungen hinweg erhalten bleiben.“ Wie dies erreicht wird, ist Aufgabe des Plans.

Die Spezifikationsvorlage stellt dies sicher, indem sie nach jeder Klärungsrunde dieselbe Überprüfung der Implementierungsdetails durchführt. Sollten Ihre Antworten einen bestimmten Technologienamen oder eine architektonische Entscheidung enthalten, ist damit zu rechnen, dass diese markiert und in einen Annahmenblock statt in die Anforderungen verschoben werden. Indem die Spezifikation an dieser Stelle technologieunabhängig gehalten wird, können Sie während der Planung verschiedene Tech-Stacks vergleichen, ohne Ihre Anforderungen neu formulieren zu müssen.

Wann sollte man auf eine Klarstellung verzichten?

Wenn „ /speckit.specify “ ohne Markierungen abgeschlossen wurde und das Feature klein, unkompliziert und gut verstanden ist, besteht keine Notwendigkeit, „clarify“ auszuführen. Der Befehl ist im Arbeitsablauf nicht zwingend erforderlich. Das Flussdiagramm-Gate existiert aus gutem Grund: Das Hinzufügen einer Klärungsrunde zu einer Spezifikation, die keine benötigt, verlangsamt den Arbeitsablauf, ohne den Plan zu verbessern.

Die einzige Ausnahme besteht darin, dass mehrere Entwickler die Spezifikation vor Beginn der Planung prüfen. Ein Durchlauf durch „ /speckit.clarify “ liefert eine dokumentierte Aufzeichnung darüber, welche Optionen in Betracht gezogen und welche ausgewählt wurden. Diese Aufzeichnung ist nützlich, wenn später jemand in das Feature eingearbeitet wird, selbst wenn keine offenen Punkte zu klären waren.

Erstellen eines Plans mit /speckit.plan

In diesem Schritt trifft die Spezifikation auf die Praxis. Die Darstellung besteht aus einer in einfacher Sprache verfassten Beschreibung Ihres Tech-Stacks und etwaiger architektonischer Einschränkungen. Es bedarf keiner großen Formalitäten, sondern lediglich der Entscheidungen, die Sie bereits getroffen haben:

/speckit.plan The application uses React. Images are not uploaded anywhere and
album order is stored in localStorage.

‌

Der Befehl liest die „ spec.md “ aus Ihrem aktuellen Zweig ein, überprüft sie anhand der Verfassung und erstellt eine Reihe von Planungsartefakten im selben Verzeichnis „ specs/<branch-name>/ “. Diese Artefakte werden von den nächsten beiden Befehlen verwendet. Bei der Umsetzung wird nichts aus dem Nichts generiert. Alles stammt von hier.

Was der Befehl ausgibt

Durch die Ausführung von „ /speckit.plan “ werden je nach Umfang der Funktion bis zu fünf Dateien erstellt:

plan.md ist das zentrale Dokument. Es beginnt mit den in Ihrer Verfassung festgelegten Voraussetzungen für die Einhaltung der Vorschriften vor der Umsetzung und geht anschließend in einen stufenweisen Umsetzungsplan über:

# Implementation Plan: Photo Organizer

## Phase -1: Pre-Implementation Gates

### Simplicity Gate (Article II)
- [x] Using ≤3 projects?
- [x] No future-proofing?

### Test-First Gate (Article I)
- [x] Tests written before implementation?
- [x] Contract tests defined?

## Architecture Overview

**Chosen Stack**: React, localStorage
**Rationale**: FR-001 requires local-only storage. No server component is needed.
localStorage is sufficient for persisting album order without additional dependencies.

## Phase 0: Foundation

**Objective**: Set up project structure and confirm localStorage read/write.
**Dependencies**: None
**Deliverables**: React app scaffolded, localStorage utility wired up, a passing smoke test.

Jede Phase benennt ihre Abhängigkeiten ausdrücklich. Wenn Phase 2 etwas aus Phase 1 benötigt, wird diese Abhängigkeit angegeben. Anhand dieser Angaben ermittelt „ /speckit.tasks “ die Reihenfolge der Aufgaben und ermittelt, welche Aufgaben parallel ausgeführt werden können.

research.md wird generiert, wenn der Tech-Stack Optionen enthält, die sich für einen Vergleich eignen. Sein Zweck besteht darin, die Abwägungen zu dokumentieren, die der Bearbeiter vorgenommen hat, bevor er sich für eine Bibliothek oder einen Ansatz entschieden hat:

# Research: Photo Organizer

## Drag-and-Drop

**Options evaluated**:
- Native HTML5 drag-and-drop API: Available without libraries, works for
  basic reordering.
- @dnd-kit/react: Accessible, touch-friendly, built for React.

**Decision**: @dnd-kit/react. FR-002 requires drag-and-drop and the native
HTML5 API has known issues with touch events on mobile.

Der Umfang von „ research.md “ hängt von der Anzahl der Entscheidungspunkte im Tech-Stack ab. Ein einfacher, klar definierter Stack führt zu einer kurzen Recherchedatei oder gar keiner. Ein Stack mit mehreren umstrittenen Bibliotheksauswahlen führt zu einer längeren. Sie haben darauf keinen direkten Einfluss. Dies ergibt sich aus der Komplexität Ihrer Eingabeaufforderung.

data-model.md setzt die Domänenkonzepte aus der Spezifikation in konkrete Entitätsdefinitionen um:

# Data Model: Photo Organizer

## Entities

### Album
| Field     | Type     | Constraints          | Notes                          |
|-----------|----------|----------------------|--------------------------------|
| id        | INTEGER  | PRIMARY KEY, AUTOINCREMENT |                          |
| name      | TEXT     | NOT NULL             | Derived from date by default   |
| date      | TEXT     | NOT NULL             | ISO 8601 format                |
| sort_order| INTEGER  | NOT NULL, DEFAULT 0  | Persisted per FR-002           |

### Photo
| Field     | Type     | Constraints          | Notes                          |
|-----------|----------|----------------------|--------------------------------|
| id        | INTEGER  | PRIMARY KEY, AUTOINCREMENT |                          |
| album_id  | INTEGER  | NOT NULL, FK → Album.id |                             |
| filename  | TEXT     | NOT NULL             | Local path, not a URL          |
| created_at| TEXT     | NOT NULL             | Used for in-album sort order   |

## Constraints
- Albums are never nested (FR-004). No parent_id column.
- sort_order is the persisted user-defined order (resolved 2026-03-25, clarify step).

Das Schema spiegelt genau das wider, was in der Spezifikation steht – nicht mehr und nicht weniger. Sollte eine Spalte eine Funktion erfüllen, die nicht durch eine funktionale Anforderung abgedeckt ist, erscheint sie hier nicht.

contracts/ ist ein Verzeichnis mit API-Spezifikationsdateien, wobei jede Datei einem Anwendungsbereich entspricht. Bei einer REST-API behandelt jede Datei eine einzelne Ressource. Bei einer reinen Frontend-Anwendung beschreiben die Verträge die Schnittstelle zwischen den Komponenten und der Datenschicht: Funktionssignaturen sowie deren erwartete Eingaben und Ausgaben.

quickstart.md Enthält die wichtigsten Validierungsszenarien, die der Bearbeiter nach Abschluss der Implementierung manuell überprüfen können sollte. Diese entsprechen direkt den Abnahmeszenarien aus der Spezifikation und wurden als nummerierte Checkliste neu formatiert:

# Quickstart Validation

1. Open the app in Firefox and Chrome. Confirm albums are visible.
2. Drag an album to a new position. Reload the page. Confirm the new order persisted.
3. Click into an album. Confirm photos are shown in a tile grid.
4. Attempt to nest one album inside another. This must not be possible.

So überprüfen Sie den Plan

Bevor Sie „ /speckit.tasks “ ausführen, lesen Sie bitte „ plan.md “ durch und halten Sie dabei die Spezifikation neben sich bereit. Zwei Punkte, die Sie überprüfen sollten:

Gate-Status: Jedes Compliance-Gate gemäß der Verfassung sollte mit „ [x] “ gekennzeichnet werden. Ein nicht markiertes Gate bedeutet, dass der Plan einen Konflikt mit Ihren festgelegten Grundsätzen festgestellt hat und diesen nicht auflösen konnte. Der Plan sollte unterhalb der Gates einen Abschnitt zur Komplexitätsverfolgung enthalten, in dem die Ausnahme sowie die Gründe für deren Rechtfertigung dokumentiert sind. Falls die Ausnahme dort nicht aufgeführt ist, führen Sie /speckit.plan mit den folgenden zusätzlichen Hinweisen erneut aus:

/speckit.plan Same stack as before. Flag as a justified exception: the feature
requires three separate React apps because each album type ships as an
independent micro-frontend.

Phasenabhängigkeiten: In jeder Phase unter plan.md wird angegeben, wovon sie abhängt. Verfolgen Sie diese Abhängigkeiten von Phase 0 bis zur letzten Phase. Wenn ein Ergebnis in Phase 2 aufgeführt ist, dessen Abhängigkeit jedoch von keiner vorhergehenden Phase abgedeckt wird, wird diese Lücke während des /speckit.implement als fehlerhafte Aufgabe angezeigt. Es ist besser, dies hier zu erkennen.

Die Überprüfung von „ research.md “ ist optional, aber sinnvoll, wenn Sie mit der Wahl einer Bibliothek nicht einverstanden sind oder wenn eine Entscheidung auf der Grundlage von Annahmen getroffen wurde, die Sie überschreiben möchten. Wenn Sie eine Entscheidung ändern möchten, aktualisieren Sie die Beschreibung Ihres Tech-Stacks und führen Sie den Befehl erneut aus. Die Forschungsdatei wird anhand Ihrer überarbeiteten Eingabe neu generiert.

data-model.md Es lohnt sich, einen kurzen Blick darauf zu werfen, um sicherzustellen, dass die eingeschränkten Felder genau Ihrer Spezifikation entsprechen. Die Spalte „sort_order“ für Alben sollte beispielsweise nur vorhanden sein, wenn in Ihrem „clarify“-Schritt festgelegt wurde, dass die Neuanordnung der Alben dauerhaft gespeichert wird. Enthält das Modell eine Spalte, die einem Merkmal zugeordnet ist, das Sie ausdrücklich ausgeschlossen haben, weicht der Plan von der Spezifikation ab, und eine erneute Ausführung ist die richtige Lösung.

Was die „Tech-Stack“-Anweisung steuert und was nicht

Die Entscheidung bezüglich des Tech-Stacks bestimmt die Auswahl der Bibliotheken und Frameworks. Sie hat jedoch keinen Einfluss auf die Projektstruktur, die Teststrategie oder die Implementierungsphasen. Diese ergeben sich aus dem Grundgerüst und der Spezifikation. Wenn Sie diese Aspekte beeinflussen möchten, aktualisieren Sie bitte das Grundgerüst oder die Spezifikation, bevor Sie den Plan umsetzen.

Ein häufiger Fehler besteht darin, Einschränkungen in die Tech-Stack-Eingabezeile aufzunehmen, die eigentlich in die Spezifikation gehören. „Keine Authentifizierung“ ist keine Entscheidung, die den Tech-Stack betrifft. Es handelt sich um eine Entscheidung zum Umfang, die als funktionale Anforderung oder expliziter Ausschluss in die Spezifikation gehört. Wenn man dies in die Eingabezeile des Plans aufnimmt, umgeht man den Prozess, anstatt es an der richtigen Stelle zu verankern. Wenn das nächste Mal jemand die Spezifikation aktualisiert und den Plan erneut ausführt, verschwindet die Einschränkung.

Wenn Sie das Projekt für eine bestehende Codebasis initialisiert haben, stellen Sie sicher, dass Ihre Konstitution Grundsätze enthält, die auf die bestehende Architektur verweisen. Ohne diesen Kontext behandelt der Plan Ihre Codebasis als leeres Blatt und generiert möglicherweise Datenmodelle und Verträge, die bereits Vorhandenes duplizieren. Nachdem Sie „ /speckit.tasks “ ausgeführt haben, verwenden Sie „ /speckit.analyze “, um zu überprüfen, ob die generierten Artefakte untereinander und mit dem bestehenden Code konsistent sind, bevor Sie mit der Implementierung fortfahren.

Aufschlüsselung mit /speckit.tasks

Es sind keine Argumente erforderlich. Der Befehl lautet plan.md, spec.md, sowie alle eventuell vorhandenen optionalen Artefakte (data-model.md, contracts/, research.md, quickstart.md) aus Ihrem Feature-Verzeichnis:

/speckit.tasks

‌

Die Ausgabe besteht aus einer einzigen Datei: tasks.md. Jede darin enthaltene Aufgabe ist ein Kontrollkästchen, das der Agent nacheinander während des Prozesses „ /speckit.implement “ abarbeiten kann.

Wie „tasks.md“ aufgebaut ist

Die Aufgaben sind in Phasen gegliedert. Die ersten beiden Phasen sind stets identisch:

Anschließend wird jeder User Story aus der Spezifikation eine eigene Phase zugewiesen, geordnet nach Priorität. Eine P1-Story wird zu Phase 3, eine P2-Story zu Phase 4 und so weiter. In der abschließenden Phase werden Feinabstimmungen sowie übergreifende Aspekte wie Fehlerzustände, Barrierefreiheit oder Leistung behandelt.

Innerhalb jeder User-Story-Phase folgt die Reihenfolge einem festen Muster: Tests (falls gefordert), dann Modelle, dann Dienste, dann Endpunkte oder Benutzeroberfläche, dann Integration. Diese Reihenfolge ist bewusst gewählt. Der Entwickler schreibt die Tests vor der Implementierung, wenn TDD in den Vorgaben festgelegt ist. Sollte TDD nicht zu Ihren Grundsätzen gehören, erscheinen Testaufgaben nur dann, wenn dies in der Spezifikation ausdrücklich gefordert wird.

Ein vereinfachtes Beispiel für den Foto-Organizer:

## Phase 1: Setup

- [ ] T001 Initialize React project with Create React App in /photo-organizer
- [ ] T002 Install @dnd-kit/react in /photo-organizer

## Phase 2: Foundational

- [ ] T003 Create Album type definition in src/types/album.ts
- [ ] T004 Create Photo type definition in src/types/photo.ts
- [ ] T005 [P] Create localStorage utility for reading/writing albums in src/utils/storage.ts
- [ ] T006 [P] Create date grouping utility in src/utils/groupByDate.ts

## Phase 3: View Photo Albums [US1]

- [ ] T007 [US1] Create AlbumList component in src/components/AlbumList.tsx
- [ ] T008 [US1] Create AlbumCard component in src/components/AlbumCard.tsx
- [ ] T009 [US1] Render AlbumList in App.tsx with sample data
- [ ] T010 [US1] Add empty album placeholder in AlbumCard.tsx

## Phase 4: Reorder Albums [US2]

- [ ] T011 [US2] Wrap AlbumList with DndContext in src/components/AlbumList.tsx
- [ ] T012 [US2] Persist new order to localStorage on drag end in src/utils/storage.ts
- [ ] T013 [US2] Load persisted order on app start in App.tsx

## Phase 5: Photo Tile Grid [US3]

- [ ] T014 [P] [US3] Create PhotoGrid component in src/components/PhotoGrid.tsx
- [ ] T015 [P] [US3] Create PhotoTile component in src/components/PhotoTile.tsx
- [ ] T016 [US3] Wire album click to navigate to PhotoGrid in App.tsx

## Phase 6: Polish

- [ ] T017 Add loading state for album list in src/components/AlbumList.tsx
- [ ] T018 Verify all quickstart validation scenarios pass

Aufgabenformat

Jede Aufgabe folgt einem strengen Format:

- [ ] T001 [P] [US1] Description with file path

Das Kontrollkästchen (- [ ]) ist ein Pflichtfeld. „ T001 “ ist eine fortlaufende ID. „ [P] “ kennzeichnet die Aufgabe als parallelisierbar, was bedeutet, dass ein Agent, der die parallele Ausführung unterstützt, diese Aufgabe neben anderen Aufgaben unter [P] in derselben Phase ausführen kann. „ [US1] “ ordnet die Aufgabe einer User Story aus der Spezifikation zu. Einrichtungs- und grundlegende Aufgaben haben keine Story-Kennzeichnung. Die Beschreibung endet stets mit einem Dateipfad, damit der Agent genau weiß, wohin er den Code schreiben soll.

Parallele Markierungen

Mit „ [P] “ gekennzeichnete Aufgaben können gleichzeitig ausgeführt werden, da sie unterschiedliche Dateien betreffen und keine Abhängigkeiten zu noch nicht abgeschlossenen Aufgaben innerhalb derselben Phase aufweisen. Im obigen Beispiel, T005 und T006 sind beide [P] da „storage.ts“ und „groupByDate.ts“ keine Kopplung aufweisen. T003 und T004 sind nicht gekennzeichnet [P] da auf Typdefinitionen häufig von nachfolgenden Aufgaben in derselben Phase zurückgegriffen wird und der Aufwand für deren Reihenfolge vernachlässigbar ist.

Agenten, die keine parallele Ausführung unterstützen, ignorieren die Markierung „ [P] “ einfach und führen die Aufgaben der Reihe nach aus. Die fortlaufenden IDs (T001, T002, …) stellen unabhängig von parallelen Markierungen die kanonische Ausführungsreihenfolge dar.

Was Sie vor dem Weitergehen überprüfen sollten

Nachdem die Aufgabenliste erstellt wurde, gibt der Befehl eine Zusammenfassung aus: Gesamtzahl der Aufgaben, Aufgaben pro User Story, Möglichkeiten zur parallelen Bearbeitung sowie einen vorgeschlagenen MVP-Umfang (in der Regel nur User Story 1). Bitte sehen Sie sich diese Zusammenfassung an, bevor Sie den Befehl „ /speckit.implement “ ausführen.

Drei Punkte, auf die Sie achten sollten:

Falls Ihr Team die Arbeit in GitHub Issues erfasst, kann „ /speckit.taskstoissues “ die generierten Aufgaben direkt dorthin übertragen.

Implementierung mit /speckit.implement

Führen Sie das Programm ohne Argumente aus. Der Befehl liest alle erforderlichen Daten aus dem Feature-Verzeichnis ein:

/speckit.implement

‌

Was geschieht, wenn Sie das Programm ausführen?

Als Erstes prüft der Befehl, ob Checklisten vorhanden sind. Falls Ihr Feature-Verzeichnis einen Ordner „ checklists/ “ enthält (der mit dem Befehl „ /speckit.checklist “ erstellt wurde), liest er alle darin enthaltenen Dateien aus und zählt die unvollständigen Einträge. Jede Checkliste mit noch nicht abgehakten Einträgen löst eine Abfrage aus, in der Sie gefragt werden, ob Sie fortfahren oder den Vorgang abbrechen möchten. Sind keine Checklisten vorhanden, wird dieser Schritt übersprungen.

Anschließend lädt der Befehl den vollständigen Implementierungskontext: tasks.md für den Ausführungsplan, plan.md für den Technologie-Stack und die Dateistruktur sowie alle optionalen Artefakte wie data-model.md, contracts/ oder research.md. All diese wurden in früheren Schritten generiert.

Anschließend wird die Projektstruktur überprüft. Bei einem React-Projekt bedeutet dies, dass nach der Datei „ .gitignore “ gesucht und sichergestellt wird, dass sie die Dateien „ node_modules/ “, „ build/ “ und „ .env* “ enthält. Fehlt eine Datei, wird sie durch den Befehl erstellt. Ist eine Datei bereits vorhanden, werden alle fehlenden kritischen Muster an das Ende angehängt.

Phasenweise Ausführung

Aufgaben werden in der Reihenfolge ausgeführt, die durch „ tasks.md “ festgelegt ist. Zuerst Phase 1, dann Phase 2 und so weiter. Innerhalb jeder Phase verarbeitet der Agent die Aufgaben nacheinander, es sei denn, sie sind mit dem Marker „ [P] “ versehen. Parallele Aufgaben können gleichzeitig ausgeführt werden, da sie unterschiedliche Dateien betreffen.

Für den Foto-Organizer sieht das folgendermaßen aus:

Bei jeder abgeschlossenen Aufgabe ändert sich der Status des Kontrollkästchens in der Datei „ tasks.md “ von „ - [ ] “ zu „ - [X] “. Sie können die Datei jederzeit öffnen, um zu sehen, wie weit der Agent bereits fortgeschritten ist.

Fehlerbehandlung

Wenn eine sequenzielle Aufgabe fehlschlägt, wird der Befehl abgebrochen. Er gibt den Fehler mit ausreichendem Kontext aus, damit Sie das Problem diagnostizieren können: welche Datei gerade geschrieben wurde, was schiefgelaufen ist und einen Vorschlag für den nächsten Schritt. Beheben Sie das Problem und führen Sie „ /speckit.implement “ erneut aus. Der Befehl setzt die Ausführung an der Stelle fort, an der er unterbrochen wurde, indem er die Kontrollkästchen in „ tasks.md “ ausliest und alle Aufgaben überspringt, die bereits als „ [X] “ markiert sind.

Parallele Aufgaben verhalten sich unterschiedlich. Wenn eine Aufgabe unter „ [P] “ fehlschlägt, während andere in derselben Gruppe erfolgreich sind, setzt der Befehl die erfolgreichen Aufgaben fort und meldet den Fehler am Ende der Phase. Dies ist für Phase 2 im Foto-Organizer von Bedeutung: Wenn „ T005 “ (storage.ts) fehlschlägt, „ T006 “ (groupByDate.ts) jedoch erfolgreich ist, müssen Sie lediglich das Speicher-Dienstprogramm beheben, bevor Sie fortfahren.

Validierung der Fertigstellung

Nachdem die letzte Aufgabe abgeschlossen ist, führt der Befehl eine abschließende Überprüfung durch. Dabei wird überprüft, ob jede Aufgabe in „ tasks.md “ als „ [X] “ markiert ist, ob die implementierten Funktionen der ursprünglichen Spezifikation entsprechen und ob alle in der Aufgabenliste definierten Tests erfolgreich bestanden wurden. Als Ausgabe wird eine Zusammenfassung angezeigt: die Gesamtzahl der abgeschlossenen Aufgaben, etwaige übersprungene oder fehlgeschlagene Aufgaben sowie der Status jeder einzelnen User Story.

Öffnen Sie nun die App und testen Sie sie anhand Ihrer Spezifikation. Für den Foto-Organizer bedeutet dies, die Seite zu laden, zu überprüfen, ob die Alben aus dem localStorage geladen werden, ein Album per Drag & Drop zu verschieben, um die Reihenfolge anzupassen, die Seite zu aktualisieren, um die Persistenz zu bestätigen, und auf ein Fotoraster zu klicken. Die Schnellstart-Szenarien unter quickstart.md (sofern Sie unter /speckit.plan eines generiert haben) entsprechen genau diesen manuellen Prüfschritten.

Verwendung von Spec Kit in einem bestehenden Projekt

Bis zu diesem Punkt ging man von einem Greenfield-Projekt aus. In der Praxis findet die eigentliche Arbeit jedoch meist in einer bestehenden Codebasis statt. Der Arbeitsablauf umfasst dieselben sechs Schritte, doch drei davon erfordern besondere Sorgfalt: Initialisierung, Aufbau und Planung.

Initialisierung

Anstatt ein neues Verzeichnis anzulegen, initialisieren Sie Spec Kit innerhalb Ihres bestehenden Repositorys:

specify init --here --ai copilot

Dadurch wird das Verzeichnis „ .specify/ “ hinzugefügt und es werden Slash-Befehle registriert, ohne Ihren bestehenden Code zu verändern. Wenn Ihr Projekt umfangreich ist, sollten Sie in Erwägung ziehen, die Initialisierung auf ein bestimmtes Unterverzeichnis zu beschränken. Bei einem Monorepo mit zehn Diensten ist es nicht erforderlich, dass der Agent alle zehn Dienste berücksichtigt, wenn Sie eine Funktion zu einem einzelnen Dienst hinzufügen. Navigieren Sie zunächst in das Verzeichnis des Dienstes und führen Sie von dort aus den Befehl „ specify init --here “ aus. Der Kontext des Agenten bleibt dadurch kleiner und präziser.

Verfassen einer Verfassung, die den bestehenden Gesetzestext berücksichtigt

Die Konzeption ist der wichtigste Schritt bei Brownfield-Projekten. Bei einem Greenfield-Projekt beschreibt die Konzeption, wie Sie arbeiten möchten. Bei einem bestehenden Projekt muss sie zudem beschreiben, was bereits vorhanden ist und was der Beauftragte nicht antasten darf.

Beginnen Sie damit, explizite Richtlinien zu erlassen, die sich auf Ihre Codebasis beziehen:

/speckit.constitution This project is an existing ASP.NET Core Web API with
a layered architecture: Controllers, Services, and Repositories. Do not
regenerate or restructure any existing class. New code must follow the
existing patterns in the Services/ and Repositories/ directories. All new
endpoints must be added to existing controllers where appropriate rather
than creating new ones. Entity Framework Core is the ORM. Do not introduce
a second data access pattern.

Die Spezifikation auf eine Änderung ausrichten, nicht auf das System

Wenn Sie „ /speckit.specify “ ausführen, beschreiben Sie bitte nur die Funktion, die Sie hinzufügen möchten, und nicht das System, in dem sie zum Einsatz kommt. Die Spezifikation sollte wie ein Änderungsantrag formuliert sein, nicht wie eine Systemübersicht:

/speckit.specify Add a notification preferences page where users can toggle
email and push notifications per category. Categories are managed by admins
and already exist in the system as NotificationCategory entities.

Beachten Sie den letzten Satz. Er weist den Bearbeiter darauf hin, dass „ NotificationCategory “ bereits existiert. Dies ist von Bedeutung, da es den Bearbeiter daran hindert, eine funktionale Anforderung zur Erstellung dieser Entität zu verfassen. Rechnen Sie im Rahmen des Klärungsschritts mit einer Frage dazu, wie auf die bestehende Entität zugegriffen wird. Beantworten Sie diese auf funktionaler Ebene wie folgt: „Benachrichtigungskategorien sind für diese Funktion schreibgeschützt und werden über die bestehende Entität ‚ ICategoryRepository ‘ abgerufen.“

Planung unter Berücksichtigung der bestehenden Architektur

Der Schritt „ /speckit.plan “ ist der Punkt, an dem sich Brownfield-Projekte am stärksten von Greenfield-Projekten unterscheiden. Ihre Angabe zum Tech-Stack sollte beschreiben, was bereits vorhanden ist, und nicht, wofür Sie sich entscheiden:

/speckit.plan The project uses ASP.NET Core 8, Entity Framework Core with
SQL Server, and a React frontend served from wwwroot. Authentication is
handled by ASP.NET Identity and is already configured. The new feature
adds a NotificationPreferencesController, a NotificationPreferenceService,
and a React page at /settings/notifications. Use the existing repository
pattern in src/Repositories for data access.

Dieser Detaillierungsgrad liefert dem Plan „step“ genügend Kontext, um eine Datei „ data-model.md “ zu generieren, die das bestehende Schema erweitert, anstatt es zu ersetzen, sowie eine Datei „ plan.md “, deren Phasen auf bestehende Dateien verweisen. Überprüfen Sie die generierte Datei „ plan.md “ sorgfältig: Jede Phase sollte „extend“ oder „add to“ anstelle von „create“ enthalten, wenn sie auf etwas verweist, das bereits existiert.

Durchführung einer Analyse vor der Implementierung

Bei bestehenden Projekten ist „ /speckit.analyze “ nicht optional. Führen Sie diesen Befehl nach „ /speckit.tasks “ und vor „ /speckit.implement “ aus:

/speckit.analyze

Der Befehl gleicht die generierten Artefakte untereinander sowie mit den Dateien in Ihrem Repository ab. Dabei werden Probleme wie die folgenden erkannt:

Beheben Sie alle gemeldeten Probleme, bevor Sie „ /speckit.implement “ ausführen. Das Erkennen eines Namenskonflikts im Analyseschritt dauert nur wenige Sekunden. Wird dieser erst nach der Implementierung entdeckt, müssen Sie den generierten Code vom bestehenden Code entflechten.

Eine praktische Zusammenfassung des Arbeitsablaufs

Bei einem bestehenden Projekt sieht die angepasste Abfolge wie folgt aus:

Die zusätzlichen Schritte (Scoping-Initialisierung, Erstellung einer defensiven Konfiguration, Durchführung der Analyse) verlängern den Arbeitsablauf um etwa zehn Minuten. Das ist weitaus weniger Zeitaufwand als das Debuggen eines Agenten, der Ihre Service-Ebene von Grund auf neu generiert hat.

Was funktioniert gut und was nicht

Der strukturierte Ablauf ist das, was bei Spec Kit am besten funktioniert. Wenn man gezwungen ist, die Anforderungen zu klären, bevor der Plan verfasst wird, und den Plan zu überprüfen, bevor der Entwickler Code schreibt, lassen sich Missverständnisse frühzeitig erkennen. Das klingt selbstverständlich. In der Praxis springt die meisten KI-gestützte Entwicklung jedoch direkt zur Umsetzung, und die Rückkopplungsschleife zur Aufdeckung einer falschen Annahme ist eher eine fehlerhafte Funktion als eine klärende Frage.

Die Aufteilung der Aufgaben gemäß „ /speckit.tasks “ ist zuverlässiger, als den Agenten zu beauftragen, Planung und Umsetzung in einem Schritt durchzuführen. Die Parallelitätsmarkierungen unterstützen Agenten, die die gleichzeitige Ausführung von Aufgaben ermöglichen, und die explizite Reihenfolge verhindert den häufigen Fehlerfall, bei dem ein Agent versucht, eine Funktion zu implementieren, bevor er das Testgerüst geschrieben hat.

Bei Greenfield-Projekten lässt sich der Arbeitsablauf optimal nutzen. Da man bei Null anfängt, erscheint die gesamte sechsstufige Abfolge angemessen: Es gibt keinen bestehenden Code, den der Agent falsch interpretieren könnte, und die in Schritt eins verfasste Konstitution prägt jede nachfolgende Entscheidung.

Brownfield ist schwieriger

Die Einbindung von Spec Kit in eine bestehende Codebasis ist eine ganz andere Sache. Ein gut dokumentierter Fehlerfall sieht folgendermaßen aus: Der Agent wird beauftragt, eine Funktion hinzuzufügen, die auf vorhandenem Code aufbaut. Während der Planungsphase untersucht er die vorhandenen Klassen und erstellt präzise Notizen. Bei der Implementierung behandelt er diese Beschreibungen jedoch als neue Anforderungen und generiert die Klassen von Grund auf neu, wodurch Duplikate entstehen, anstatt den bereits vorhandenen Code zu erweitern.

Das zugrunde liegende Problem besteht darin, dass der Agent während der Implementierung korrekt zwischen „Dies beschreibt etwas, das bereits existiert“ und „Dies ist eine neue Anforderung“ unterscheiden muss. Diese Unterscheidung kann bei längeren Kontextfenstern und komplexeren Codebasen ins Stocken geraten. Die Ausführung von „ /speckit.analyze “ nach der Aufgabengenerierung hilft dabei, Inkonsistenzen zwischen dem Plan und dem bestehenden Code zu erkennen, bevor die Implementierung beginnt; allerdings überprüft das Tool nur die Konsistenz zwischen den einzelnen Artefakten. Es schreibt die Konfiguration nicht neu und verhindert auch nicht, dass der Agent bestehende Klassen neu generiert.

Eine praktische Abhilfe besteht darin, explizite Konfigurationsartikel zu verfassen, die besagen: „Generieren Sie keinen Code neu, der bereits in den folgenden Modulen vorhanden ist.“ Es ist zudem hilfreich, den Umfang dessen, was der Agent sieht, klein und präzise zu halten. Initialisieren Sie Spec Kit für eine Teilmenge der Codebasis anstelle des gesamten Repositorys. Keiner der beiden Ansätze bietet eine Garantie, doch beide verringern das Ausfallrisiko.

Wenn sich Ihre Spezifikation ändert

Spec Kit erstellt für jede Spezifikation einen neuen Git-Zweig. Bei diesem Ansatz wird eine Spezifikation als maßgebliche Quelle für einen einzelnen Änderungsantrag betrachtet, nicht jedoch für eine Funktion über deren gesamte Lebensdauer hinweg. Im GitHub-Blog werden Spezifikationen als „lebendige Artefakte, die sich mit dem Projekt weiterentwickeln“ beschrieben, doch das Modell mit einem eigenen Zweig pro Spezifikation deutet darauf hin, dass Spec Kit derzeit auf der „Spec-First“-Ebene arbeitet und nicht auf der „Spec-Anchored“-Ebene.

Was dies in der Praxis bedeutet: Wenn sich die Spezifikation für eine Funktion während der Implementierung ändert, aktualisieren Sie die Spezifikationsdateien im Zweig, führen Sie bei Bedarf „ /speckit.clarify “ und „ /speckit.plan “ erneut aus und generieren Sie die Aufgabenliste neu, bevor Sie fortfahren. Die spezifikationsgesteuerte Methodik dokumentiert dies wie erwartet: Die Spezifikation ist die maßgebliche Quelle, und der Code wird auf dieser Grundlage neu generiert. Dies funktioniert jedoch nur dann zuverlässig, wenn die Änderung vor Beginn der Implementierung erkannt wird. Wird eine Änderung an der Spezifikation erst nach der Ausführung von „ /speckit.implement “ entdeckt, ist eine manuelle Abstimmung zwischen dem aktualisierten Plan und dem bereits generierten Code erforderlich.

Verzweigung zur Erkundung von Alternativen

Eine Anwendung des Git-Verzweigungsmodells, die gut funktioniert, besteht darin, den Workflow zweimal mit derselben Spezifikation, jedoch unterschiedlichen Eingaben unter /speckit.plan auszuführen. Da Sie den Tech-Stack als Eingabeangabe angeben, können Sie bereits bei der Planung eine Verzweigung vornehmen und zwei separate Implementierungen generieren: beispielsweise eine mit WebSockets und eine mit Server-Sent-Events. Die Aufgabenaufteilungen bleiben getrennt, und Sie können die Implementierungen vergleichen, bevor Sie sich für eine entscheiden. Die Dokumentation unter „spec-driven.md“ beschreibt dies ausdrücklich als Designziel: „Erzeugung mehrerer Implementierungsansätze aus derselben Spezifikation, um verschiedene Optimierungsziele zu untersuchen.“

Der Markdown-Aufwand

Spec Kit erzeugt während eines einzelnen Arbeitsablaufs eine beträchtliche Anzahl von Dateien: spec.md, plan.md, research.md, data-model.md, contracts/, tasks.md, quickstart.md. Bei einer mittelgroßen Funktion in einer bestehenden Codebasis kann die Überprüfung all dieser Elemente länger dauern als die Überprüfung des eigentlichen Codes. Bei einer Funktion im Bereich von 3 bis 5 Story-Punkten kann der Zeitaufwand für die Überprüfung der Spec-Kit-Artefakte dem Zeitaufwand entsprechen, der für die direkte Implementierung der Funktion mittels standardmäßiger KI-gestützter Programmierung erforderlich gewesen wäre.

Dies ist kein Mangel des Tools. Es handelt sich um Kosten, die Sie einkalkulieren müssen. Die Artefakte sind nützlich für umfangreiche Funktionen mit mehreren Mitwirkenden, bei denen die Rückverfolgbarkeit zwischen Anforderung und Implementierung von Bedeutung ist. Für einen Einzelentwickler, der an einer gut verständlichen Codebasis arbeitet, ist der Nutzen dieser Überprüfungszeit geringer.

Wenn die Qualität der Spezifikationen den Engpass darstellt

Eine vage Spezifikation führt zu einem vagen Plan, und „ /speckit.implement “ kann einen ungenauen Aufgabenaufbau nicht ausgleichen. Das Tool deckt das Problem zwar früher auf als bei der herkömmlichen Entwicklung, beseitigt es jedoch nicht. Häufig besteht Unklarheit darüber, wann man auf der funktionalen Ebene bleiben und wann man technische Details hinzufügen sollte. Die Dokumentation des Arbeitsablaufs ist in diesem Punkt nicht ganz einheitlich, und Entwickler, die jahrelang Tickets mit stark implementierungsorientiertem Inhalt verfasst haben, werden instinktiv früher technische Entscheidungen treffen, als es der Prozess vorsieht.

Die „ [NEEDS CLARIFICATION] “-Markierungen, die /speckit.clarify in die Spezifikation einfügt, sind zwar hilfreich, erkennen jedoch nur das, was das Modell als mehrdeutig identifiziert. Eine Anforderung, die zwar präzise formuliert ist, aber eine unausgesprochene Annahme enthält, wird ohne Markierung durchgelassen und taucht später als Fehler auf.

Die Leistungsfähigkeit des Agenten spielt hier eine größere Rolle als bei offenen Eingabeaufforderungen. Die Schritte „Klärung“ und „Planung“ beruhen darauf, dass das Modell Lücken und Abwägungen durchdenkt. Ein schwächeres Modell erzeugt bei „ /speckit.clarify “ oberflächlichere Fragen und einen weniger nützlichen Plan. Bei Modellen mit kleineren Kontextfenstern treten in der Implementierungsphase zudem Probleme auf, wenn Aufgaben auf frühere Dateien verweisen, die aus dem aktiven Kontext herausgescrollt wurden.

Fazit

Die spezifikationsgesteuerte Entwicklung ist kein neues Konzept. Das Verfassen von Spezifikationen vor dem Schreiben des Codes ist seit Jahrzehnten gängige Praxis. Was Spec Kit verändert, sind die Kosten, die mit einer ordnungsgemäßen Umsetzung verbunden sind. Wenn eine gut verfasste Spezifikation direkt eine Aufgabenaufschlüsselung und die Umsetzung generiert, entfällt der Anreiz, diesen Schritt zu überspringen.

Der sechsstufige Arbeitsablauf sorgt dafür, dass die richtigen Gespräche frühzeitig geführt werden. Sie klären, was Sie entwickeln, bevor Sie sich für einen Tech-Stack entscheiden. Sie überprüfen den Plan, bevor der Entwickler auch nur eine einzige Zeile Code schreibt. Diese Abfolge reduziert den Aufwand für Nachbesserungen, der entsteht, wenn mitten in der Umsetzung ein Missverständnis festgestellt wird.

Das „Spec Kit“ funktioniert am besten, wenn Sie das Lastenheft als etwas betrachten, das Sie aktualisieren werden, und nicht als ein Endprodukt, das Sie übergeben. Formulieren Sie es präzise, dann hat der Makler weniger Spielraum für Fehlannahmen.

Referenzen

GitHub. (2025). Spec Kit: Ein Toolkit für den Einstieg in die spezifikationsgesteuerte Entwicklung. https://github.com/github/spec-kit

GitHub. (2025). Methodik der spezifikationsgesteuerten Entwicklung. https://github.com/github/spec-kit/blob/main/spec-driven.md