끝말잇기: 이기면서 배우는 AI 끝말잇기
초등학생이 AI와 끝말잇기를 하면서 표준어와 그 뜻을 자연스럽게 익히는 웹 앱입니다.
로블록스 끝말잇기는 표준어가 아닌 이상한 단어도 통해서, 아이가 단어는 외우는데 뜻은 모릅니다. 이 앱은 표준어만 통하게 하고, 단어를 낸 바로 그 화면에서 뜻과 그림을 보여 줍니다. 이기려고 하다 보면 단어와 뜻이 함께 남는 것이 목표입니다.
주요 기능
- AI와 한 판: 닉네임을 입력하고 AI와 번갈아 단어를 잇습니다. 차례마다 30초 안에, 기회 4번 안에 맞는 단어를 내야 합니다.
- 낼 때마다 뜻 보기: 내가 낸 단어와 AI가 낸 단어의 이모지, 뜻, 예문이 같은 화면에 바로 나옵니다.
- 두음법칙: "리"로 끝나면 "이"로도 이을 수 있고, 가능할 때는 "두음법칙 적용 가능!" 힌트가 나옵니다.
- 끝장단어: 상대가 이을 수 없는 단어를 내면 그 즉시 이깁니다. 첫 단어에는 쓸 수 없습니다.
- 힌트 도우미: 막히면 한 판에 3번까지 열 수 있는 옆면 도우미에서 이어 갈 단어와 끝장단어(🔥 표시)를 보고 뜻을 확인합니다.
- 사전 확인: 단어장에 없는 단어를 입력하면 서버가 표준국어대사전에서 표준어(명사)인지 확인하고, 맞으면 사전 뜻풀이로 판에 넣습니다. 철자가 같은 단어는 뜻을 최대 3개까지 번호로 보여 줍니다.
- 승패 기록: 닉네임별 승패가 이 기기의 브라우저에 쌓입니다. 가입이나 서버 저장이 없습니다.
| 사전에서 확인된 단어 | 결과 화면(뜻이 여러 개인 단어) | 모바일 |
|---|
| | |
기술 스택
Next.js 16 (App Router) · React 19 · Tailwind CSS 4 · shadcn/ui · Bun · Vitest · Playwright
시작하기
bun install
bun dev
http://localhost:3000에서 확인합니다. 사전 확인 기능을 쓰려면 표준국어대사전 Open API 인증 키가 필요합니다. 프로젝트 루트에 .env.local 파일을 만들고 키를 넣으세요.
STDICT_API_KEY=발급받은_32자리_키
- 키는 서버에서만 읽고 브라우저로 보내지 않습니다.
NEXT_PUBLIC_을 붙이지 마세요.
- 키가 없어도 앱은 실행됩니다. 직접 쓴 단어장으로 게임을 끝까지 할 수 있고, 단어장에 없는 단어를 입력하면 "사전에 연결하지 못했어요"가 나옵니다.
- 배포할 때는 호스팅 서비스의 환경 변수에 같은 이름으로 넣습니다.
스크립트
| 명령어 | 설명 |
|---|
bun dev | 개발 서버 실행 |
bun run build | 프로덕션 빌드 |
bun start | 프로덕션 서버 실행 |
bun run lint | ESLint 실행 |
bun run typecheck | tsc --noEmit 타입 검사 |
bun run test | Vitest 단위/컴포넌트 테스트 1회 실행 |
bun run test:watch | Vitest watch 모드 |
bun run test:e2e | Playwright E2E 테스트 실행 |
구조
features/wordchain/: 끝말잇기의 모든 코드가 있습니다. 규칙(game.ts), 단어장(words.ts), 승패 기록(records.ts), 화면 컴포넌트, 사전 확인(dictionary.ts, 서버 전용 server.ts)으로 나뉩니다. 공개 API는 index.ts입니다.app/api/word-check/: 브라우저가 부르는 사전 확인 경로입니다. 인증 키는 여기서만 쓰입니다.PRODUCT.md: 이 앱이 누구를 위해 무엇을 약속하는지 적은 제품 정의입니다.docs/specs/: 기능별 스펙(ai-wordchain-round, dictionary-word-check, hint-helper)입니다.docs/decisions/: 단어 출처와 UI 구성의 결정과 근거입니다. 어떤 사전을 검토했고 왜 이렇게 정했는지 남아 있습니다.GLOSSARY.md: 판, 차례, 기회, 끝장단어 같은 용어집입니다.
단어 출처와 라이선스
알려진 한계
- 사전에서 가져온 뜻풀이는 어른 눈높이라 길거나 어려울 수 있습니다.
- 철자가 같은 단어의 뜻을 사전 순서대로 3개 보여 주기 때문에, 흔한 뜻이 3개 안에 없거나 아이에게 적당하지 않은 뜻이 보일 수 있습니다. 흔한 단어는 단어장에 직접 쓴 뜻이 있어 영향이 작습니다.
- 단어장이 작아서(355개) 판이 짧고, 이어 갈 단어가 거의 없는 글자가 있습니다.
- 승패 기록은 브라우저에만 저장되어 다른 기기와 공유되지 않고, 저장 데이터를 지우면 사라집니다.
- 초대 링크 대전과 표준어 제안 기능은 아직 없습니다.
테스트
- 단위·컴포넌트: Vitest + Testing Library. 설정은
vitest.config.mts, 매처와 cleanup은 vitest.setup.ts에 있습니다. 테스트 파일은 소스 옆에 *.test.ts(x)로 둡니다. globals를 켜지 않았으므로 describe/it/expect는 vitest에서 import 합니다.
- E2E: Playwright. 설정은
playwright.config.ts, 테스트는 e2e/*.spec.ts에 둡니다. webServer가 bun run dev를 자동으로 띄우므로 별도 서버 실행이 필요 없습니다.
E2E를 처음 실행하기 전에 브라우저를 한 번 내려받아야 합니다.
bunx playwright install chromium
브라우저가 이미 설치된 환경(예: Claude Code 원격 세션)에서는 내려받는 대신 실행 파일 경로를 지정할 수 있습니다.
PLAYWRIGHT_CHROMIUM_PATH=/opt/pw-browsers/chromium bun run test:e2e
async Server Component는 Vitest가 아직 지원하지 않으므로 E2E로 검증합니다.
- 런타임 검증(에이전트용): agent-browser. 에이전트가
next-dev-loop 스킬로 실행 중인 앱을 직접 조작해 변경을 확인할 때 씁니다. 프로젝트 의존성이 아니므로 한 번 전역으로 설치합니다.
npm i -g agent-browser
agent-browser install # 설치된 Chrome이 없을 때만
Claude Code 워크플로우
이 앱은 아래 흐름으로 만들었습니다. 제품 정의에서 시작해 기능마다 스펙을 정하고, 구현과 검증, PR까지 이어집니다.
flowchart LR
DP["define-product"] --> PRODUCT[/"PRODUCT.md"/]
PRODUCT --> SI["shape-idea"]
SI --> SPEC[/"docs/specs/<slug>/spec.md"/]
SPEC --> ST["split-into-tasks<br/>여러 결과로 나눌 때"]
SPEC --> IMP["implement"]
ST --> IMP
IMP --> HR["human-review<br/>중대한 결과를 검토할 때"]
IMP --> PR["pr"]
HR --> PR
FU[/"docs/follow-ups/*.md"/] --> RF["resolve-follow-ups"]
RF --> PR
파이프라인 밖에서는 project-knowledge, maintain-project-context, add-stack-context, build-prototype, explain-visually, tdd가 각자의 조건에 따라 켜집니다. project-knowledge는 GLOSSARY.md, docs/decisions/, docs/follow-ups/에 다음 작업에서도 재사용할 지식과 후속 항목을 남깁니다. Git 작업은 commit, pull, push, pr, merge가 해당 요청에 맞춰 처리합니다.
