⚡
★ 86.6k

Usecase: 고급 Todo 앱을 처음부터 구축하기

Superpowers를 처음 접하는 사람도 브레인스토밍부터 실행까지 — 단 한 번의 작업 세션만으로 완전한 Todo 애플리케이션을 구축할 수 있습니다. 이것은 전체 워크플로우를 경험할 수 있는 이상적인 입문 usecase입니다.

배경

프로토타입/데모용 Todo 애플리케이션을 만들고 싶습니다 — 프레젠테이션할 때 충분히 인상적이면서, Superpowers 프로세스를 처음부터 끝까지 따라 구축하는 것이 목표입니다.

요구사항:

  • CRUD: 추가, 수정, 삭제, 완료 표시
  • 상태, 우선순위, 카테고리별 필터/검색
  • 분류 (Work / Personal / Study) 및 우선순위 (High / Medium / Low)
  • Drag & drop으로 순서 정렬
  • 각 todo에 마감일 설정
  • Dark mode (토글 + 시스템 설정 연동)
  • 데이터를 localStorage에 저장 (백엔드 불필요)

기술 스택:

  • Vite + React 18 + TypeScript
  • shadcn/ui + Tailwind CSS
  • @dnd-kit (drag & drop)
  • date-fns (날짜 처리)
  • Vitest + React Testing Library

배울 수 있는 것

이 가이드에서는 Superpowers의 네 가지 핵심 기술을 적용합니다:

  1. Brainstorming & Design -- Q&A를 통한 요구사항 탐색, 접근 방식 비교, visual companion으로 레이아웃 선택
  2. Writing Plans -- 명확한 검증 기준이 있는 11개 task로 분할
  3. TDD -- hook과 component에 대해 테스트를 먼저 작성
  4. Debugging & Verification -- 실제 호환성 오류 처리 및 모든 것이 동작하는지 검증

최종 목표: 12개 테스트 케이스가 모두 통과하고, 프로덕션 빌드가 성공하며, 규율 있는 프로세스로 구축된 완전한 Todo 애플리케이션.

단계별 실습

1단계: Todo App 디자인 브레인스토밍

AI와 채팅을 열고 다음과 같이 말합니다:

"React + TypeScript로 간단한 Todo 애플리케이션을 만들고 싶습니다. 코드를 작성하기 전에 브레인스토밍을 해봅시다."

AI는 브레인스토밍 모드에 진입하고, visual companion(브라우저에 목업 표시)을 활성화한 후, 하나씩 질문을 시작합니다:

질문 1: "이 Todo 애플리케이션의 주요 목적은 무엇인가요?"

  • A) 학습/포트폴리오 프로젝트
  • B) 일상적으로 사용할 개인 애플리케이션
  • C) 프레젠테이션용 프로토타입/데모

C) 프로토타입/데모를 선택합니다 -- 프레젠테이션할 때 인상적이어야 합니다.

질문 2: "애플리케이션에 어떤 기능이 필요한가요?"

  • A) 기본 -- 추가, 수정, 삭제, 완료 표시
  • B) 중급 -- A + 필터/검색, 카테고리, 우선순위
  • C) 고급 -- B + drag & drop, 마감일, dark mode, localStorage 저장

C) 고급을 선택합니다 -- 데모에 적합한 완전한 기능.

질문 3: "데이터는 어디에 저장하나요?"

  • A) LocalStorage only
  • B) Mock API (json-server 또는 MSW)
  • C) Real backend (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 목록.
- 장점: 간단, 라우팅 불필요, 부드러운 UX
- 단점: 모든 것이 하나의 뷰에 집중

## Approach B: Multi-Page with React Router
여러 페이지로 분할: Dashboard, Todo List, Settings.
- 장점: 명확한 구조, 확장 용이
- 단점: todo 앱에는 과도함, 추가 의존성

## Approach C: Kanban Board Style
Todo를 컬럼 형태로 표시 (To Do / In Progress / Done), 컬럼 간 drag & drop.
- 장점: 데모 시 시각적으로 인상적
- 단점: 훨씬 복잡하고, 필터/정렬이 어려움

처음에는 Kanban (C)을 선택했지만, visual companion에서 목업을 확인한 후 Approach A: Single Page로 변경합니다 -- 기능과 복잡도 사이의 최적의 균형.

AI는 레이아웃에 대해 추가 질문합니다:

  • A) Sidebar + Main Content (Todoist 스타일)
  • B) Top Filter Bar + Centered List (미니멀리스트)

