ユースケース: 高度な Todo アプリをゼロから構築する

Superpowers を初めて使う方でも、ブレインストームから動作確認まで、たった1回の作業セッションで完全な Todo アプリを構築できます。これは Superpowers の全プロセスを体験するための理想的な入門ユースケースです。

---

背景

プロトタイプ/デモとして Todo アプリを構築したい場合 -- プレゼンテーションで十分な印象を与えられるものを、Superpowers のプロセスに従って最初から最後まで構築します。

要件:

• CRUD: 追加、編集、削除、完了マーク
• ステータス、優先度、カテゴリによるフィルタリング/検索
• 分類（Work / Personal / Study）と優先度（High / Medium / Low）
• ドラッグ＆ドロップによる並べ替え
• 各 Todo に期限日を設定
• ダークモード（トグル + システム設定に連動）
• データは localStorage に保存（バックエンド不要）

技術スタック:

• Vite + React 18 + TypeScript
• shadcn/ui + Tailwind CSS
• @dnd-kit（ドラッグ＆ドロップ）
• date-fns（日付処理）
• Vitest + React Testing Library

---

学べること

このチュートリアルでは、Superpowers の4つのコアスキルを実践します：

1. Brainstorming & Design -- Q&A による要件の発掘、アプローチの比較、ビジュアルコンパニオンでのレイアウト選択
2. Writing Plans -- 明確な検証基準を持つ11のタスクに分割
3. TDD -- フックとコンポーネントのテストを先に記述
4. Debugging & Verification -- 実際の互換性エラーの処理とすべてが動作することの確認

最終目標: 12のテストケースがすべてパスし、プロダクションビルドが成功する、規律あるプロセスで構築された完全な Todo アプリです。

---

ステップバイステップ実践

ステップ 1: Todo アプリの設計をブレインストームする

AI とのチャットを開き、以下のように伝えます：

「React + TypeScript でシンプルな Todo アプリを作りたいです。コードを書く前にブレインストームしましょう。」

AI はブレインストームモードに入り、ビジュアルコンパニオン（ブラウザ上にモックアップを表示）を起動して、1つずつ質問を始めます：

質問 1: 「この Todo アプリの主な目的は何ですか？」

• A) 学習/ポートフォリオプロジェクト
• B) 日常的に使う個人アプリ
• C) プレゼン用のプロトタイプ/デモ

選択: C) プロトタイプ/デモ -- プレゼンで印象的に見える必要があります。

質問 2: 「アプリにはどの機能が必要ですか？」

• A) 基本 -- 追加、編集、削除、完了マーク
• B) 中級 -- A + フィルタリング/検索、カテゴリ、優先度
• C) 高度 -- B + ドラッグ＆ドロップ、期限日、ダークモード、localStorage 永続化

選択: C) 高度 -- デモ用にフル機能を搭載。

質問 3: 「データの保存先は？」

• A) LocalStorage のみ
• B) Mock API（json-server または MSW）
• C) 実際のバックエンド（Firebase/Supabase）

選択: A) LocalStorage -- シンプルで、バックエンド不要。

質問 4: 「UI/スタイリングのアプローチは？」

• A) Tailwind CSS
• B) shadcn/ui + Tailwind
• C) CSS Modules / Styled Components
• D) Ant Design / MUI

選択: B) shadcn/ui + Tailwind -- 美しく、プロフェッショナルで、カスタマイズが容易。

質問 5: 「ツール/ビルドツールは？」

• A) Vite
• B) Next.js
• C) Create React App

選択: A) Vite -- 高速、軽量、最も普及。

十分な情報を収集した後、AI は3つのアプローチを提示します：

## Approach A: Single Page — All-in-One（推奨）
アプリ全体が1ページに収まります。サイドバーにフィルタ/カテゴリ、メインエリアに Todo リスト。
- Pros: シンプル、ルーティング不要、スムーズな UX
- Cons: すべてが1つのビューに集約される

