GitHub SpecKit + VS Code Codex로 플래시카드 앱 만들기 (명세 주도 튜토리얼)

이 포스트에서는 GitHub SpecKit + Codex VS Code 확장을 사용하여 로컬 플래시카드 앱을 구축합니다. 명세 → 계획 → 작업 → 구현에 이르는 Spec-Driven Development(명세 주도 개발) 흐름을 끝까지 따를 것입니다.

이 프로젝트에 SpecKit을 사용하는 이유는? #why-speckit-for-this-project

전통적인 “바이브 코딩(vibe-coding)“은 결과가 불확실합니다. SpecKit은 이를 뒤집습니다: 명확한 명세를 작성하고, 기술 계획을 세우며, 작업으로 분할한 뒤, 코딩 에이전트가 작고 테스트 가능한 단위를 구현하도록 하면서 여러분이 과정에 참여하게 됩니다.

사전 준비사항 #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); 성능 예산: 첫 로드 JS < 160KB
- 오프라인 우선 (외부 서비스 없음, 모두 로컬)

이것은 향후 단계가 따라야 하는 헌법 파일을 생성/업데이트합니다.

명세 작성 (무엇과 왜) #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; 리포지토리 추상화
- 앱 라우터; 변형을 위한 서버 액션
- 단위 테스트: Vitest; E2E: Playwright (스모크 흐름)
- 키보드 단축키 유틸리티; CSS 변수를 통한 다크 모드
- 학습 페이지 코드 분할; 번들 크기 유지

이것은 Codex가 따를 청사진이 됩니다.

작업으로 분할 #break-it-into-tasks

/speckit.tasks

순서가 매겨진 단계, 파일 경로, 테스트 스텁이 포함된 생성된 tasks.md를 기대하세요. 선택적 품질 검토:

• /speckit.clarify — 명시되지 않은 부분 보강
• /speckit.analyze — 명세 ↔ 계획 커버리지 교차 확인
• /speckit.checklist — QA 체크리스트 생성 (“unit tests for English” 등)

Codex로 구현 #implement-with-codex

/speckit.implement

Codex는 tasks.md를 따라 앱을 스캐폴딩하고, 코드를 작성하며, 여러분의 승인 하에 테스트를 연결합니다.

실행 및 테스트 #run-and-test

pnpm i
pnpm dev
# http://localhost:3000 열기

계획의 모든 작업을 완료한 후: 덱 생성 → 카드 추가 → 학습(Study) 클릭 → 퀴즈 중 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/          # 명세, 계획, 작업, 연구 산출물
  .github/           # SpecKit이 추가한 프롬프트/템플릿
  app/               # Next.js 경로 및 UI
  db/                # Drizzle 스키마 + 시드
  tests/             # 단위 + E2E
  README.md

문제 해결 #troubleshooting

• Copilot 메뉴에 슬래시 명령어가 표시되지 않음: --ai codex로 초기화했는지, 프로젝트 루트에 있는지, Codex CLI/확장이 최신 버전인지 확인하세요. /speckit.constitution만 표시된다면, 도구와 템플릿을 업데이트하세요. 일부 에이전트 통합은 시간이 지나면 수정됩니다.
• 에이전트 확인 실패: specify init에 --ignore-agent-tools를 추가하여 확인을 건너뛰고 템플릿을 가져오세요.
• Windows: Windows에서 Codex는 실험적 기능입니다. 최상의 결과를 위해 WSL을 사용하세요.

다음 아이디어 #next-ideas

• 덱을 JSON으로 가져오기/내보내기
• 카드 면에 마크다운 지원
• 이미지 카드
• 연속 학습(Streak) 및 인사이트 뷰
• nextDue를 사용하는 “다시 학습” 스마트 덱

출처 #sources

• SpecKit 리포지토리 (README: 설치, 에이전트, 슬래시 명령어) — 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 확장 문서 — https://developers.openai.com/codex/ide/