Flashcards-App mit GitHub SpecKit + VS Code Codex bauen (Spec-Driven Tutorial)

In diesem Beitrag erstellen wir eine lokale Flashcards-App mit GitHub SpecKit + der Codex VS Code-Erweiterung. Wir folgen dem Spec-Driven Development-Flow von Anfang bis Ende: Spezifizieren → Planen → Aufgaben → Implementieren.

Warum SpecKit für dieses Projekt? #why-speckit-for-this-project

Traditionelles „Vibe-Coding“ führt oft zu unklaren Ergebnissen. SpecKit dreht den Spieß um: Du schreibst eine klare Spezifikation, erstellst einen technischen Plan, zerlegst ihn in Aufgaben und lässt deinen Coding-Agenten kleine, testbare Schnitte implementieren – wobei du in der Schleife bleibst.

Voraussetzungen #prerequisites

• VS Code mit der Codex-Erweiterung (anmelden mit deinem ChatGPT-Account).
• Git, Python 3.11+ und uv (Paketmanager/Launcher).
• macOS, Linux oder Windows (WSL wird für die beste Codex-Erfahrung auf Windows empfohlen).

Öffentliches Repo: https://github.com/nicklaunches/flashcards-speckit

Specify CLI installieren #install-specify-cli

Dauerhafte Installation (empfohlen):

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

Projekt mit Codex verknüpfen und initialisieren #init-project-wired-to-codex

Erstelle einen Ordner und initialisiere SpecKit für Codex:

mkdir flashcards-speckit && cd flashcards-speckit
specify init . --ai copilot
# Windows-Benutzer können hinzufügen: --script ps

Öffne den Ordner in VS Code und bestätige, dass das Copilot-Panel angemeldet ist.

Leitplanken setzen: Verfassung #set-guardrails-constitution

Führe im Copilot-Chat aus:

/speckit.constitution
Erstelle Prinzipien, die sich konzentrieren auf:
- vertikale Slices; 90% der Aufgaben < 30 Minuten
- React + Next.js + TypeScript; SQLite via Drizzle
- Unit-Tests für Kernlogik; Playwright Smoke-Tests
- Barrierefreiheit (WCAG AA); Performance-Budget: First Load JS < 160KB
- Offline-First (keine externen Dienste, alles lokal)

Dies erstellt/aktualisiert eine Verfassungsdatei, der zukünftige Schritte folgen müssen.

Die Spec schreiben (Was und Warum) #write-the-spec-what-and-why

/speckit.specify
Baue eine lokale, offline-first Flashcards-App für schnelle Lerneinheiten.

User Stories:
1) Als Lerner kann ich Decks erstellen (Name & Beschreibung).
2) Ich kann Karten hinzufügen, bearbeiten und löschen (Vorderseite/Rückseite).
3) Ich kann ein Deck mit einem Quiz-Flow studieren (Vorderseite anzeigen → umdrehen → Easy/Hard markieren).
4) Spaced Repetition: Karten je nach Schwierigkeit hoch-/runterstufen, um sie später wieder aufzutauchen.
5) Suche: Decks und Karten nach Text filtern.
6) Daten werden lokal gespeichert; App läuft ohne Netzwerk.
7) Gutes UX: Tastenkürzel (J/K/Space), responsives Layout, Dark Mode.

Akzeptanzkriterien:
- CRUD bleibt zwischen Sitzungen erhalten
- Quiz zeigt Fortschritt & Genauigkeit an
- Mobile + Desktop responsiv

Bleibe bei Was/Warum. Technische Entscheidungen werden in der nächsten Phase getroffen.

Den technischen Plan erstellen (Wie) #create-the-technical-plan-how

/speckit.plan
Tech & Architektur:
- Next.js + React + TypeScript; Tailwind für UI
- SQLite-Datei-DB mit Drizzle ORM; Repository-Abstraktion
- App Router; Server Actions für Mutationen
- Unit: Vitest; E2E: Playwright (Smoke-Flows)
- Tastaturkürzel-Util; Dark Mode via CSS-Variablen
- Code-Splitting der Study-Seite; kleines Bundle behalten

Dies wird zum Bauplan, dem Codex folgt.

In Aufgaben zerlegen #break-it-into-tasks

/speckit.tasks

Erwarte eine generierte tasks.md mit angeordneten Schritten, Dateipfaden und Test-Stubs. Optionale Qualitäts-Pässe:

• /speckit.clarify — schärfe ungenaue Teile
• /speckit.analyze — cross-check Spec ↔ Plan Abdeckung
• /speckit.checklist — generiere eine QA-Checkliste („Unit-Tests für English“)

Mit Codex implementieren #implement-with-codex

/speckit.implement

Codex folgt der tasks.md, um die App zu skripten, Code zu schreiben und Tests unter deinen Freigaben zu verknüpfen.

Ausführen und testen #run-and-test

pnpm i
pnpm dev
# öffne http://localhost:3000

Sobald alle Aufgaben aus dem Plan erledigt sind: Versuche: Deck erstellen → Karten hinzufügen → Study drücken → J/K/Space während des Quizzes nutzen.

Spaced Repetition hinzufügen #add-spaced-repetition

Bitte Codex, die Funktion zu erweitern:

/speckit.tasks
Scheduler hinzufügen:
- Jede Karte hat einen Schwierigkeits-Bucket (1..3)
- EASY → +1 Bucket (max 3); HARD → −1 (min 1)
- Session zieht mehr aus unteren Buckets
- Persistiere lastReviewed, nextDue

Führe dann erneut /speckit.implement aus.

Empfohlene Repo-Struktur #recommended-repo-structure

flashcards-speckit/
  .specify/          # Spec, Plan, Tasks, Research-Artefakte
  .github/           # Prompts/Templates von SpecKit hinzugefügt
  app/               # Next.js Routen & UI
  db/                # Drizzle Schema + Seed
  tests/             # Unit + E2E
  README.md

Fehlerbehebung #troubleshooting

• Slash-Befehle erscheinen nicht im Codex-Menü: Stelle sicher, dass du mit --ai codex initialisiert hast, du dich im Projekt-Stammordner befindest und Codex CLI/Erweiterung auf dem neuesten Stand ist. Wenn nur /speckit.constitution angezeigt wird, aktualisiere Tools und Templates; einige Agenten-Integrationen werden im Laufe der Zeit behoben.
• Agent-Checks fehlschlagen: Füge --ignore-agent-tools zu specify init hinzu, um Checks zu überspringen und Templates trotzdem abzurufen.
• Windows: Codex ist auf Windows experimentell – nutze WSL für die besten Ergebnisse.

Nächste Ideen #next-ideas

• Import/Export von Decks als JSON
• Markdown-Unterstützung auf Karten-Vorder-/Rückseiten
• Bildkarten
• Streaks + Insights-Ansicht
• „Erneut studieren“ intelligentes Deck mittels nextDue

Quellen #sources

• SpecKit Repo (README: Install, Agents, Slash Commands) — https://github.com/github/spec-kit
• GitHub Blog: Spec-driven development with AI: Get started with a new open-source toolkit — https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/
• GitHub Blog: Spec-driven development — Using Markdown as a programming language — https://github.blog/ai-and-ml/generative-ai/spec-driven-development-using-markdown-as-a-programming-language-when-building-with-ai/
• Codex IDE extension docs — https://developers.openai.com/codex/ide/ locale: “de” originalSlug: “build-flashcards-app-github-speckit-vscode-codex-tutorial”