Claude Code로 나만의 AI 학교 생활 도우미 "별이" 만들기

Claude Code로 초등학교 3학년 아이를 위한 학교 생활 시뮬레이터 앱 — 아이디어부터 Vercel 배포까지 전 과정

소개

시도하고자 했던 것

초등학교 3학년 아이의 아버지로서, 아이가 학교에서 겪는 작은 어려움들이 마음에 걸렸습니다. 특별한 문제가 있는 건 아닌데, 또래보다 조금 느린 구석이 있었어요.

아내가 아이의 초등학교 참관학습을 다녀온 후, 학교에서의 아이 모습이 집에서의 모습과 전혀 다르다는 것을 발견했다.

- 집에서의 아이: 활발하고 에너지 넘치며 말도 많고 자기 주장도 뚜렷함

- 학교에서의 아이: 조용하고 자신감이 없어 보이며, 선생님의 말씀을 듣고 지시를 따라가는 데 어려움을 보임

단순히 수줍음이 많은 것이 아니라, "뭘 해야 하는지 잘 모르는 것" 처럼 보였다. 즉, 수업 내용이나 규칙을 미리 알고 있었다면 더 자신 있게 참여할 수 있었을 것이라는 인상을 받았다.

연습이 필요한 상황이었습니다. 그래서 Claude Code와 함께 아이 전용 앱을 직접 만들기 시작했습니다.

이름은 별이의 공부방 ⭐

진행 방법

사용한 도구

Phase 1: "공부 도우미"에서 "학교 생활 시뮬레이터"로 방향 전환

claude의 design.md 파일을 gpt에게 검증을 요청하여 나온 답변

ALT

gpt 의 대답

수학 실력보다 학교 상황 대처 능력이 훨씬 더 큰 문제였거든요. 그래서 Claude Code에게 gpt의 답변 방향으로 다시 설계를 요청했습니다.

Claude Code는 즉시 설계 문서를 재작성하고, 타입 정의부터 API 라우트, 페이지 컴포넌트까지 전체 구조를 새로 설계해줬습니다.

Phase 2: 핵심 기능 4가지 구현

별이 미션 모드 — 15개 씨드 시나리오 + AI 무한 생성

선생님 말씀: "소리 내어 한 문단씩 돌아가며 읽을 거예요. 준비하세요!"

어떻게 할까?
① 아무것도 안 한다
② ✅ 교과서에서 내 차례 부분을 찾아 미리 눈으로 읽어본다
③ 다른 책을 꺼낸다
④ 손을 든다

5가지 카테고리: 수업 준비 / 수업 활동 / 이동·정렬 / 쉬는 시간 / 점심·급식

친구 상황 연습 — 정답 후 실제 대사 제공

정답 후: 이렇게 말해봐 → "응, 나도 하고 싶었어! 어느 편이야?"

단순히 정답을 알려주는 게 아니라 실제로 쓸 수 있는 대사를 줍니다. 아이에게는 "알고 있는 것"과 "실제로 말할 수 있는 것"이 다르니까요.

ALT

휴대폰에 있는 한국어 앱의 스크린샷

수업 미리보기 — AI가 다음 수업 내용을 아이 눈높이로 미리 설명

ALT

한국어 앱 스크린샷

수학 적응형 학습 — 틀렸을 때 AI가 단계별로 설명

ALT

iPad의 수학 앱 스크린샷

Phase 3: 아이를 위한 디테일 다듬기

Claude Code에게 물었습니다.

"이 앱이 우리 아이 관점에서 몇 점 정도 될까? 객관적으로 평가해줘."

Claude Code의 답: 68점

약점으로 꼽은 3가지:

1. 디자인이 아이용이 아님 — 캐릭터 없음

2. 정답 시 감흥 없음 — 애니메이션 없음

3. 매일 앱을 열 이유 없음 — 일일 습관 유도 없음

그래서 바로 개선 작업에 들어갔습니다.

별이 캐릭터 (SVG) — 눈, 입 표정이 있는 노란 별 캐릭터. 기분에 따라 표정 변화.

// 기쁨·생각중·응원·축하 — 4가지 표정
const mouths = {
  happy:       "M 37 57 Q 50 69 63 57",
  celebrating: "M 35 55 Q 50 72 65 55",
  encouraging: "M 37 60 Q 50 66 63 60",
  thinking:    "M 37 60 Q 43 55 50 60 Q 57 65 63 60",
}

정답 StarBurst 애니메이션 — 맞추면 ⭐✨🌟 8개가 사방으로 터짐

@keyframes starBurst {
  0%   { transform: translate(0, 0) scale(0.2); opacity: 1; }
  100% { transform: translate(var(--dx), var(--dy)) scale(1.3); opacity: 0; }
}

오늘의 도전 배너 — 매일 다른 미션이 홈에 노출

결과 공유 버튼 — "오늘 미션 4/5 맞췄어요!" — 부모 공유로 아이 동기부여

Phase 4: 음성 지원 추가

음성지원을 제안했습니다. 글자가 많아서 실제 교실과 비슷하게 만들고싶었습니다.

"실제로 더 도움이 되려면 선생님 말씀은 음성 지원도 되게 하면 좋지 않을까?"

Claude Code가 즉시 구현:

• useSpeech.ts 훅 — Web Speech API 래핑, ko-KR, 속도 0.82

• SpeakButton.tsx — 자동 재생 + 재생 중 "멈추기" 토글

• 미션 페이지: 새 문제마다 선생님 말씀 자동 재생

• 친구 연습 페이지: 친구 대사 자동 재생

