Kotoba Quest

단어 연습 앱은 답이 틀렸다고는 알려 주지만, 그 선택지가 왜 틀렸는지는 잘 알려 주지 않습니다. 단어를 찾아보다 보면 풀던 자리를 잃기도 합니다. 작은 게임이 틀린 선택지마다 이유를 설명하고, 문제를 풀다 사전을 확인한 뒤 같은 문제로 돌아오게 하며, 계정이나 서버 없이도 정직한 기록을 남길 수 있을까요?

네 가지 문제 유형(읽기, 쓰기, 문맥 속 단어, 문법)은 저장된 선택지 ID와 비교해 규칙으로 채점하므로, 선택지 순서를 섞어도 정답이 바뀌지 않습니다. 틀린 선택지마다 해설이 따로 있고, 각 문제는 시험하는 사전 항목으로 연결됩니다. 사전에는 한자, 단어, 문법 항목과 예문이 들어 있습니다.

한 판을 하는 동안 문제와 그 개정판, 선택지 순서, 고른 답, 채점, 보상을 IndexedDB에 저장합니다. 페이지를 새로 고치거나 문제에서 사전을 열었다 돌아와도 같은 문제에서 이어집니다. 답, 보상, 진행 상황은 하나의 트랜잭션으로 기록되고, 같은 답을 다시 내면 저장된 결과를 돌려줄 뿐 보상을 두 번 주지 않습니다.

코인으로 모자, 스카프, 무기를 삽니다. 구매는 잔액 확인, 차감, 소유 기록, 원장 기록을 하나의 트랜잭션으로 처리하고, 같은 구매 요청이 반복돼도 두 번 청구하지 않습니다. 게임, 옷장, 프로필 카드가 모두 같은 장착 캐릭터를 그립니다. 카드는 캔버스에 4:5 또는 9:16 PNG로 그려 공유하거나 저장할 수 있고, JSON 백업으로 기록을 내보내고 복원합니다.

맞힌 문제는 1일, 3일, 7일 뒤에 복습으로 돌아오고, 틀린 문제는 다음 날 돌아옵니다. 매일 출석 보상은 별도 원장에 기록되며 학습으로 치지 않습니다. 처음 내려받은 뒤에는 서비스 워커가 앱을 캐시해 오프라인에서도 돌아갑니다. 소리는 플레이어가 켜기 전까지 꺼져 있습니다.

데모에는 초급 팩 두 개가 있습니다. 휴식과 몸에 관한 14문제, 요일과 날짜에 관한 15문제이며, 사전 항목 21개와 예문 24개가 함께 들어 있습니다. 일반 학습에는 승인된 문제만 쓸 수 있는데 그 목록이 비어 있으므로, 일반 학습은 “준비 중” 화면을 보여 주고 초안 문제는 미검수로 표시한 데모 모드에서만 나옵니다.

공식 빌드는 최종 QA 중이어서 건드리지 않았습니다. 2026년 11월 8일, 소스 파일이 SHA-256으로 원본과 일치하는 사본에서 검사를 다시 돌렸습니다. 그때는 Vitest 테스트 106개가 파일 15개에 걸쳐 모두 통과했고, TypeScript 검사, 콘텐츠 검사(고정 파일 세 개: 초안 문제 14 + 15개, 항목 21개, 예문 24개), 오디오 검사(선택 파일 13개)도 통과했습니다. 그 뒤 개발 브랜치의 Vitest 테스트는 파일 19개에 걸쳐 154개로 늘었고, 2026년 11월 10일 그 브랜치(hyh4867/kotoba-quest, 커밋 20bc1e9)를 내보낸 사본에서 모두 통과했으며 TypeScript 검사도 통과했습니다.

