AI와 사양 기반 개발(spec-driven development)을 사용하여 버려졌던 라이프 카운터가 어떻게 Star Wars

이 글은 GitHub Finish-Up-A-Thon Challenge를 위한 제출물입니다.

2024년에 기본적인 라이프 카운터(life counter)로 시작했다가 버려졌고, 마침내 다시 돌아와 완성하게 된 앱... 이번에는 Star Wars Unlimited를 위한 제대로 된 덱 테스트 동반자로서 말이죠.

🛠️ 내가 만든 것

SWU Playtesting은 트레이딩 카드 게임(TCG)인 Star Wars Unlimited를 위해 React Native + Expo (web + Android)로 구축된 동반자 앱입니다. 이 앱은 당신의 덱이 실제로 어떻게 성능을 내는지 추적합니다. 덱을 등록하고, 테스트 게임을 기록할 수 있으며, 각 덱의 승률, 매치업(matchups), 그리고 기록을 추적합니다. 또한 게임을 하는 동안 여전히 라이프를 계산해야 하기 때문에, 이 모든 기능은 테마가 적용된 라이프 카운터(life counter) 역할도 겸합니다.

요약하자면: 이 앱은 _"이 게임은 누가 이기고 있는가?"_라는 질문을 _"내 덱 중 실제로 어떤 덱이 이기는가?"_라는 질문으로 바꿔줍니다.

⏳ 시작점 (미완성 프로젝트)

2024년에 저는 Star Wars Unlimited용 라이프 카운터(life counter)로 사용할 수 있는 앱을 만들기 시작했습니다. 시중에 있는 라이프 카운터들은 이 게임에 제대로 맞춰져 있지 않았고, 테마 측면에서도 게임과 아무런 관련이 없었기에, 제가 직접 사용할 수 있는 React Native 앱을 직접 만들어 보기로 결정했습니다.

더 큰 무언가를 만들고 싶었지만, 시간이 흐르면서 결국 프로젝트를 포기하게 되었습니다. 기본적인 라이프 카운터(life counter)로서는 작동했지만, 색상, 초기 라이프 포인트 등 그 어떤 것도 커스텀할 수 있는 방법이 없었습니다. 모든 것이 정적(static)이었습니다. 스타일조차 딱히 좋지 않았습니다. 최소한 설정(Settings) 화면이라도 필요했습니다.

당시 모습은 이랬습니다:

<table><tbody><tr><td><img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fraw.githubusercontent.com%2FIcarusTheFly%2Fswu-playtesting%2Ffinish-up-a-thon-challenge%2Fdocs%2Fscreenshots%2Flegacy%2Flife-counter.png" width="780" alt="원래 라이프 카운터" height="1688"></td><td><img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fraw.githubusercontent.com%2FIcarusTheFly%2Fswu-playtesting%2Ffinish-up-a-thon-challenge%2Fdocs%2Fscreenshots%2Flegacy%2Fdialog.png" width="780" alt="원래 초기화 대화 상자" height="1688"></td></tr></tbody></table>

두 개의 라이프 총합, 하나의 이니셔티브 마커(initiative marker), 그리고 중앙에 있는 초기화 버튼이 전부였습니다. 그게 다였죠. 분명히 첫 단계일 뿐이었고 — 진정으로 완성된 앱이라면 훨씬 더 많은 기능들이 들어갔을 겁니다.

✅ 재도약 스토리 (The Comeback Story)

이번 챌린지를 위해 이 프로젝트를 다시 시작했을 때, 계획은 작았습니다. 사용자가 앱을 약간 커스터마이징할 수 있도록 몇 가지 설정을 추가하고 UI를 정리하는 것이 목표였습니다. 하지만 더 살펴보니, 계속 생각하게 되더군요... 내가 실제로 사용하고 싶은 앱은 어떤 종류일까? 그리고 하나의 아이디어가 떠올랐습니다.

저는 그것을 명확히 보았습니다: 제가 정말 원했던 것은 플레이테스팅 앱이었습니다. 덱들을 추적하고, 다른 덱들과 비교했을 때 성능을 확인하며, 실제 게임 중에도 라이프를 계산할 수 있고 — 승패를 기록하면서 진행할 수 있는 무언가요. 그것이 계획이었습니다. 그래서 저는 이 기능을 향해 하나씩 빌드하기 시작했습니다.

제가 구축한 방식에 대한 참고 사항: 사양 기반 개발 (spec-driven development)

제가 가장 자랑스러워하는 부분 중 하나이자, 실제로 프로젝트를 완성할 수 있게 해준 부분이 바로 여기입니다.

