google-cloud-study-jam-hackathon

Imported from currenjin/google-cloud-study-jam-hackathon (AGENTS.md). Install upstream with npx skills add currenjin/google-cloud-study-jam-hackathon. Copyright stays with the author.

릴드 (Reels Drama) — Agent Context

이 프로젝트는 Google Cloud Study Jam Hackathon(2026-07-16) 출품작이다. 개발 시간이 총 120분이므로 모든 판단은 "에러 없이 도는 데모"를 최우선으로 한다. 이 파일과 docs/03-prompts.md에 이미 내려진 결정을 재논의하지 말고 그대로 구현한다. 사용자에게 질문하기 전에 이 문서에서 답을 찾는다.

전체 위임 모드

사용자가 "전체 위임 프롬프트"(docs/04-kickoff-prompts.md 최상단)를 주면 M1 → M2 → M3 → M3+를 승인 대기 없이 연속 실행한다. 규칙:

• 마일스톤마다: 동작 확인 → npm run build 통과 → 커밋 → 즉시 push
• 질문으로 멈추지 않는다. 모든 결정 기준은 이 문서에 있다. 문서에 없는 사소한 결정은 "데모가 안 죽는 쪽"을 고른다
• 막히면 해당 기능을 축소/폴백하고 진행한다. 전체를 멈추는 것은 금지
• 완료 후 보고: 구현된 것 / 축소·생략한 것 / 사람이 할 일(M4: 데모 녹화, 영상 업로드, repo public 전환, 제출)

기존 스캐폴드 처리

리포에 기본 Vite 템플릿(package.json name: tmp_vite, 카운터 App.jsx)이 이미 있을 수 있다. 다시 스캐폴드하지 말고 재사용한다: 의존성(@google/genai, react, vite)과 node_modules는 이미 설치되어 있고 public/demo-assets/도 복사되어 있다. package.json name을 reels-drama로 바꾸고, 기본 데모 UI(App.jsx의 카운터/로고)를 전부 우리 화면으로 교체한다. src/__pycache__ 같은 무관한 잔재물은 삭제한다. Node 버전은 .nvmrc(22)를 따른다 — 터미널에서 vite가 엔진 에러를 내면 nvm use부터 실행한다.

무엇을 만드는가

텍스트 프롬프트를 시드로 받아, 여러 사람이 릴레이로 한 줄씩 전개를 이어가면 AI가 숏폼 드라마를 만들어주는 참여형 웹앱. 이미지 시드는 MVP 범위 밖이다.

화면 3장 (이 이상 만들지 않는다):

1. 시드 입력 — 텍스트로 드라마 시작 → Gemini가 Story Bible(JSON) 생성
2. 턴 화면 — 현재 씬(컷 이미지 + 대사/내레이션) + "다음 전개 한 줄" 입력 + "다음 사람에게 넘기기" 버튼 (핫시트 방식: 같은 브라우저에서 기기를 넘겨받는 상호작용)
3. 완성 릴 재생 — 9:16 세로 프레임, 컷 자동 넘김(컷당 3~4초), 대사/내레이션 자막 오버레이

기술 스택 (고정 — 변경하지 않는다)

• Vite + React (JavaScript). TypeScript, 라우터, 상태관리 라이브러리, Tailwind 쓰지 않는다. 화면 전환은 단일 state로, 스타일은 src/App.css 하나로.
• @google/genai SDK, 브라우저에서 직접 호출. API 키는 .env의 VITE_GEMINI_API_KEY. 이 방식은 키가 브라우저에 노출되므로 localhost의 임시 해커톤 데모에서만 허용한다. 외부 배포 금지, .env 커밋 금지, 행사 종료 직후 키 폐기. 프로덕션은 백엔드 프록시를 사용한다.
• 모델 (현장에서 AI Studio 목록 기준으로 최종 확인, 없으면 괄호 안 대체):
  • 각본/바이블: gemini-3-flash-preview (대체: gemini-2.5-flash)
  • 이미지: gemini-2.5-flash-image, aspect ratio 9:16. 현장 AI Studio에서 사용 가능 여부를 먼저 확인하며, 다른 모델 ID를 추측해 자동 대체하지 않는다.
• 상태는 React state + localStorage 백업. localStorage에는 바이블·요약·대사·프롬프트만 저장하고 base64/blob 이미지와 API 키는 저장하지 않는다. 읽기/쓰기는 try/catch로 감싸고 스키마 버전을 둔다. DB 없음, 서버 없음.
• 배포는 하지 않아도 된다. npm run dev 로컬 데모로 충분.

핵심 설계 원칙