테스트는 선택지 ID 기반 규칙 채점, 섞은 뒤에도 맞게 붙는 오답 해설, 새로 고침과 사전 왕복 뒤의 판 복원, 같은 답에 보상이 두 번 들어가지 않는지, 두 번 청구되지 않는 구매, 학습과 분리된 출석, 복습 날짜, 카드 PNG와 공유 대체 동작, 백업과 이전 버전에서의 마이그레이션, 오프라인 캐시를 다룹니다. IndexedDB와 서비스 워커를 모의 객체로 바꾼 jsdom에서 실행합니다. 헤드리스 Chrome(390·375 px)에서 진행한 최종 QA에서 출시를 막는 문제는 없었습니다. 앱 파일이 캐시된 뒤에는 오프라인에서 다시 실행되었고, 보상과 구매가 두 번 들어간 적은 없었습니다.

스크린샷은 동결한 출시 후보 빌드(빌드 ID ceb3b15e2a1b3356)를 헤드리스 Chrome의 폰 너비에서 실행해 찍었습니다. 가상의 플레이어 “Player”가 데모 한 판을 하며 한 문제를 일부러 틀리고, 연결된 사전 항목을 열었다 돌아온 뒤, 초급 검을 사서 장착하고 4:5 카드를 만들었습니다.

그 판에서 休日의 오답 きゅうにち를 고르자 그 선택지에 맞춰 쓴 해설이 나왔고, 사전 버튼은 休日 항목을 열었으며, 돌아오자 채점된 같은 문제가 복원되었습니다. 8문제 중 7개를 맞혀 70 XP와 35코인을 얻었습니다. 이어서 산 10코인짜리 검이 옷장 캐릭터와 생성한 카드에 함께 나타났습니다.

틀린 선택지마다 해설을 따로 쓰다 보니 약한 문제가 드러났습니다. 한 문법 문제는 오답 두 개를 문맥 판단으로만 걸러낼 수 있었고, 이를 바꾸자 새로운 모호함이 생겨 팩에서 보류했습니다.

기획과 게임이 지켜야 할 규칙을 정했습니다. 모든 선택지에 해설을 붙일 것, 일반 학습에 초안 문제를 쓰지 않을 것, 보상을 두 번 받을 수 없을 것, 기록이 폰에만 남을 것. 캐릭터와 사운드 세트를 골랐고, 어떤 문제를 공개할지 결정합니다.

AI 에이전트가 역할을 나눠 일했습니다. Claude는 화면과 캐릭터 아트를 디자인하고 브라우저 QA를 맡았고, Codex는 앱과 테스트를 구현했으며, 둘 다 문제 초안 작성과 검토를 도왔습니다. 음악과 효과음은 개발 중 ElevenLabs로 생성해 파일로 넣었습니다. 결과물을 검토했고 이 페이지의 주장은 제가 책임집니다.

완성된 강좌가 아닙니다. 29문제 모두 초급 주제 두 가지에 대한 미검수 초안입니다. JLPT 교재나 N5–N1 과정이 아니며, “초급”은 공식 급수가 아닌 안내용 표시입니다.

채점은 고른 답을 저장된 정답과 비교합니다. 게임 레벨과 XP는 플레이 기록일 뿐 일본어 실력이 아니며, 게임이 학습에 도움이 되는지는 시험하지 않았습니다. 1·3·7일 복습 간격은 출발점으로 정한 규칙이며 조정한 일정이 아닙니다.

설치, iPhone 동작, 실제 스피커 출력은 아직 확인하지 않았고, 업데이트 전달과 캐시 복구는 여전히 수정이 권장됩니다. 처음 내려받기 전에는 오프라인으로 시작할 수 없습니다.

공개 출시에는 승인이 두 가지 더 필요합니다. 사람이 문제를 검수하는 것과, 생성한 오디오의 이용 조건을 확인하는 것입니다. 앱을 배포하지 않았으므로 라이브 데모는 없습니다.

코드는 비공개입니다. 출시 후보 보고서에 빌드 ID, 정적 빌드의 모든 파일에 대한 SHA-256, 각 검사의 로그를 기록했습니다. 사전은 JMdict, KANJIDIC2, KanjiVG 데이터를 쓰며 앱 설정에 출처를 밝혔습니다. 모든 스크린샷은 가상 플레이어로 진행한 데모 모드에서 찍었고, 데모 표시는 그대로 두었습니다.