추가 API 비용 없음. 브라우저 내장 기능만으로.

Phase 5: GitHub → Vercel 배포

Claude Code가 git 커밋까지 직접 실행했습니다.

git add src/
git commit -m "Build school life simulator app for elementary student"
git push -u origin main

배포 중 마주친 문제들: 실제 ai가 마주친 문제들이므로 저는 신경쓸 필요가 없었음

ESLint 빌드 오류 — react/no-unescaped-entities 규칙이 큰따옴표를 막음
→ .eslintrc.json에 규칙 비활성화로 해결

TypeScript null safety 오류 — progress.mission.totalPlayed possibly undefined
→ optional chaining ?.으로 수정

Vercel 기존 프로젝트 캐시 오류 — 이전 실패 빌드가 캐시에 남아 계속 실패
→ 프로젝트 이름을 byeori-school로 새로 생성해서 해결

최종 배포 성공:

✓ Generating static pages (17/17)
Production: https://byeori-school.vercel.app

결과와 배운 점

배운 점

1) 기술보다 관찰이 먼저다

처음엔 수학 앱이었습니다. 아이를 관찰하면서 진짜 문제가 뭔지 알게 됐어요. Claude Code는 코드를 짜는 파트너이지만, 무엇을 만들지는 부모인 내가 제일 잘 압니다.

2) "알고 있는 것"과 "할 수 있는 것"은 다르다

친구 상황 연습에서 정답만 알려주는 게 아니라 실제 대사를 주는 이유입니다. 아이에게 "어떻게 해야 한다"보다 "이렇게 말해봐"가 훨씬 효과적이에요. Claude Code도 이 차이를 설계에 반영했습니다.

3) AI 실패에도 앱이 멈추면 안 된다

중간에 api문제가 있어 제미나이 api를 발급받았습니다.

4) 점수를 물어보면 솔직하게 말해준다

앱 완성도를 물었을 때 68점이라고 했습니다. 그 평가를 기반으로 구체적인 개선 항목이 나왔고, 실제로 구현했어요. AI에게 칭찬 말고 평가를 요청하는 것이 더 유용합니다.

나만의 꿀팁

🍯 팁 1: "몇 점이야?"를 물어볼 것

기능 구현 후 Claude Code에게 사용자 관점의 객관적 평가를 요청했더니 약점 3가지와 구체적 개선안이 나왔습니다. "잘 만들었어"보다 "68점이고, 이래서 그래"가 훨씬 유용해요.

🍯 팁 2: 타입 정의를 먼저 잡을 것

types/index.ts에 MissionScenario, SocialProgress 같은 타입을 먼저 정의하고 시작하니, 여러 파일을 동시에 만들어도 일관성이 유지됐습니다. Claude Code가 자연스럽게 이 패턴을 제안했어요.

🍯 팁 3: Seed 데이터 + AI 하이브리드 패턴

API 콜이 항상 성공한다는 보장이 없습니다. 특히 아이가 쓰는 앱은 "막히는 경험"이 치명적이에요. 15개 씨드 데이터를 먼저 만들고, AI가 추가 생성 — 이 하이브리드 패턴이 가장 안전합니다.

🍯 팁 4: 배포 오류는 이름을 바꾸면 해결될 때가 있다

Vercel에서 캐시된 실패 상태가 계속 막을 때, 프로젝트 이름을 바꿔서 새로 생성하니 바로 해결됐습니다. 기술 문제가 아니라 상태 문제일 때는 깔끔하게 리셋.

시행착오

😅 Tailwind 동적 클래스 purge 문제

from-orange-400 to-yellow-400 같은 동적 클래스는 빌드 시 purge됩니다. 스포츠 카드 배경 그라디언트가 전부 흰색으로 나왔어요. CSS 값을 직접 style prop으로 주는 방식으로 해결.

// ❌ bgGradient: "from-orange-400 to-yellow-400"
// ✅ bgGradient: "linear-gradient(to bottom right, #fb923c, #facc15)"

😅 Next.js 14 params는 Promise가 아니다

스포츠 상세 페이지에서 use(params) 사용 → 크래시. Next.js 14에서 params는 일반 객체.

// ❌ const { sport } = use(params)
// ✅ const sportId = decodeURIComponent(params.sport)

😅 React Hooks Rules 위반

useMemo를 조건부 return 이후에 넣었더니 "Rendered more hooks than previous render" 에러. 훅은 반드시 모든 early return 위에 있어야 합니다. Claude Code가 즉시 위치를 수정했어요.

앞으로의 계획

1. 선생님 연계 — 담임 선생님이 직접 시나리오를 추가하는 기능

2. 부모 대시보드 — 아이가 어떤 상황을 어려워하는지 패턴 분석

3. 시나리오 확장 — 방과후, 급식, 체육 시간 등 구체적 상황 추가

4. 코칭 비즈니스 연계 — 미숙한 아이뿐만 아니라 비슷한 고민을 가진 다른 부모들과 공유

마치며

이 앱이 완벽한 해결책은 아닙니다.

하지만 아이가 저녁에 "오늘 미션 해도 돼?" 하고 먼저 물어보기 시작했어요.

연습을 놀이처럼 느끼게 만드는 것. 그것만으로도 충분합니다.

💡 핵심 한 줄: Claude Code로 앱을 만드는 비결은, 코드를 짜달라고 하기 전에 "아이가 진짜 힘들어하는 게 뭔지"를 먼저 관찰하는 것. AI는 코드를 짜고, 부모는 문제를 정의한다. 그 역할 분담이 맞아야 진짜 쓸만한 앱이 나온다.