4.5 KiB
4.5 KiB
TASK — Find-Word v0.1
역할
당신은 구현 담당 Codex다. 이 저장소에서만 작업하고 프로덕션 서버·DNS·인증정보에는 접근하지 않는다. Neo가 코드 리뷰·배포를 별도로 수행한다.
제품
- 서비스명: 단어를 맞춰라
- 표기: Designed by OZ at Heat-T Medical Inc.
- 버전: 0.1
- 배포 예정 도메인:
findword.heart-m.com - 언어: 사용자 UI와 상세 소스 주석은 한국어
목표
여러 환경 소음 속에 작은 음량으로 섞인 특정 한국어 단어나 문장을 듣고 질문에 답하는 웹 게임을 만든다. 쉬운 단계부터 소음 대비 키 문장의 dB 차이를 늘려 난이도를 높인다. 객관식과 주관식을 모두 지원한다.
핵심 시나리오
- S 캐릭터가 “으하하하~~ 나는 에스다. 널 위한 행운의 단어를 불러주마, 잘 찾아보거라.”라고 안내한다.
- 웃음과 안내 음성이 배경 소음 속으로 점차 묻힌다.
- “오늘의 내 행운은 ‘사과’에 있다.” 같은 키 문장을 재생한다.
- 재생이 끝난 뒤 질문과 네 개의 선택지를 표시한다.
- 선택지는 정답 1개와 사전에 존재하는 유사어 오답 3개로 구성한다.
- 오답은 자음·모음 변형 규칙의 서로 다른 난이도를 반영하고, 데이터에 변형 종류를 명시한다.
기능 요구사항
- 반응형 SPA, 데스크톱·모바일 키보드/터치 지원
- 시작 화면, 게임 화면, 결과 화면, 다시 듣기, 다음 문제, 전체 진행률
- 사용자가 브라우저 정책상 필요한 “소리 시작” 조작을 직접 누르도록 설계
- Web Audio API로 보이스와 배경을 믹싱하고 목표 음성 gain을 dB 기준으로 적용
- 최소 5단계 난이도. 단계가 높아질수록 목표 문장과 배경의 상대 dB가 낮아짐
- 최소 10개 문제 유형. 객관식·주관식을 포함하고 데이터 조합으로 실제 문제가 더 늘어남
- 최소 8개 배경 환경: 길거리, 쇼핑몰, 극장, 백화점, 시장, 지하철, 카페, 비 오는 거리
- 기본 패턴 문장, 시험 문장, 질문, 답, 오답 후보, 배경 프리셋을 저장된 데이터로 분리
- 사전 단어만 사용하는 4지선다 데이터와 각 오답의 변형 규칙 메타데이터
- 점수, 정답률, 연속 정답, 난이도별 결과
- 접근성: aria, 명확한 focus, 키보드 조작, reduced motion, 색 대비
- 오디오가 없거나 로드 실패해도 사용자에게 명확한 오류와 재시도 제공
- 개인 데이터 수집·로그인·추적기 없음
- 버전 0.1을 UI와 package metadata에 표시
오디오 요구사항
- 라이선스 불명확한 외부 자산을 사용하지 않는다.
- 직접 생성한 배경 소음·효과음을 저장하거나, 브라우저에서 결정론적으로 합성하는 프리셋을 사용한다.
- 한국어 목표 음성은 가능하면 직접 생성한 오디오 파일로 저장한다. 네트워크 TTS를 사용했다면 생성 스크립트·출처·생성 절차를 문서화하고 앱은 런타임에 외부 TTS를 호출하지 않는다.
- 모든 자산의 provenance를
docs/AUDIO_PROVENANCE.md에 기록한다. - 오디오 파일을 커밋할 경우 크기를 합리적으로 제한하고 build 결과에 포함되는지 테스트한다.
개발 규칙
- strict TDD: 각 동작은 실패하는 테스트를 먼저 작성하고 실제 RED→GREEN 근거를
.agent/RESULT.md에 기록한다. - TypeScript strict mode를 사용한다.
- 모든 직접 작성 소스 코드에 상세한 한국어 주석을 단다. 자명한 문법 줄마다 반복 주석을 붙이지 말고 알고리즘, 상태, 오디오, 난이도, 접근성, 보안 의도를 설명한다.
- generated lockfile과 기계 생성 바이너리는 주석 대상이 아니다.
- 비밀값, 서버 자격증명, API 키를 저장하지 않는다.
- 서버 배포는 하지 않는다.
- Git 커밋은 하지 않는다. Neo가 검증 후 커밋한다.
권장 기술
- Vite + React + TypeScript
- Vitest + Testing Library
- 순수 CSS 또는 가벼운 CSS 구조
- 정적 빌드(
dist/)로 Nginx 배포 가능
산출물
- 동작하는 v0.1 소스
- 최소 10개 문제 유형과 조합 가능한 데이터
- 오디오 생성·재생 구조
- unit/component 테스트
README.md,docs/ARCHITECTURE.md,docs/AUDIO_PROVENANCE.md,docs/DEPLOYMENT.md.agent/RESULT.md: 변경 파일, RED/GREEN 명령과 실제 결과, 전체 검증 결과, 미해결 위험