AI 에이전트가 코드베이스 전체를 제멋대로 돌아다니게 두는 대신, 저는 OpenSpec을 활용한 **사양 기반 개발 (spec-driven development)**을 통해 모든 것을 제어했습니다. 모든 기능은 먼저 작성된 제안서 (proposal) (이유와 변경 사항)로 시작하여, 트레이드오프 (trade-offs)를 다루는 설계 (design) 문서, 그리고 작업 (tasks) 목록으로 이어졌습니다. 그러고 나서야 비로소 Claude Code가 이를 구현하도록 했습니다. 완성된 각 기능은 하나의 깔끔하고 독립적인 변경 사항이 되었습니다.

그 결과는 git 히스토리에서 확인할 수 있습니다:

아... 사양 기반 개발을 올바르게 적용한 후 이렇게 깔끔한 커밋 히스토리를 보는 것은 정말 만족스럽습니다. 6개의 기능, 6개의 커밋, 각각이 완전하고 검토 가능한 단계입니다. 충격적인 diff(차이)나 "버그 다시 수정" 같은 커밋 메시지도 없습니다... 그저 앱이 성장해가는 읽기 쉬운 이야기일 뿐입니다.

그 이야기를 기능별로 하나씩 들려드리겠습니다.

feat-001: 홈 화면과 설정

원했던 것: 플레이어를 생명력이 30으로 고정되고 빨간색 대 초록색인 하드코딩된 라이프 카운터에 바로 떨어뜨리는 것을 멈추고 싶었습니다. 그것은 개인화된 앱이 아니라 하나의 가정이었습니다.

따라서 첫 번째 실제 단계로 홈 화면 (Home screen) (게임 시작 / 설정 / 종료)과 각 진영의 **팀 색상 (team colors)**을 선택하고 라이프 모드 (life mode) (설정한 값에서 카운트다운하거나 0에서 카운트업)를 선택할 수 있는 설정 (Settings) 화면을 추가했습니다. 그리고 결정적으로, 이 모든 것은 AsyncStorage를 통해 **지속 (persisted)**되었으므로, 한 번 설정하면 앱이 이를 기억합니다.

다양한 색상을 추가하기 위해, 저는 Claude Code의 도움을 받아 기존에 가지고 있던 이미지들의 발광 색상 (glow color)을 변경하여 다시 생성해야 했습니다. 원하는 결과를 얻기까지 시간이 좀 걸렸는데, 만약 시간을 되돌릴 수 있다면 아마 Canva나 유사한 도구를 사용하여 직접 에셋 (assets)을 작업했을 것입니다.

<table><tbody><tr><td><img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fraw.githubusercontent.com%2FIcarusTheFly%2Fswu-playtesting%2Ffinish-up-a-thon-challenge%2Fdocs%2Fscreenshots%2Fjourney%2Ffeat-001-home.png" width="780" alt="첫 번째 홈 화면" height="1688"></td><td><img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fraw.githubusercontent.com%2FIcarusTheFly%2Fswu-playtesting%2Ffinish-up-a-thon-challenge%2Fdocs%2Fscreenshots%2Fjourney%2Ffeat-001-settings.png" width="780" alt="첫 번째 설정 화면" height="1688"></td></tr></tbody></table>

feat-002: 실제로 의미 있는 설정 (Settings that actually make sense)

제가 원했던 것: '증가/감소(Count Up / Count Down)' 토글은 두 가지 개념을 한 번에 설명하려고 했기 때문에 최적의 사용자 경험이 아니었습니다.

그래서 이 전체 기능을 사용자가 직접 입력하거나 (+/−) 단계적으로 조절할 수 있는 단일 초기 생명 포인트 (Initial life points) 값으로 통합했습니다. 그 과정에서 실제로 사용할 두 가지 작은 편의 기능(quality-of-life options)을 추가했습니다: 더 빠르고 움직임이 적은 느낌을 위한 애니메이션(animations) 토글과 모바일 환경에서의 +/− 누름에 대한 **햅틱 피드백(haptic feedback)**입니다.

feat-003: 앱에 기억력이 생기다 (The app gets a memory)

제가 원했던 것: 이것이 모든 것을 바꾼 기능입니다. 라이프 카운터는 게임이 끝나면 모든 것을 잊어버립니다. 하지만 덱을 _테스트_하는 플레이어들(제가 이 앱을 만들고자 했던 사람들)은 스프레드시트에서 승률과 매치업 기록을 관리합니다. 저는 그 모든 것을 앱 안으로 옮기고 싶었습니다.

