GitHub SpecKit + VS Code Codexでフラッシュカードアプリを作る（仕様駆動チュートリアル）

この投稿では、GitHub SpecKit + Codex VS Code拡張機能を使用して、ローカルのフラッシュカードアプリを構築します。仕様駆動開発（Spec-Driven Development）のフローをエンドツーエンドで追います：仕様 → 計画 → タスク → 実装。

なぜこのプロジェクトにSpecKitを選ぶのか？ #why-speckit-for-this-project

従来の「雰囲気コーディング」（vibe-coding）は成果物が曖昧になりがちです。SpecKitはその常識を覆します：明確な仕様を書き、技術計画を立て、タスクに分解し、コーディングエージェントに小さな、テスト可能なスライスを実装させながら、あなたがそのプロセスを loops で管理します。

前提条件 #prerequisites

• Codex拡張機能が入ったVS Code（ChatGPTアカウントでサインイン）。
• Git、Python 3.11+、uv（パッケージ/ランチャー）。
• macOS、Linux、またはWindows（WindowsではCodexの最適な体験のためにWSLを推奨）。

公開リポジトリ： https://github.com/nicklaunches/flashcards-speckit

Specify CLIのインストール #install-specify-cli

永続インストール（推奨）：

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

Codexと連携してプロジェクトを初期化 #init-project-wired-to-codex

フォルダを作成し、Codex用にSpecKitを初期化します：

mkdir flashcards-speckit && cd flashcards-speckit
specify init . --ai copilot
# Windowsユーザーは次を追加できます: --script ps

VS Codeでフォルダを開き、Copilotパネルがサインインしていることを確認します。

ガードレールの設定：Constitution #set-guardrails-constitution

Copilotチャットで実行します：

/speckit.constitution
以下の点に焦点を当てた原則を作成してください：
- 縦スライス；タスクの90%を30分以内に収める
- React + Next.js + TypeScript；DrizzleによるSQLite
- コアロジックの単体テスト；Playwrightでのスモークテスト
- アクセシビリティ（WCAG AA）；パフォーマンス予算：First Load JS < 160KB
- オフラインファースト（外部サービスなし、すべてローカル）

これにより、今後のステップが従わなければならないConstitutionファイルが作成/更新されます。

仕様を書く（何を・なぜ） #write-the-spec-what-and-why

/speckit.specify
クイックな学習セッション用の、ローカルでオフラインファーストなフラッシュカードアプリを構築してください。

ユーザーストーリー：
1) 学習者として、デッキ（名前と説明）を作成できる。
2) カード（表面/裏面）を追加、編集、削除できる。
3) デッキをクイズフローで学習できる（表面を表示 → 裏返し → Easy/Hardをマーク）。
4) 間隔反復：難易度に応じてカードを昇格/降格し、後で再表示する。
5) 検索：テキストでデッキとカードをフィルタリングする。
6) データはローカルに保存され、アプリはネットワークなしで動作する。
7) 良いUX：キーボードショートカット（J/K/Space）、レスポンシブレイアウト、ダークモード。

受入基準：
- CRUDはセッション間で持続する
- クイズは進捗と精度を表示する
- モバイル＋デスクトップレスポンシブ

何/なぜに焦点を絞ります。技術的な選択肢は次のフェーズで扱います。

技術計画を作成（どのように） #create-the-technical-plan-how

/speckit.plan
技術とアーキテクチャ：
- Next.js + React + TypeScript；UIにはTailwind
- Drizzle ORMによるSQLiteファイルDB；リポジトリ抽象化
- App Router；ミューテーションにはServer Actions
- 単体テスト：Vitest；E2E：Playwright（スモークフロー）
- キーボードショートカットユーティリティ；CSS変数によるダークモード
- 学習ページのコード分割；バンドルを小さく保つ

これがCodexが従う設計図になります。

タスクに分解 #break-it-into-tasks

/speckit.tasks

順序付けられたステップ、ファイルパス、テストスタブが含まれた生成された tasks.md を期待してください。オプションの品質向上パス：

• /speckit.clarify — 暗黙的な部分を明確にする
• /speckit.analyze — 仕様と計画のカバー率を相互確認する
• /speckit.checklist — QAチェックリストを生成する（「英語の単体テスト」など）

Codexで実装 #implement-with-codex

/speckit.implement

Codexは tasks.md に従ってアプリをスキャフォールドし、コードを書き、あなたの承認のもとでテストを接続します。

実行とテスト #run-and-test

pnpm i
pnpm dev
# http://localhost:3000 を開く

計画のすべてのタスクが完了したら、試してみてください：デッキ作成 → カード追加 → 学習 を押す → クイズ中に J/K/Space を使用する。

間隔反復の追加 #add-spaced-repetition

Codexに拡張を依頼します：

/speckit.tasks
スケジューラを追加：
- 各カードは難易度バケット（1..3）を持つ
- EASY → バケット+1（最大3）；HARD → バケット-1（最小1）
- セッションはより低いバケットから多く引き出す
- lastReviewed, nextDueを永続化する

その後、再度 /speckit.implement を実行します。

推奨リポジトリ構成 #recommended-repo-structure

flashcards-speckit/
  .specify/          # spec, plan, tasks, research artifacts
  .github/           # SpecKitによって追加されたprompts/templates
  app/               # Next.js routes & UI
  db/                # drizzle schema + seed
  tests/             # unit + e2e
  README.md

トラブルシューティング #troubleshooting

• スラッシュコマンドがCodexメニューに表示されない：--ai codex で初期化したか、プロジェクトのルートにいるか、Codex CLI/拡張機能が最新かを確認してください。/speckit.constitution のみが表示される場合は、ツールとテンプレートを更新してください。一部のエージェント統合は時間が経つにつれて修正されます。
• エージェントチェックが失敗する：specify init に --ignore-agent-tools を追加してチェックをスキップし、とにかくテンプレートを取得します。
• Windows：CodexはWindowsで実験的です—最良の結果を得るにはWSLを使用してください。

次のアイデア #next-ideas

• デッキのJSONインポート/エクスポート
• カード表面でのMarkdownサポート
• 画像カード
• ストリート＋インサイトビュー
• nextDue を使用した「再学習」スマートデッキ

出典 #sources

• SpecKitリポジトリ（README: install, agents, slash commands） — https://github.com/github/spec-kit
• GitHubブログ: 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ブログ: 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: “ja” originalSlug: “build-flashcards-app-github-speckit-vscode-codex-tutorial”