## Approach B: Multi-Page と React Router
複数のページに分割: Dashboard、Todo List、Settings。
- Pros: 明確な構造、拡張が容易
- Cons: Todo アプリには過剰、依存関係が増える

## Approach C: Kanban Board Style
Todo をカラム形式で表示（To Do / In Progress / Done）、カラム間のドラッグ＆ドロップ。
- Pros: デモ時にビジュアルインパクトが強い
- Cons: はるかに複雑、フィルタ/ソートが困難

最初は Kanban（C）を選びましたが、ビジュアルコンパニオンでモックアップを確認した後、Approach A: Single Page に変更しました -- 機能と複雑さのバランスが最も良いためです。

AI はレイアウトについてさらに質問します：

• A) Sidebar + Main Content（Todoist 風）
• B) Top Filter Bar + Centered List（ミニマリスト）

選択: B) Top Filter Bar + Centered List -- すっきりとしたミニマリストデザイン。

AI は3つのセクションからなる詳細なデザイン仕様を作成します：

DESIGN SPEC: Todo App

=== Section 1: Architecture & Data Model ===

Data Model:
  interface Todo {
    id: string
    title: string
    completed: boolean
    priority: 'high' | 'medium' | 'low'
    category: 'Work' | 'Personal' | 'Study'
    dueDate: string | null
    order: number
    createdAt: string
  }

State Management:
  - useReducer で todo ステートを管理（add, edit, delete, toggle, reorder）
  - カスタムフック useTodos() — ロジック + localStorage の同期を処理
  - カスタムフック useTheme() — ダーク/ライトモードのトグル

Component Structure:
  App
  ├── Header（タイトル、統計、ダークモードトグル）
  ├── FilterBar（ステータスピル、優先度ピル、カテゴリピル、検索）
  ├── TodoInput（新規 Todo 追加フォーム — クリックで展開）
  ├── TodoList（DnD コンテナ）
  │   └── TodoItem[]（チェックボックス、タイトル、優先度バッジ、カテゴリ、期限日、アクション）
  └── EditTodoDialog（shadcn dialog）

=== Section 2: UI Components & Interactions ===

FilterBar:
  - 横並びのピルボタン: Status (All|Active|Done) | Priority | Category
  - AND で結合（Active + High + Work → すべてを満たす todo のみ表示）
  - 右側に検索入力

TodoItem:
  - Checkbox | Title | Priority badge（色付き）| Category tag | Due date | Menu (⋮)
  - ホバー → 左側にドラッグハンドルを表示
  - 完了 → 半透明 + 取り消し線
  - 期限超過 → 期限日を赤で表示

Drag & Drop:
  - @dnd-kit/sortable でドラッグ＆ドロップによる並べ替え
  - フィルタ表示中のドラッグ時は、相対的な order のみ更新;
    フィルタで非表示の項目は order を維持

=== Section 3: Dark Mode & Persistence ===

Dark Mode: Tailwind dark: class + システム設定をデフォルトに
localStorage: 書き込み時に 300ms のデバウンス、無効なデータの場合は空配列にフォールバック
Testing: Vitest + RTL で useTodos フック、TodoInput、TodoItem をテスト

AI は spec reviewer をディスパッチして仕様の品質をチェックします。レビュアーは3つの小さな推奨事項付きで承認しました（仕様に反映済み）。

承認後、次のフェーズに進みます。

Superpowers メモ: デザイン仕様は docs/superpowers/specs/ に保存され、spec reviewer がプラン作成前に自動チェックします。詳しくは Brainstorming をご覧ください。

---

ステップ 2: Superpowers が詳細なプランを作成する

デザイン仕様に基づき、AI は作業を 11のタスク に分割します（シンプルなアプリに比べてかなり多い）：

## Plan: Todo App

### Task 1: Project Scaffold
- Vite + React + TS, Tailwind, shadcn/ui, @dnd-kit, date-fns
- Vitest + React Testing Library
- Verification: npm run build が成功すること

### Task 2: Types & Storage Utilities
- src/types/todo.ts — interface Todo, Filters, constants
- src/lib/storage.ts — localStorage helpers
- Verification: TypeScript のコンパイルが OK

