우리는 Salty Poker를 이렇게 만들고 있다: spec-driven development

대부분의 포커 플랫폼은 대부분의 포커 핸드가 플레이되는 방식으로 만들어진다 — 빠르게, 감으로, 가면서 답을 찾아가며. 우리는 그렇게 하지 않는다.

첫날부터 우리는 이 플랫폼을 spec-driven development 방식으로 만들겠다고 의식적으로 결정했다. 이는 AI 지원 엔지니어링 분야에서 진지한 기세를 얻고 있는 방법론이며, 우리가 만들고 있는 모든 것이 그 위에 놓여 있는 토대다.

Spec-driven development이란 무엇인가

단 한 줄의 프로덕션 코드가 쓰이기 전에 스펙이 먼저 쓰였다. 100페이지가 넘는다. 시스템의 모든 영역을 다루는 23개의 모듈 — 인프라, 데이터베이스 스키마, API 계약, 서비스 경계, 컴플라이언스 컨트롤, CI/CD 파이프라인, 운영 runbook.

이 방법론은 세 단계로 나뉜다. Spec-first: 어떤 코드보다도 먼저 철저한 스펙을 작성한 다음, 이를 기반으로 개발을 이끈다. Spec-anchored: 프로젝트가 성숙해 감에 따라 스펙이 코드베이스와 나란히 살아 있고 진화한다. Spec-as-source: 사람이 만지는 것은 스펙뿐이고 — 코드는 전적으로 스펙으로부터 생성된다.

언급할 만한 실패 패턴도 있다: spec-once — 스펙이 프로젝트를 시작시키고 나서 빌드가 깊어지면서 조용히 버려지는 경우. 설계도가 유물이 된다.

우리는 이를 명시적으로 방지하도록 설계됐다. 우리 스펙은 살아 있는 문서다. 결정이 내려지고, 엣지 케이스가 드러나고, 아키텍처가 진화할 때마다 업데이트된다. 세션이 끝날 때 스펙은 지금까지 만들어진 것을 반영한다. 다음 세션이 시작될 때 스펙은 지난 세션이 끝난 지점에서 정확히 이어받는다.

포커 플랫폼에 왜 이것이 중요한가

포커 플랫폼은 예측 가능한 방식으로 망가진다 — 그리고 거의 모든 경우 같은 근본 원인으로 귀결된다: 초기 단계에서 취한 지름길이 쌓여 나중에 심각한 문제로 번진다.

제대로 된 복식 원장 없이 만든 월렛 시스템. 엣지 케이스에 대해 스트레스 테스트되지 않은 게임 엔진. 첫날부터 녹여 넣지 않고 나중에 덧붙인 컴플라이언스 레이어. 플레이어 50명에서는 잘 돌아가지만 500명에서 무너지는 플랫폼.

Spec-driven development는 그것을 막는 규율이다. 모든 서비스 경계가 만들어지기 전에 정의된다. 모든 데이터 플로우가 구현되기 전에 문서화된다. 모든 컴플라이언스 요구사항이 단 하나의 마이그레이션이 실행되기 전에 스펙에 들어가 있다. "나중에 해결하지"라는 결정은 없다 — "나중에"는 플레이어들이 이미 테이블에 앉아 있는 시점이기 때문이다.

실행 엔진으로서의 Agentic AI

우리는 이 플랫폼을 만들기 위해 agentic AI를 사용하고 있다 — 그리고 이것은 대부분의 사람들에게 익숙한 AI 도구들과는 중요한 차이가 있다.

Agentic AI는 단순히 질문에 답하거나 코드를 자동완성하지 않는다. 정의된 경계 안에서 자율적으로 여러 단계의 워크플로를 수행한다 — 코드를 작성하고, 테스트를 돌리고, 실패를 포착하고, 고치고, 커밋한다 — 사람이 매 동작을 감독할 필요 없이. 하나의 작업을 처음부터 끝까지 처리하고, 사람의 결정이 필요한 지점에 도달했을 때 제어권을 돌려준다.

스펙은 그것을 안전하고 예측 가능하게 만든다. 에이전트는 정의되고 리뷰되고 버전 관리되는 스펙 위에서 동작한다. 각 세션은 한 번에 2~4개의 집중된 모듈 하위 집합을 로드하여, 에이전트에게 필요한 맥락만 정확히 주고 그 외에는 주지 않는다. 각 세션에는 정의된 범위가 있다. 체크포인트가 다음 단계로 가는 관문 역할을 한다. 체크리스트가 깨끗해지기 전까지는 아무것도 나아가지 않는다.

에이전트는 무엇을 만들지 결정하지 않는다. 스펙이 결정한다. 에이전트는 실행한다.

결과

그것이 마땅히 받아야 할 엄밀함으로 만들어진 플랫폼. 문서화된 모든 아키텍처 결정. 의도적인 모든 서비스 경계. 문제가 되기 전에 해결된 모든 컴플라이언스 요구사항.

그것이 우리가 만들고 있는 것이다. 그리고 여러분이 그 위에서 플레이할 때 차이를 느낄 것이다.

나는 spec-driven development에 대해 방법론으로서 — 결정들, 툴링, 세션 구조, 그리고 포커를 넘어선 의미에 대해 — The Salty Korean에서 글을 쓴다. 이 엔지니어링 측면에 관심이 있다면 더 깊은 이야기는 거기에 있다.

방법론에 대한 더 자세한 내용: Heeki Park의 Using Spec-Driven Development with Claude Code.

Stay salty.