B) Top Filter Bar + Centered List를 선택합니다 -- 깔끔하고 미니멀합니다.

AI는 3개 섹션으로 구성된 상세 디자인 spec을 작성합니다:

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 state 관리 (add, edit, delete, toggle, reorder)
  - Custom hook useTodos() — 로직 + localStorage 동기화 처리
  - Custom hook useTheme() — dark/light mode 토글

Component Structure:
  App
  ├── Header (제목, 통계, dark mode 토글)
  ├── FilterBar (상태 pills, 우선순위 pills, 카테고리 pills, 검색)
  ├── TodoInput (새 todo 추가 폼 — 클릭 시 확장)
  ├── TodoList (DnD 컨테이너)
  │   └── TodoItem[] (체크박스, 제목, 우선순위 배지, 카테고리, 마감일, 액션)
  └── EditTodoDialog (shadcn dialog)

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

FilterBar:
  - 가로 배치된 Pill 버튼: Status (All|Active|Done) | Priority | Category
  - AND 조합 (Active + High + Work → 모든 조건을 만족하는 todo만 표시)
  - 오른쪽에 검색 입력

TodoItem:
  - Checkbox | Title | Priority badge (색상) | Category tag | Due date | Menu (⋮)
  - Hover → 왼쪽에 drag handle 표시
  - Completed → 흐리게 + 취소선
  - Overdue → 마감일이 빨간색으로 표시

Drag & Drop:
  - @dnd-kit/sortable로 드래그 앤 드롭 정렬
  - 필터링된 뷰에서 드래그 시, 상대적 순서만 업데이트;
    필터에 의해 숨겨진 항목은 순서 유지

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

Dark Mode: Tailwind dark: class + 시스템 설정 기본값
localStorage: 쓰기 시 300ms 디바운스, 유효하지 않은 데이터의 경우 빈 배열로 폴백
Testing: Vitest + RTL로 useTodos hook, TodoInput, TodoItem 테스트

AI는 spec 품질을 확인하기 위해 spec reviewer를 dispatch합니다. Reviewer가 3가지 작은 권장사항과 함께 승인합니다 (이미 spec에 반영됨).

승인 후 다음 단계로 넘어갑니다.

Superpowers 참고: 디자인 spec은 docs/superpowers/specs/에 저장되며, spec reviewer가 plan 작성 전에 자동으로 검토합니다. 자세한 내용은 Brainstorming을 참조하세요.

2단계: Superpowers가 상세 Plan 작성

디자인 spec을 기반으로, AI는 작업을 11개 task로 분할합니다 (단순한 앱에 비해 상당히 많습니다):

## Plan: Todo App

### Task 1: Project Scaffold
- Vite + React + TS, Tailwind, shadcn/ui, @dnd-kit, date-fns
- Vitest + React Testing Library
- 검증: npm run build 성공

### Task 2: Types & Storage Utilities
- src/types/todo.ts — interface Todo, Filters, constants
- src/lib/storage.ts — localStorage helpers
- 검증: TypeScript 컴파일 OK

### Task 3: useTodos Hook (TDD)
- 테스트 먼저: src/hooks/use-todos.test.ts
- 코드: src/hooks/use-todos.ts
- 검증: 6/6 테스트 통과

### Task 4: Filter Logic & useTheme Hook
- src/lib/filters.ts — applyFilters() 함수
- src/hooks/use-theme.ts — dark mode 토글

### 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
- 검증: 3/3 테스트 통과

### Task 7: TodoItem Component (TDD)
- 테스트 먼저: src/components/todo-item.test.tsx (DndContext wrapper 포함)
- 코드: src/components/todo-item.tsx
- 검증: 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에 연결
- 검증: npm run build 성공

### Task 11: Final Polish & All Tests
- 검증: 12/12 테스트 통과, tsc --noEmit OK, build OK

AI가 plan reviewer를 dispatch하여 검토합니다. Reviewer가 2가지 문제를 발견합니다:

  1. TodoItem 테스트에 DndContext wrapper 누락 -- useSortable에는 DndContext provider가 필요하므로 테스트가 실패할 수 있습니다
  2. Task 1에서 Sonner가 설치되지 않음 -- Task 10에서 오류가 발생할 수 있습니다