### Task 3: useTodos Hook (TDD)
- テスト先行: src/hooks/use-todos.test.ts
- コード: src/hooks/use-todos.ts
- Verification: 6/6 テストがパス

### Task 4: Filter Logic & useTheme Hook
- src/lib/filters.ts — applyFilters() 関数
- src/hooks/use-theme.ts — ダークモードトグル

### Task 5: Header & FilterBar Components
- src/components/header.tsx
- src/components/filter-bar.tsx

### Task 6: TodoInput Component (TDD)
- テスト先行: src/components/todo-input.test.tsx
- コード: src/components/todo-input.tsx
- Verification: 3/3 テストがパス

### Task 7: TodoItem Component (TDD)
- テスト先行: src/components/todo-item.test.tsx（DndContext ラッパー付き）
- コード: src/components/todo-item.tsx
- Verification: 3/3 テストがパス

### Task 8: TodoList + Drag & Drop
- src/components/todo-list.tsx

### Task 9: EditTodoDialog
- src/components/edit-todo-dialog.tsx

### Task 10: Assemble App + Toast
- すべてのコンポーネントを App.tsx に統合
- Verification: npm run build が成功すること

### Task 11: Final Polish & All Tests
- Verification: 12/12 テストがパス、tsc --noEmit OK、build OK

AI は plan reviewer をディスパッチしてチェックします。レビュアーが2つの問題を発見しました：

1. TodoItem テストに DndContext ラッパーがない -- useSortable には DndContext プロバイダーが必要で、テストが失敗する
2. Task 1 で Sonner がインストールされていない -- Task 10 でエラーが発生する

AI は実装開始前に両方を修正しました。

Superpowers メモ: プランは docs/superpowers/plans/ に保存され、実行前に自動レビューされます。詳しくは Writing Plans をご覧ください。

確認: 「OK、実装を開始しましょう。」

---

ステップ 3: プランに沿った実装（TDD: RED → GREEN → REFACTOR）

AI はプランに従ってタスクを順番に実行します。テストがあるタスクはすべて TDD サイクルに従います。

Task 1: Project Scaffold

Vite + React + TS のスキャフォールドと全依存関係のインストール。実際の問題に遭遇しました：

• Vite 8 が未対応 -- @tailwindcss/vite との互換性がない → --legacy-peer-deps を使用
• shadcn/ui init が失敗 -- import alias の不足 → tsconfig + vite.config で @/ エイリアスを設定
• Vite 8 と shadcn の競合 → Vite 7 にダウングレード

実践的な教訓: スキャフォールドが常にスムーズにいくとは限りません。ライブラリ間の互換性問題はよくあることです。重要なのは、デバッグとワークアラウンドの方法を知っていることです。

Task 2: Types & Storage Utilities

ファイル	説明
src/types/todo.ts	Interface Todo, Filters, type aliases, constants (PRIORITIES, CATEGORIES)
src/lib/storage.ts	loadTodos(), saveTodos(), loadTheme(), saveTheme() とエラーハンドリング

Task 3: useTodos Hook (TDD)

	ファイル	説明
テスト	src/hooks/use-todos.test.ts	6テストケース: starts empty, add todo, toggle todo, delete todo, edit todo, reorder todos
コード	src/hooks/use-todos.ts	useReducer + localStorage 同期、公開: addTodo, toggleTodo, deleteTodo, editTodo, reorderTodos

RED → npx vitest run → FAIL（ファイルが存在しない） → GREEN → フックを実装 → 6/6 PASS

Task 4: Filter Logic & useTheme

ファイル	説明
src/lib/filters.ts	applyFilters() -- ステータス、優先度、カテゴリ、検索を AND で結合するフィルタ
src/hooks/use-theme.ts	ダーク/ライトの切り替え、localStorage + システム設定と同期

Task 5: Header & FilterBar