그래서 저는 이름이 지정된 덱 (decks) (속성, 리더, 아키타입, 노트)의 공유 풀, 영구 저장되는 게임 로그 (game log), 그리고 그로부터 파생된 통계 (stats) (전적, 승률, 연승)를 추가했습니다. 각 덱에는 상대 전적 (head-to-head matchups) (이벤트별 그룹화 및 전략 노트 포함), 전체 게임 기록 (game history), 그리고 한 시즌의 테스트 데이터를 한꺼번에 채워 넣을 수 있는 일괄 추가 (Bulk Add) 흐름이 포함된 상세 화면이 제공됩니다. 통계는 **대칭적 (symmetric)**입니다. 즉, "A가 B를 이겼다"를 기록하면 두 덱 모두가 자동으로 업데이트됩니다.

  

feat-004: 완성된 것처럼 보이게 만들기 (UI 현대화)

원했던 것: 이 시점에서 앱은 많은 기능을 수행하고 있었지만, 여전히 미완성된 것처럼 보였습니다. 우주 배경은 게임 중에만 나타났고, 대화창 버튼은 테마와 충돌하는 채도 높은 파란색/빨간색이었습니다. 초기화 컨트롤은 "새로고침" 화살표처럼 보였습니다.

그래서 이번 작업은 순수하게 시각적인 개선 작업이었습니다. 모든 화면 뒤에 **애니메이션 별자리 (animated starfield)**를 배치하고(모션을 껐을 때는 정지된 배경 사용), 충돌하는 색상 대신 **금속 질감의 대화창 버튼 (metallic dialog buttons)**을 적용했습니다. 초기화 화살표는 제대로 된 **햄버거 메뉴 (hamburger menu)**가 되었고, 흐릿했던 우선권 비트맵은 가로 모드에서도 마침내 제대로 보이는 선명한 **벡터 토큰 (vector token)**으로 바뀌었습니다.

feat-005: "라이프 카운터"에서 "SWU 플레이테스팅"으로

feat-005: "라이프 카운터"에서 "SWU 플레이테스팅"으로

내가 원했던 것: 앱은 조용히 덱 테스트 도구(deck-testing tool)로 변해 있었지만, 여전히 스스로를 라이프 카운터(life counter)라고 "소개"하고 있었습니다. 이제 이 앱의 실제 정체성에 전념할 때였습니다.

그래서 앱 이름을 SWU Playtesting으로 변경하고, 표준 하단 탭 바 (bottom tab bar) (홈, 덱, 설정)를 추가했으며, 홈 (Home) 화면을 대시보드로 전환했습니다. 즉, 가장 성적이 좋은 덱, 한 번의 탭으로 테스트 (Test) 할 수 있는 덱 순위 목록, 그리고 빠른 플레이 테스트 게임 (Play Test Game) 버튼을 배치했습니다. 새로운 아이콘, 더 차분하고 밀도 있는 별밭(starfield), 그리고 실제 브랜딩을 적용했습니다.

아이콘을 생성하기 위해 Claude Design 및 Google Stitch와 한동안 의견을 주고받았지만, 결국 Claude Design을 사용했습니다. AI 활용 경험에 대한 자세한 내용은 나중에 더 자세히 다루겠습니다.

feat-006: 실제 디자인 시스템 (최종 리디자인)

내가 원했던 것: 글쎄요, 결국 스타일이 여전히 제 취향에는 완벽히 맞지 않았습니다... 약간 평면적(flat)이라는 느낌을 받았습니다. 저는 모든 화면이 _완성된 제품_처럼 느껴지기를 원했습니다.

그래서 실제 **디자인 시스템 (design system)**을 구축했습니다. 공유된 메탈릭 실버 + 골드 (metallic-silver + gold) 토큰과 재사용 가능한 컴포넌트 키트(component kit)를 만들고, 이를 중심으로 앱의 스타일을 다시 입혔습니다. 메탈릭 헤더가 있는 리디자인된 홈 화면, 숫자 전용 기록과 최근 폼을 보여주는 스파크라인(sparklines)이 포함된 덱 카드, 그리고 골드 색상의 플레이 테스트 게임 (Play Test Game) 버튼부터 시작했습니다. 모든 곳에 동일한 토큰을 사용했기 때문에, 다음 화면들도 구조적으로 일관성을 유지하게 됩니다. 이것이 아래 데모에서 볼 수 있는 버전입니다.

🎬 데모

간단한 워크스루(walkthrough): 홈, 덱과 그 통계, 설정, 그리고 테스트 게임을 시작하여 라이프를 카운트하는 과정입니다.

비디오