저는 최근 명세 기반 개발 (Spec-Driven Development, SDD)에 깊이 빠져 있습니다. 이것이 실제로 무엇인지 살펴보고, Kiro의 첫 번째 생일을 위해 game을 만드는 데 어떻게 사용했는지 보여드리고자 합니다.

만약 명세 기반 개발, 즉 SDD를 접해보지 못했더라도 걱정하지 마세요. 제가 도와드리겠습니다. 이것이 무엇인지, 어디에 도움이 되는지, 어디에서 과한지(overkill), 그리고 제가 이 게임을 만드는 데 어떻게 사용했는지 다룰 것입니다!

대신 영상을 보고 싶으신가요? 확인해 보세요!

명세 기반 개발(Spec-Driven Development)이란 무엇인가?

SDD는 세 단계로 나뉘며, 이 모든 과정은 코드가 작성되기 전에 일어납니다.

SDD phases

먼저 요구사항 문서(requirements document)를 작성합니다. 그런 다음 AI 에디터가 이를 설계 문서(design document)로 변환하게 합니다. 그다음, 요구사항과 설계를 바탕으로 작업 목록(tasks)을 생성합니다.

가장 중요한 부분은 모든 단계의 중간에 인간이 있다는 점입니다. 당신은 요구사항을 확인합니다. 설계를 확인합니다. 생성된 작업들을 검토하고 수정합니다. 당신이 계획을 승인하기 전까지는 아무것도 구축되지 않습니다.

하지만 이것이 확정된 규칙은 아닙니다. 때로는 요구사항과 설계가 하나의 문서로 결합되기도 합니다. 어떤 때는 세 가지가 동시에 일어나는 빠른 모드(quick mode)로 실행하기도 합니다. 이는 당신이 무엇을 하려고 하는지에 따라 달라집니다. 저는 큰 기능을 작업할 때는 세 가지 문서를 모두 만들고, 데모와 같이 빠르게 무언가를 하려고 할 때는 일종의 빠른 모드나 계획 모드를 사용하기도 합니다.

트레이드오프 (The trade-offs)

다른 모든 것과 마찬가지로, SDD에도 트레이드오프 (trade-offs)가 따릅니다.

SDD Tradeoffs

제가 가장 좋아하는 점은 높은 초도 성공률 (first-pass success rate)입니다. 만약 실제로 요구사항 문서 (requirements doc)와 실제 설계 (design)를 작성하며 초기에 작업을 제대로 수행한다면, 최종 결과물이 당신이 원했던 모습일 가능성이 훨씬 높아집니다.

검토 (review) 또한 더 쉬워집니다. 크고 복잡한 기능을 더 작은 단계로 나누기 때문에, 대신 각 단계를 확인할 수 있고 여러 개의 작은 PR (Pull Request)을 올릴 수 있습니다. 그리고 잘못된 방향으로 가는 것을 방지하는 데에도 도움이 됩니다. 에이전트 (agent)가 여러 방향으로 멋대로 달려가게 내버려 두었다가 너무 늦게 깨닫는 대신, 한두 단계마다 코드를 확인하게 됩니다.

단점은 초반의 계획 시간입니다. SDD (Spec-Driven Development)는 코드를 보기 전까지 더 많은 시간이 소요되므로, 모든 작업에 적합한 것은 아닙니다. 일회성 코드 (throwaway code)나 작은 이슈의 경우에는 필요하지 않습니다. 반면에 더 많은 생각이 필요한 기능에는 정말 효과적입니다. 시작할 때 약간의 시간을 포기하는 대신, 그 대가로 마지막에는 더 안정적이고 더 잘 작동하는 앱을 얻게 됩니다.

프로젝트: Kiro 생일 게임

제가 무엇을 만들었는지 보여드리겠습니다.

Game image

이것은 여러 건물을 돌아다니며 탐험하는 로그라이크 게임 (rogue-like game)입니다. 각 건물은 Kiro의 서로 다른 시점을 나타내는데, 이것이 우리의 Kiro 생일 축하 파티의 일부이기 때문입니다. Kiro가 돌을 맞이합니다. 그래서 한 건물은 Kiro가 일반적으로 공개 (generally available)되었을 때를 다루고, 다른 건물은 re:Invent에서 우리가 머물렀던 집을 다루는 식입니다. 모든 집을 방문하면 보너스 집/구역을 잠금 해제할 수 있습니다. Kiro의 역사를 들려주는 재미있는 방법이라고 생각했습니다.

내부적으로는 Phaser와 TanStack Start를 사용했습니다. Phaser는 2D 파이널 판타지 (Final Fantasy) 스타일의 비주얼을 구현하는 게임 라이브러리 (gaming library)이며, TanStack Start는 이 모든 것을 감싸는 웹 라이브러리 (web library)입니다. 음악도 포함되어 있는데, 이에 대해서는 나중에 말씀드리겠습니다.