ファイル	説明
src/components/header.tsx	アプリ名、統計カウンター、ダークモードトグル（Sun/Moon アイコン）
src/components/filter-bar.tsx	ステータス/優先度/カテゴリのピルボタン + 検索入力

Task 6: TodoInput (TDD)

	ファイル	説明
テスト	src/components/todo-input.test.tsx	3テストケース: render placeholder, call onAdd on submit, clear input after submit
コード	src/components/todo-input.tsx	クリックでフォームに展開する入力: title, priority dropdown, category dropdown, date picker

RED → FAIL → GREEN → 3/3 PASS

Task 7: TodoItem (TDD)

	ファイル	説明
テスト	src/components/todo-item.test.tsx	3テストケース: render title + priority, toggle checkbox, line-through when completed。注意: テストには DndContext + SortableContext ラッパーが必要
コード	src/components/todo-item.tsx	ドラッグハンドル付きソート可能アイテム、チェックボックス、優先度バッジ、カテゴリタグ、期限日、ドロップダウンメニュー

RED → FAIL → GREEN → 3/3 PASS

Task 8-9: TodoList + EditTodoDialog

ファイル	説明
src/components/todo-list.tsx	@dnd-kit/core + @dnd-kit/sortable による DnD コンテナ、空の状態表示
src/components/edit-todo-dialog.tsx	編集フォーム付き shadcn Dialog: title, priority, category, date picker

Task 10: Assemble App

すべてを App.tsx に統合: useTodos + useTheme + applyFilters + Toaster。プロダクションビルド成功。

Task 11: Final Polish

tsc --noEmit パス OK ですが、npm run build で asChild prop の TypeScript エラーを検出 -- shadcn v2 は radix の代わりに base-ui を使用しており、render prop に変更が必要。修正後 → ビルド OK、12/12 テストパス。

各タスクでの TDD プロセス: AI がテストを先に記述 → テスト実行で FAIL を確認 → 最小限のコードを実装 → テスト実行で PASS を確認 → 必要に応じてリファクタリング → コミット。詳しくは TDD をご覧ください。

---

ステップ 4: Verification -- 全体の検証

11のタスクすべてが完了しました。最終検証を実行します。

テストスイート全体を実行

npx vitest run

✓ src/hooks/use-todos.test.ts (6 tests)
  ✓ useTodos > starts with empty todos
  ✓ useTodos > adds a todo
  ✓ useTodos > toggles a todo
  ✓ useTodos > deletes a todo
  ✓ useTodos > edits a todo
  ✓ useTodos > reorders todos

✓ src/components/todo-input.test.tsx (3 tests)
  ✓ TodoInput > renders placeholder input
  ✓ TodoInput > calls onAdd with todo data on submit
  ✓ TodoInput > clears input after submit

✓ src/components/todo-item.test.tsx (3 tests)
  ✓ TodoItem > renders todo title and priority
  ✓ TodoItem > calls onToggle when checkbox clicked
  ✓ TodoItem > shows line-through when completed

Test Files  3 passed (3)
     Tests  12 passed (12)

型チェック & ビルド

npx tsc --noEmit    # No errors
npm run build       # ビルド成功

宣言

Todo アプリ完成。12/12 テストパス。プロダクションビルド OK。TypeScript エラーなし。各機能ごとの10クリーンコミット。

---

結果

プロセス全体を完了した後、以下のものが得られます：

完全な機能:

• CRUD todos（追加、編集、削除、完了トグル）
• ステータス、優先度、カテゴリ + 検索による AND 結合フィルタ
• ドラッグ＆ドロップによる並べ替え
• 期限超過の警告付き期限日（赤色表示）
• ダークモード（トグル + システム設定に連動）
• localStorage 永続化（300ms デバウンス）
• shadcn/ui によるレスポンシブでミニマリストな UI
• 統計表示（総タスク数、アクティブ、完了）

12のテストケースが100%パス:

• カスタムフック useTodos: add, toggle, delete, edit, reorder, empty state
• コンポーネント TodoInput: render, submit, clear
• コンポーネント TodoItem: render, toggle, completed style