AI는 구현을 시작하기 전에 두 가지 모두 수정합니다.

Superpowers 참고: Plan은 docs/superpowers/plans/에 저장되며 실행 전에 자동으로 리뷰됩니다. 자세한 내용은 Writing Plans를 참조하세요.

**"OK, 구현을 시작합시다."**라고 확인합니다.

3단계: Plan에 따른 구현 (TDD: RED → GREEN → REFACTOR)

AI는 plan에 따라 각 task를 실행합니다. 테스트가 있는 task는 모두 TDD 사이클을 따릅니다.

Task 1: Project Scaffold

Vite + React + TS 스캐폴딩, 모든 의존성 설치. 실제 발생한 문제:

  • Vite 8이 호환되지 않음 — @tailwindcss/vite와 → --legacy-peer-deps 사용
  • shadcn/ui init 실패 — import alias 누락 → tsconfig + vite.config에서 @/ alias 설정
  • Vite 8이 shadcn과 충돌 → Vite 7로 다운그레이드

실무 교훈: 스캐폴딩이 항상 순조롭지는 않습니다. 라이브러리 간 호환성 문제는 흔한 일입니다. 중요한 것은 디버그하고 우회하는 방법을 아는 것입니다.

Task 2: Types & Storage Utilities

파일설명
src/types/todo.tsInterface Todo, Filters, type aliases, constants (PRIORITIES, CATEGORIES)
src/lib/storage.tsloadTodos(), saveTodos(), loadTheme(), saveTheme() (에러 처리 포함)

Task 3: useTodos Hook (TDD)

파일설명
테스트src/hooks/use-todos.test.ts6개 테스트 케이스: starts empty, add todo, toggle todo, delete todo, edit todo, reorder todos
코드src/hooks/use-todos.tsuseReducer + localStorage 동기화, expose: addTodo, toggleTodo, deleteTodo, editTodo, reorderTodos

RED → npx vitest run → FAIL (파일이 아직 존재하지 않음) → GREEN → Hook 구현 → 6/6 PASS

Task 4: Filter Logic & useTheme

파일설명
src/lib/filters.tsapplyFilters() -- 상태, 우선순위, 카테고리, 검색에 대한 AND 조합 필터
src/hooks/use-theme.tsdark/light 토글, localStorage + 시스템 설정과 동기화

Task 5: Header & FilterBar

파일설명
src/components/header.tsx앱 이름, 통계 카운터, dark mode 토글 (Sun/Moon 아이콘)
src/components/filter-bar.tsx상태/우선순위/카테고리용 Pill 버튼 + 검색 입력

Task 6: TodoInput (TDD)

파일설명
테스트src/components/todo-input.test.tsx3개 테스트 케이스: render placeholder, call onAdd on submit, clear input after submit
코드src/components/todo-input.tsx폼으로 확장되는 입력: 제목, 우선순위 드롭다운, 카테고리 드롭다운, 날짜 선택기

RED → FAIL → GREEN → 3/3 PASS

Task 7: TodoItem (TDD)

파일설명
테스트src/components/todo-item.test.tsx3개 테스트 케이스: render title + priority, toggle checkbox, line-through when completed. 참고: 테스트에 DndContext + SortableContext wrapper 필요
코드src/components/todo-item.tsxSortable item (drag handle, 체크박스, 우선순위 배지, 카테고리 태그, 마감일, 드롭다운 메뉴)

RED → FAIL → GREEN → 3/3 PASS

Task 8-9: TodoList + EditTodoDialog

파일설명
src/components/todo-list.tsx@dnd-kit/core + @dnd-kit/sortable를 사용한 DnD 컨테이너, empty state
src/components/edit-todo-dialog.tsx편집 폼이 있는 shadcn Dialog: 제목, 우선순위, 카테고리, 날짜 선택기

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 테스트 통과.

각 task의 TDD 프로세스: AI가 테스트를 먼저 작성 → 테스트 실행하여 FAIL 확인 → 최소한의 코드 구현 → 테스트 실행하여 PASS 확인 → 필요 시 리팩토링 → 커밋. 자세한 내용은 TDD를 참조하세요.

4단계: Verification -- 전체 검증

11개 task가 모두 완료되었습니다. 최종 검증을 실행합니다.

전체 테스트 스위트 실행

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)

Type check & Build