• Story Bible이 일관성의 전부다. 첫 시드에서 JSON 바이블(인물, marker, 톤, visual_style, setting)을 생성하고, 이후 모든 생성 호출에 컨텍스트로 주입한다. 스키마와 프롬프트 3종은 docs/03-prompts.md에 있다 — 그대로 사용하고 임의로 재작성하지 않는다.
• 비주얼 스타일 고정: "wooden artist mannequin figures on a miniature diorama stage set, soft studio lighting, shallow depth of field, cinematic color grading, 9:16 vertical". 모든 이미지 프롬프트는 이 문구로 시작한다.
• 캐릭터는 이름이 아니라 marker(소품/색)로 이미지 프롬프트에 묘사한다. (인형은 얼굴로 구분 불가)
• Gemini 텍스트 호출은 responseMimeType: application/json과 SDK 버전에 맞는 구조화 출력 스키마를 함께 지정한다. JSON 파싱 후 필수 필드·배열·character_id를 검증하고, 파싱 또는 검증 실패 시 1회 재시도한다.

스코프 규칙 (절대 준수)

하지 않는다: 로그인/계정, 실시간 멀티유저 동기화, DB, 모바일 대응, 공유/투표 기능, 이미지 시드, Veo 영상 생성(스킵 — 새 기능보다 퀄리티), 대규모 테스트 코드, 접근성/국제화.

기능 추가보다 퀄리티. M3 이후 남는 시간은 새 기능이 아니라 완성도에 쓴다. 우선순위: ① 데모 경로가 어떤 입력에도 안 죽는 것 ② 릴 재생의 연출(씬 전환 페이드, 자막 타이밍, 엔딩 카드) ③ 타이포·간격·색 등 시각 완성도 ④ 로딩/에러 마이크로카피의 콘셉트 일관성("촬영 중...", "대본 쓰는 중..."). 심사 기준 1번이 "에러 없이 완성도 높게 동작하는가"다.

목업 자산 (demo-assets/)

demo-assets/mock-scenes.json은 정규화된 클라이언트 씬 형태의 목업 데이터(바이블 + 씬 4개), SVG 파일들은 목업 컷 이미지다. 목업 컷은 image_prompt와 /demo-assets/... 형식의 image_url을 함께 가지며, 실제 API 컷은 생성 전 image_url: null로 정규화한다. API 연동 전에 이 데이터로 시드 → 씬 UI를 완성하고(릴 재생 UI는 M3에서), 그 다음 실제 Gemini 호출로 교체한다. text-card-fallback.svg는 이미지 실패 시 텍스트 카드의 디자인 레퍼런스.

스캐폴드 시 demo-assets/를 public/demo-assets/로 복사한다 — Vite dev 서버는 프로젝트 루트를 서빙해서 /demo-assets/...가 우연히 동작하지만, build 산출물에는 public/만 복사되므로 public 경유가 안전하다.

장애 대응

• 이미지 생성 실패 → 1회 재시도 → 실패 시 해당 컷을 텍스트 카드(어두운 배경 + 내레이션 타이포, demo-assets/text-card-fallback.svg 스타일)로 렌더한다. 절대 빈 화면/에러를 노출하지 않는다.
• 모든 요청에 타임아웃을 둔다. 릴레이 도중 씬 생성이 재시도 후에도 실패하면 목업으로 바꿔치기하지 않는다 — 사용자가 입력한 전개와 무관한 씬이 나오는 것은 에러보다 나쁘다. 대신 콘셉트 에러 카드("전파가 약합니다... 다시 시도해 주세요")와 재시도 버튼을 보여주고 입력을 보존한다.
• DEMO_MODE는 드라마 시작 전에만 진입할 수 있다. VITE_DEMO_MODE=true이거나, 시작 화면에서 API 키 누락/바이블 생성 실패가 확인될 때 "데모 모드로 체험" 진입을 제안한다. 활성화 중에는 화면에 항상 "DEMO" 배지를 표시한다. 제출용 데모 영상과 심사 시연에는 DEMO_MODE 화면을 사용하지 않는다.
• 모든 생성 호출에 로딩 상태 표시 ("촬영 중..." 같은 콘셉트 문구).

마일스톤 (킥오프 프롬프트는 docs/04-kickoff-prompts.md)

• M1 (0–30분): 프로젝트 스캐폴드 + 목업 기반 시드·씬 화면 + 시드 → 바이블 → 씬 1개 → 이미지 1장 실제 호출 (릴 재생 UI는 M3)
• M2 (30–65분): 턴 릴레이 UI, story_summary 갱신, 씬 히스토리 누적
• M3 (65–90분): 완성 릴 재생 화면(자동 넘김 + 자막), DEMO_MODE·텍스트 카드 폴백, 스타일 폴리시
• M4 (90–120분): 사람 작업 — 데모 촬영, README, 제출. 에이전트는 요청받은 버그 수정만 한다

각 마일스톤 완료 시 동작 확인 가능한 상태여야 하며, 즉시 커밋한다. 매 커밋 전 npm run build를 통과시키고, M3에서는 VITE_DEMO_MODE=true 전체 흐름과 강제 이미지 실패 폴백도 확인한다.