주말 만에 카드 게임을 출시했지만, '감'으로 코딩하지는 않았습니다

이것은 Vibe Coding Weekend Challenge에 제출하는 저의 글입니다. 솔직히 말하자면, 제가 한 것은 전형적인 '감' 코딩(vibe coding)은 아니었습니다.

앱 소개 (두 문장으로)

이것은 체코의 카드 게임인 Mau-Mau 계열의 Prší를 브라우저 버전으로 구현한 것입니다. 딜부터 누군가 패를 비울 때까지, 의도적으로 바보 같은 AI와 1대1로 한 판을 플레이할 수 있으며, 마우스나 터치로 조작합니다.

• 🎮 플레이: https://czsoftcode.github.io/prsi/
• 📦 소스 코드: [https://github.com/czsoftcode/prsi]

스택은 TypeScript + Vite이며, 프레임워크 없이 순수 DOM 렌더링을 사용했습니다. 게임 엔진(규칙, 이동 유효성 검사, 승리 감지)은 DOM 의존성이 없는 순수 함수로 구성되어 있어 자체적으로 완전히 테스트가 가능하며, 그 결과 약 300개의 단위/통합 테스트를 확보할 수 있었습니다.

사용 도구: Claude Code, 하지만 통제된 방식으로

챌린지는 Lovable, Cursor 또는 Bolt를 제안했습니다. 저는 대신 Claude Code를 사용했는데, 이는 일반적으로 '감' 코딩이 의미하는 '앱을 설명하고 나오는 대로 받아들이는 방식'과는 달랐습니다.

대신 저는 작은 단계 오케스트레이터(phase orchestrator)를 통해 Claude Code를 이끌었습니다. 전체 빌드는 약 10개의 명시적인 단계로 분할되었으며, 각 단계에는 작성된 목표와 검증 가능한 결과가 있었습니다:

1. Vite + TypeScript 스캐폴드
2. 엔진: 데이터 모델 (32장 카드 덱, 딜링)
3. 엔진: 기본 이동 (무늬/랭크 일치, 뽑기)
4. 엔진: 특수 카드 및 승리 조건
5. AI 상대방 휴리스틱(heuristic)
6. UI: 테이블 렌더링
7. UI: 상호 작용 루프 + 무늬 선택기
8. 게임 종료, 새 매치 시작, 교착 상태 처리
9. 종단 간 시뮬레이션 (AI 대 AI 게임 200회)
10. README 작성 및 배포

각 단계는 다음 단계가 시작되기 전에 계획, 구현 및 검토를 거쳤습니다. 따라서 "감(vibe)"에 의존하기보다는, **AI가 타이핑을 수행하는 명세 기반 개발 (spec-driven development)**에 더 가까웠습니다. 이 방식의 장점은 AI가 미묘하게 잘못된 부분을 작성했을 때, 제가 신뢰해야만 하는 2,000줄짜리 코드 덩어리 대신 테스트와 엄격한 범위 (scope)를 통해 이를 잡아낼 수 있었다는 점입니다.

실제로 무엇이 잘못되었나

챌린지에서는 실제 반복 횟수와 문제가 발생한 사항들을 요구합니다. 솔직히 말해서, 코드가 아니라 _규칙 (rules)_이 가장 어려운 부분이었습니다.

• 7번 카드. 7은 상대방이 2장을 뽑게 만들며, 7은 **중첩 (stack)**됩니다. 최대 4장까지 중첩될 수 있으므로, 마지막 플레이어는 8장을 뽑아야 할 수도 있습니다. "7에 대해서는 오직 다른 7로만 대응할 수 있다"는 규칙을 올바르게 구현하는 데 몇 번의 시도가 필요했는데, 이는 어떤 카드가 플레이 가능한 것으로 간주되는지와 상호작용하기 때문입니다.
• 퀸 (Queen)은 와일드카드입니다. 퀸은 어떤 카드에도 낼 수 있으며 요구되는 문양 (suit)을 변경합니다. 첫 번째 엔진 버전에서는 이를 일반적인 문양/숫자 일치 규칙으로 잘못 제한했습니다. 테스트를 통해 발견하여 수정했습니다.
• 배포 문제. 모든 것이 localhost에서는 잘 작동했지만, GitHub Pages에서는 작동하지 않았습니다. 카드들이 절대 경로인 /cards/... 아래에 존재하는데, 사이트는 /prsi/ (프로젝트 하위 경로)에서 서빙되기 때문에 모든 카드가 404 오류를 일으켰습니다. 해결 방법: 경로를 하드코딩하는 대신 Vite의 import.meta.env.BASE_URL을 통해 경로를 빌드하도록 수정했습니다.
• 어처구니없는 버전 관리 실수. v1.0.2 태그를 달았지만 실제로 package.json을 올리는 것을 잊어버려, 태그의 트리에는 여전히 1.0.1로 표시되었습니다. 사소한 문제지만, 딱 확인해 볼 때만 눈에 띄는 그런 종류의 실수입니다.

AI 측면은 의도적으로 단순하게 유지했습니다. 상대방은 오직 유효한 수 (legal moves)만 두며, 기본적인 휴리스틱 (heuristic)을 사용하여 수를 선택합니다. 똑똑한 AI를 만드는 것이 목적이 아니라, 정확한 AI를 만드는 것이 목적이었기에 그 200회의 시뮬레이션 게임이 중요했습니다 (모든 게임은 불변량 (invariant)을 깨뜨리지 않고 승리 또는 교착 상태로 끝나야 합니다).

그럴 만한 가치가 있었나?

네. 주말이라는 제약은 범위를 축소하도록 강제합니다. 계정, 멀티플레이어, 라운드 간 점수 기록 등은 제외하고, 오직 하나의 완성도 높은 게임에만 집중하게 됩니다. 또한 단순히 느낌(vibe)에 의존하는 대신 단계별(phase-by-phase)로 진행했기에, 출시된 결과물은 제가 실제로 논리적으로 추론하고 확장할 수 있는 형태가 되었습니다.

"멍청한" AI가 체코 카드 게임에서 패배하는 모습을 보고 싶다면, 바로 여기서 확인하실 수 있습니다: https://czsoftcode.github.io/prsi/