ファイル構造:

src/
  App.tsx
  index.css
  test-setup.ts
  types/
    todo.ts
  lib/
    storage.ts
    filters.ts
    utils.ts
  hooks/
    use-todos.ts
    use-todos.test.ts
    use-theme.ts
  components/
    header.tsx
    filter-bar.tsx
    todo-input.tsx
    todo-input.test.tsx
    todo-item.tsx
    todo-item.test.tsx
    todo-list.tsx
    edit-todo-dialog.tsx
    ui/  (shadcn components)

---

実際に遭遇した問題

理想的なチュートリアルとは異なり、実際のセッションでは多くの問題に対処する必要がありました：

1. Vite 8 が Tailwind プラグインと互換性がない

@tailwindcss/vite が Vite 8 をサポートしていない → --legacy-peer-deps でインストール後、shadcn も競合するため Vite 7 にダウングレード。

2. import alias の不足により shadcn/ui init が失敗

shadcn は @/ import alias を必要とする → tsconfig で baseUrl + paths、vite.config で resolve.alias を設定する必要がありました。

3. shadcn v2 が radix の代わりに base-ui を使用

asChild prop が機能しなくなった → PopoverTrigger と DropdownMenuTrigger で render prop に変更が必要。このエラーは npm run build（vite build には独自の型チェックがある）でのみ発生し、tsc --noEmit はパス OK で、dev モードでも報告されませんでした。

4. TodoItem テストに DnD ラッパーが必要

useSortable フックは DndContext + SortableContext プロバイダーを必要とします。ラップしないとテストがクラッシュします。plan reviewer が実装前に発見し修正しました。

教訓: これが verification が重要な理由です。多くのエラーはプロダクションビルドや厳密な型チェック時にのみ発生し、dev モードでは見えません。

---

重要なポイント

1. ブレインストームは適切なタイミングでの方向転換を助ける

最初は Kanban Board を選びましたが、ビジュアルコンパニオンでモックアップを見たとき、Single Page の方が適していることに気づきました。ブレインストーム段階での変更はコード0行のコストです。実装後の変更は何時間ものリファクタリングを要します。

2. Plan reviewer がコード作成前にバグを発見する

レビュアーがプランの2つの問題を発見しました（テストに DndContext ラッパーがない、sonner 依存関係がない）。レビューがなければ、これらのバグは実装中に現れ、デバッグに時間を費やすことになります。

3. 互換性の問題は日常茶飯事

11タスク中3つで互換性の問題が発生しました（Vite 8、shadcn alias、asChild prop）。これはあなたのバグではありません -- JavaScript エコシステムの現実です。プロセスがあれば、混乱する代わりに素早く発見して修正できます。

4. useReducer + Custom Hook + TDD は強力なコンボ

useTodos フックはすべてのロジック（CRUD、reorder、localStorage 同期）をカプセル化し、6つのテストケースで保護されています。UI が複雑な場合（ドラッグ＆ドロップ、フィルタ、編集ダイアログ）でも、独立してテストされているためロジックは安定しています。

5. 11タスクだが、各タスクは小さく明確

「高度な Todo アプリを構築する」は大変そうに聞こえます。しかし11のタスクに分割すると、各タスクは1-2ファイルを作成するだけで、独自の検証基準があります。アプリ全体を頭に入れる必要はありません -- 現在のタスクに集中するだけです。

6. 実際のプロジェクトへのステップ

この「高度な」Todo アプリには、カスタムフック、ドラッグ＆ドロップ、ダークモード、shadcn/ui、localStorage 永続化、TDD、自動レビューが含まれています。これらはすべての React プロジェクトで再利用できるパターンです。

---

現実はチュートリアルのように完璧ではありません。 互換性の問題、ライブラリの変更、予期しないエラーに遭遇するでしょう。Superpowers のプロセスはこれらの問題を排除するものではありません -- どこから始めればよいかわからず途方に暮れる代わりに、早期に発見し体系的に対処する手助けをしてくれます。