npx tsc --noEmit    # No errors
npm run build       # 빌드 성공

선언

Todo App 완성. 12/12 테스트 통과. 프로덕션 빌드 OK. TypeScript 오류 없음. 기능별로 정리된 10개의 깔끔한 커밋.

결과

전체 프로세스를 완료한 후, 다음과 같은 결과물을 얻게 됩니다:

완전한 기능:

  • CRUD todos (추가, 수정, 삭제, 완료 토글)
  • 상태, 우선순위, 카테고리 + 검색에 대한 AND 조합 필터
  • Drag & drop으로 순서 정렬
  • 마감일과 overdue 경고 (빨간색)
  • Dark mode (토글 + 시스템 설정 연동)
  • localStorage 영구 저장 (300ms 디바운스)
  • shadcn/ui를 사용한 반응형 미니멀리스트 UI
  • 통계 표시 (전체 task, 활성, 완료)

12개 테스트 케이스 100% 통과 범위:

  • Custom hook useTodos: add, toggle, delete, edit, reorder, empty state
  • Component TodoInput: render, submit, clear
  • Component 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에는 별도의 type check가 있음), tsc --noEmit은 통과했으며 dev mode에서도 표시되지 않았습니다.

4. TodoItem 테스트에 DnD wrapper 필요

useSortable hook은 DndContext + SortableContext provider가 필요합니다. wrap하지 않으면 테스트가 크래시됩니다. Plan reviewer가 구현 전에 이를 발견하고 수정했습니다.

교훈: 이것이 verification이 중요한 이유입니다. 많은 오류는 프로덕션 빌드 또는 엄격한 type check 실행 시에만 나타나며, dev mode에서는 보이지 않습니다.

핵심 포인트

1. 브레인스토밍이 적절한 시점에 마음을 바꿀 수 있게 해줍니다

처음에는 Kanban Board를 선택했지만, visual companion에서 목업을 확인한 후 Single Page가 더 적합하다는 것을 깨달았습니다. 브레인스토밍 단계에서의 변경은 코드 0줄의 비용입니다. 구현 후 변경은 수 시간의 리팩토링이 필요합니다.

2. Plan reviewer가 코드 작성 전에 버그를 잡아냅니다

Reviewer가 plan에서 2가지 문제를 발견했습니다 (테스트에서 DndContext wrapper 누락, sonner 의존성 누락). 리뷰가 없었다면, 이러한 버그는 구현 도중에 나타나 디버깅 시간을 낭비하게 만들었을 것입니다.

3. 호환성 문제는 흔한 일입니다

11개 task 중 3개에서 호환성 문제가 발생했습니다 (Vite 8, shadcn alias, asChild prop). 이것은 여러분의 버그가 아닙니다 -- JavaScript 생태계의 현실입니다. 프로세스가 이를 빠르게 발견하고 수정할 수 있게 해주므로 당황할 필요가 없습니다.

4. useReducer + Custom Hook + TDD는 강력한 조합입니다

useTodos hook은 모든 로직 (CRUD, reorder, localStorage 동기화)을 캡슐화하고 6개의 테스트 케이스로 보호됩니다. UI가 복잡해져도 (drag & drop, 필터, 편집 다이얼로그) 로직은 독립적으로 테스트되었으므로 안정적입니다.

5. 11개 task지만 각 task는 작고 명확합니다

"고급 Todo 앱 구축"은 무섭게 들립니다. 하지만 11개 task로 나누면, 각 task는 1-2개 파일만 생성하고 자체 검증이 있습니다. 전체 앱을 머릿속에 담을 필요 없이 -- 현재 task에만 집중하면 됩니다.

6. 이것은 실제 프로젝트를 위한 디딤돌입니다

이 "고급" Todo 앱에는 이미 다음이 포함되어 있습니다: custom hooks, drag & drop, dark mode, shadcn/ui, localStorage persistence, TDD, 자동 리뷰. 이것들은 모든 React 프로젝트에서 재사용할 패턴입니다.

현실은 튜토리얼처럼 완벽하지 않습니다. 호환성 문제, 라이브러리 변경, 예상치 못한 오류를 만나게 됩니다. Superpowers 프로세스는 이러한 문제를 제거하지 않습니다 -- 어디서부터 시작해야 할지 모르고 헤매는 대신, 조기에 발견하고 체계적으로 처리할 수 있게 도와줍니다.