SDD를 사용하여 이를 구축한 방법

저는 Kiro를 열고 spec mode(명세 모드)를 사용하라고 명령했습니다. 이는 IDE에서 직접 수행할 수 있으며, CLI v3부터는 CLI에서도 spec mode를 사용할 수 있습니다. 어떤 방식이든, 이 모드는 요구사항(requirements), 설계(design), 작업(tasks)이라는 세 가지 문서를 생성합니다.

저는 게임을 설명하는 프롬프트를 입력했습니다. 예를 들어, "파이널 판타지(Final Fantasy) 스타일의 2D 비디오 게임을 만들고 있으며, 여기 다양한 클래스와 이름들이 있고, 우리가 가질 다양한 건물들은 다음과 같다"와 같은 식입니다. 이를 바탕으로 Kiro는 EARS 형식의 요구사항을 생성했는데, 이는 사용자 스토리(user story)에 수락 기준(acceptance criteria)이 결합된 전형적인 구조입니다. 앞서 언급했듯이, 저는 생성된 문서가 정확한지 확인하기 위해 모든 단계에서 이중으로 점검했습니다.

요구사항을 바탕으로 설계(design)를 구축했습니다. 모든 것을 하나의 문서로 유지하고 싶다면 이 단계를 건너뛸 수도 있지만, 저는 별도로 분리하는 것을 선호합니다. 설계 단계에서는 기술적인 세부 사항들이 다뤄졌습니다. 프론트엔드를 위한 TypeScript 라이브러리로 Phaser를 사용하고, 곳곳에 useEffect가 사용된 TanStack Start를 활용하며, 상위 수준의 구조, 장면(scenes), 경계(boundaries), 게임 쉘(game shell) 등을 정의했습니다.

그 다음에는 모든 개별 작업이 세분화된 작업 목록(task list)이 나왔습니다. 저는 먼저 MVP(Minimum Viable Product, 최소 기능 제품)를 구축하라고 명령했기 때문에, Kiro는 전체 목록을 가져와 가장 중요한 4가지 작업을 앞쪽으로 배치했습니다. 저는 작업 순서가 타당한지 확인한 후, 처음 4가지 작업을 먼저 구현하도록 했고, 결과물을 살펴본 뒤 다음 단계로 넘어가기 전에 제대로 작동하는지 확인했습니다.

과정을 더 쉽게 만들어준 도구들

여기서 큰 도움이 된 몇 가지가 있습니다.

저는 몇 가지 MCP(Model Context Protocol) 서버를 사용했습니다. 에이전트가 API를 추측하지 않도록 Phaser 문서를 가져오기 위한 Context7을 사용했습니다. 그리고 Kiro가 앱을 열어 확인하고 요구사항과 일치하는지 검토할 수 있도록 Chrome 브라우저 MCP 확장 프로그램을 사용했습니다.

또한 자동 모드 (auto mode)를 실행했습니다. 여러 모델을 번갈아 사용했는데, Claude 4.8은 훌륭하지만 크레딧을 상당히 많이 소모합니다. 자동 모드는 특히 명세 기반 개발 (SDD)과 결합했을 때 정말 뛰어난 성능을 보여주었습니다. 이는 이 접근 방식에서 과소평가된 부분 중 하나입니다. 모든 것이 이미 명세 (spec)에 작성되어 있기 때문에, 원하는 것을 얻기 위해 반드시 최고 수준의 최첨단 (state-of-the-art) 모델을 사용할 필요는 없습니다. 이 과정의 대부분에서 자동 모드만으로도 충분했습니다.

그 외에도 몇 가지 스킬 (skills)을 사용했습니다. AWS Agent Toolkit과 더불어 Amplify 및 serverless 스킬을 사용했습니다. /aws-amplify를 실행하여 게임을 Amplify 호스팅에 배포하는 데 도움을 받았습니다. 음악을 위해서는 ElevenLabs를 사용했습니다. 저는 여러 서비스와 연결된 scripts 폴더를 구성해 두었는데, 아트(art)를 위한 PixelLab, 오디오를 위한 ElevenLabs, 심지어 Hugging Face까지 포함되었습니다. 이 모든 것이 키 (keys)를 담은 .env 파일을 사용하여 Kiro 내부에서 구동되었으며, 에셋 (assets) 또한 자동으로 생성해 주었습니다.

마무리하며

이것이 저의 명세 기반 개발 (spec-driven development) 워크플로우의 기본 버전입니다. 초기에 더 많은 계획이 필요하지만, 실제 기능을 구현할 때는 그만한 가치가 있습니다.

게임을 직접 플레이해보고 싶다면 여기에서 확인하세요!

여러분은 일상 업무에서 명세 기반 개발 (spec-driven development)을 사용하시나요? 여러분의 경험은 어떠했는지 궁금합니다. 그럼 안녕히 계세요, 읽어주셔서 감사합니다.