Créez une application de Flashcards avec GitHub SpecKit + VS Code Codex (Tutoriel Spec-Driven)

Dans cet article, nous allons construire une application Flashcards locale en utilisant GitHub SpecKit + l’extension VS Code Codex. Nous suivrons le flux de développement Spec-Driven Development de bout en bout : Spécifier → Planifier → Tâches → Implémenter.

Pourquoi SpecKit pour ce projet ? #why-speckit-for-this-project

Le “vibe-coding” traditionnel rend les résultats flous. SpecKit change la donne : vous écrivez une spec claire, créez un plan technique, le divisez en tâches, et laissez votre agent de codage implémenter de petites tranches testables avec vous dans la boucle.

Prérequis #prerequisites

• VS Code avec l’extension Codex (connectez-vous avec votre compte ChatGPT).
• Git, Python 3.11+, et uv (gestionnaire de paquets/launcher).
• macOS, Linux, ou Windows (WSL recommandé pour la meilleure expérience Codex sur Windows).

Dépôt public : https://github.com/nicklaunches/flashcards-speckit

Installer Specify CLI #install-specify-cli

Installation persistante (recommandée) :

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

Initialiser le projet connecté à Codex #init-project-wired-to-codex

Créez un dossier et initialisez SpecKit pour Codex :

mkdir flashcards-speckit && cd flashcards-speckit
specify init . --ai copilot
# Les utilisateurs Windows peuvent ajouter : --script ps

Ouvrez le dossier dans VS Code et confirmez que le panneau Copilot est connecté.

Définir les garde-fous : Constitution #set-guardrails-constitution

Dans le chat Copilot, exécutez :

/speckit.constitution
Créer des principes axés sur :
- des tranches verticales ; 90% des tâches < 30 minutes
- React + Next.js + TypeScript ; SQLite via Drizzle
- tests unitaires pour la logique cœur ; Playwright smoke
- accessibilité (WCAG AA) ; budget perf : First Load JS < 160KB
- offline-first (pas de services externes, tout en local)

Cela crée/met à jour un fichier de constitution que les étapes futures doivent suivre.

Écrire la Spec (quoi et pourquoi) #write-the-spec-what-and-why

/speckit.specify
Construire une application Flashcards locale, offline-first, pour des sessions d'étude rapides.

User Stories :
1) En tant qu'apprenant, je peux créer des Decks (nom & description).
2) Je peux ajouter, éditer et supprimer des Cartes (recto/verso).
3) Je peux étudier un Deck avec un flux de quiz (montrer recto → retourner → marquer Facile/Difficile).
4) Répétition espacée : promouvoir/dépromouvoir les cartes par difficulté pour les resurfacer plus tard.
5) Recherche : filtrer les decks et cartes par texte.
6) Les données sont stockées localement ; l'application fonctionne sans réseau.
7) Une UX soignée : raccourcis clavier (J/K/Space), disposition responsive, mode sombre.

Critères d'acceptation :
- CRUD persiste entre les sessions
- Quiz montre la progression & précision
- Responsive Mobile + Desktop

Gardez le focus sur le quoi/pourquoi. Sauvegardez les choix techniques pour la phase suivante.

Créer le Plan Technique (comment) #create-the-technical-plan-how

/speckit.plan
Tech & Architecture :
- Next.js + React + TypeScript ; Tailwind pour l'UI
- Fichier DB SQLite avec Drizzle ORM ; abstraction repository
- App Router ; Server Actions pour les mutations
- Unit : Vitest ; E2E : Playwright (flux smoke)
- Utilitaire raccourcis clavier ; mode sombre via variables CSS
- Code-splitting page étude ; garder le bundle petit

Cela devient le blueprint que Codex suivra.

Le diviser en Tâches #break-it-into-tasks

/speckit.tasks

Attendez-vous à un tasks.md généré avec des étapes ordonnées, des chemins de fichiers et des tests factices. Passes de qualité optionnelles :

• /speckit.clarify — resserrer les points mal spécifiés
• /speckit.analyze — vérifier la couverture spec ↔ plan
• /speckit.checklist — générer une checklist QA (“tests unitaires pour English”)

Implémenter avec Codex #implement-with-codex

/speckit.implement

Codex suit tasks.md pour générer l’application, écrire le code et connecter les tests sous vos approbations.

Exécuter et tester #run-and-test

pnpm i
pnpm dev
# ouvrir http://localhost:3000

Une fois que vous avez terminé toutes les tâches du plan : Essayez : créer Deck → ajouter Cartes → cliquer sur Study → utiliser J/K/Space pendant le quiz.

Ajouter la répétition espacée #add-spaced-repetition

Demandez à Codex d’étendre la fonctionnalité :

/speckit.tasks
Ajouter le scheduler :
- Chaque carte a un bucket de difficulté (1..3)
- FACILE → +1 bucket (max 3) ; DIFFICILE → −1 (min 1)
- La session tire plus des buckets inférieurs
- Persister lastReviewed, nextDue

Puis réexécutez /speckit.implement.

Structure de dépôt recommandée #recommended-repo-structure

flashcards-speckit/
  .specify/          # spec, plan, tasks, artefacts de recherche
  .github/           # prompts/templates ajoutés par SpecKit
  app/               # routes & UI Next.js
  db/                # schéma drizzle + seed
  tests/             # unit + e2e
  README.md

Dépannage #troubleshooting

• Les commandes slash n’apparaissent pas dans le menu Codex : assurez-vous d’avoir initialisé avec --ai codex, d’être à la racine du projet, et que l’extension Codex CLI est à jour. Si seul /speckit.constitution s’affiche, mettez à jour les outils et templates ; certaines intégrations d’agents sont corrigées avec le temps.
• Échecs des checks de l’agent : ajoutez --ignore-agent-tools à specify init pour ignorer les checks et récupérer les templates quand même.
• Windows : Codex est expérimental sur Windows — utilisez WSL pour de meilleurs résultats.

Idées pour la suite #next-ideas

• Importer/exporter les decks en JSON
• Support Markdown sur les faces des cartes
• Cartes avec images
• Série + vue d’insights
• Deck intelligent “Refaire l’étude” utilisant nextDue

Sources #sources

• Dépôt SpecKit (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/
• Docs extension Codex IDE — https://developers.openai.com/codex/ide/