AI 에이전트로 구축한 Roku/Fire TV용 퀴즈 플랫폼 'SplitCast' 개발기

실용적 조언

프로젝트 루트에 API_CONTRACT.md를 작성하여 에이전트가 공유 규약을 깨지 않도록 강제하라.
AGENTS.md를 통해 각 에이전트의 역할과 작업 범위를 명시하라.

섹션별 상세

SplitCast는 Roku와 Fire TV를 위한 퀴즈 플랫폼이다. Vercel, Railway, Supabase를 기반으로 QR 코드를 통해 모바일로 참여하는 구조를 갖췄다. 4개월간의 개발 끝에 두 곳의 바에서 유료 서비스를 시작했다. 하드웨어 제약이 있는 환경에서도 현대적인 웹 스택으로 상용 서비스 구축이 가능함을 나타낸다.

Claude와 Codex를 활용한 개발 중 플랫폼 간 코드 충돌이 발생했다. Codex가 Fire TV를 최적화하며 Roku 클라이언트의 API 계약을 파괴했다. 에이전트가 전체 시스템 의존성을 무시하고 특정 클라이언트 코드만 수정한 결과이다. 에이전트 기반 개발에서 시스템 전체 맥락 유지의 어려움을 드러낸다.

에이전트의 오작동을 막기 위해 명시적인 가드레일 파일을 도입했다. AGENTS.md와 API_CONTRACT.md를 작성하여 에이전트가 수정 시 반드시 참조하게 했다. 이 파일을 통해 에이전트가 공유 규약을 준수하며 코드를 작성하도록 강제했다. 프롬프트 외부의 구조화된 지침이 에이전트의 안정성을 높이는 핵심 도구임을 확인했다.

AI 생성 퀴즈 콘텐츠는 서비스의 지속 가능성을 확보하는 핵심 요소이다. 매 세션마다 새로운 질문을 생성하여 콘텐츠 반복 문제를 해결했다. 실제 바(Bar) 고객들이 '마라톤 모드'와 같은 추가 기능을 요청할 정도로 콘텐츠 품질이 유지됐다. AI가 생성한 동적 콘텐츠가 실제 비즈니스 가치를 창출할 수 있음을 입증했다.

용어 해설

API 계약(API Contract): — 소프트웨어 컴포넌트 간의 상호작용 방식을 정의하는 명세이다. 에이전트가 한쪽 코드를 수정할 때 다른 쪽과의 호환성을 유지하게 돕는 기준이 된다. 멀티 플랫폼 개발에서 코드 간섭을 방지하는 핵심적인 가드레일 역할을 수행한다.
에이전트 조정(Agent Coordination): — 여러 AI 에이전트나 작업 단위가 서로 충돌하지 않고 협력하도록 관리하는 기법이다. 대규모 프로젝트에서 코드 일관성을 유지하는 데 필수적이다. 에이전트가 전체 시스템의 의존성을 파악하지 못해 발생하는 오류를 예방하는 데 중요하다.
가드레일 파일(Guardrail File): — AI 모델의 행동을 제한하거나 특정 규칙을 따르도록 강제하는 지침 파일이다. 프롬프트 외부에서 지속적인 제약 조건을 제공하여 오류를 방지한다. 프로젝트 구조 내에 영구적인 지침을 심어주어 에이전트의 작업 일관성을 보장하는 효과가 있다.

언급된 도구

Claude추천

코드 생성 및 개발 보조

Codex중립

코드 최적화 및 생성

Supabase추천

백엔드 데이터베이스 및 인프라