소개
분당에서 영어 읽기 전문 학원을 운영하는 Reading Horizons Master Teacher입니다. 22년간 아이들을 가르치면서 늘 이런 문제가 있었어요. "처음 만나는 학생의 읽기 수준을 정확히 파악하는 데 2~3주가 걸린다." 학부모에게 "왜 이 수준인가요?"라는 질문을 받으면 설명은 할 수 있는데, 근거 자료로 보여줄 문서가 없었습니다.
그래서 Claude를 활용해서 직접 AI 읽기 진단 웹앱을 만들어봤습니다. 코딩 경험 없는 비개발자가 Claude Code와 Claude AI를 활용해 기획부터 배포까지 진행 한 과정을 공유합니다.
진행 방법
진행 방법
사용 도구
Claude (기획, 코드 작성, 디버깅, 문서 작성 전반)
Claude Code (파일 관리, 빌드, 코드 실행)
React + Vite (프론트엔드)
Vercel (배포, 무료)
GitHub (코드 저장소)
OpenAI Whisper API (음성 인식)
Anthropic Claude API (AI 진단 분석)
1단계 — 앱 구조 기획
Claude에게 내 문제 상황을 설명하고 구조를 함께 설계했습니다.
사용한 프롬프트:
나는 22년 경력의 영어 읽기 전문 원장이야.
Reading Horizons Master Teacher 자격이 있고,
파닉스와 난독증 지도를 전문으로 해.
다음 문제를 해결하고 싶어:
1. 처음 오는 학생의 읽기 수준을 빠르게 파악하고 싶다
2. 학부모에게 진단 근거를 PDF로 줄 수 있으면 좋겠다
3. 난독증이 의심되는 아이의 어떤 하위 기술이 약한지 파악하고 싶다
React 웹앱으로 만들고 싶은데, 어떤 구조가 좋을까?Claude가 제안한 구조:
로그인/회원가입 (localStorage 기반)
아이 정보 입력 → 설문 → AI 분석 → 결과 리포트
PDF 다운로드
진단 기록 저장
2단계 — 핵심 기능 구현
AI 읽기 진단
AI 읽기 진단
Claude API를 활용한 진단 분석 프롬프트 (실제 사용 버전):
system: 'You are an expert in Reading Horizons methodology and structured
literacy for Korean children learning English. Analyze diagnostic data
and produce a personalized diagnosis with ACTIONABLE teaching tips.
RESPOND ONLY IN JSON:
{
"overallLevel": "Level description in Korean",
"levelNumber": 2,
"summary": "2-3 sentences in Korean using simple language",
"strengths": ["..."],
"challenges": ["..."],
"recommendations": [{"title": "...", "desc": "...", "priority": "high/medium/low"}],
"teachingTips": [{"title": "...", "how": "...", "example": "..."}],
"nextSteps": ["..."],
"readingHorizonsPath": "...",
"categoryScores": {
"phonemic_awareness": 75,
"decoding": 60,
"phonics_patterns": 40,
"fluency": 50,
"comprehension": 65,
"attitude": 70
}
}
teachingTips은 전문 지식 없는 학부모/교사가 집에서 바로 시도할 수 있는 팁으로.'난독증 심층 스크리닝
현장에서 자주 겪는 "블렌딩은 되는데 받아쓰기가 안 되는 아이"의 패턴을 분석하기 위해 7개 하위 기술로 세분화했습니다.
글자-소리 대응
블렌딩 (소리 합치기)
세그멘팅 (소리 쪼개기)
인코딩/받아쓰기
시각 변별 (b/d, p/q 혼동)
빠른 이름대기 (RAN)
작업 기억
Claude에게 이 7개 영역을 설명하고 불균형 패턴을 자동 감지하는 알고리즘을 코드로 작성하게 했습니다.
// 블렌딩-인코딩 불균형 패턴 감지 (실제 코드)
if (scores.blending > 60 && scores.encoding < 40) {
patterns.push({
title: '블렌딩 > 인코딩 불균형',
icon: '⚖️',
desc: ' 소리를 합쳐 읽기는 가능하지만, 소리를 듣고 글자로 쓰기가 어렵습니다.',
tip: '소리를 듣고 글자 타일을 골라 단어를 만드는 연습부터 시작하세요.'
})
}음성 기반 파닉스 테스트
시행착오: 처음에는 TTS(Text-to-Speech)로 음소 소리를 들려주려 했습니다. 하지만 브라우저 TTS는 "b"를 /b/ 소리가 아닌 "비(bee)"라는 글자 이름으로 읽는 문제가 있었습니다.
해결: 개별 음소 대신 예시 단어를 들려주는 방식으로 전환했습니다. "b" 소리를 묻는 대신 "ball", "bat", "sun" 세 단어를 들려주고 b로 시작하는 단어를 고르게 했어요. 음소 인식 테스트 본래 목적도 더 잘 달성됩니다.
javascript
// 음소 → 예시 단어 매핑 (실제 코드)
var PHONEME_WORDS = {
'b': 'ball', 'd': 'dog', 'f': 'fish',
'short a': 'cat', 'short e': 'bed', 'short i': 'sit',
'sh': 'ship', 'ch': 'chip', 'th': 'thin',
}읽기 유창성 테스트 (Whisper API)
아이가 단어/문장/문단을 소리 내어 읽으면, Whisper API가 음성을 텍스트로 변환하고, 원문과 단어별로 비교합니다.
javascript
// Whisper API 연동 (실제 코드)
var formData = new FormData()
formData.append('file', blob, 'audio.webm')
formData.append('model', 'whisper-1')
formData.append('language', 'en')
var res = await fetch('https://api.openai.com/v1/audio/transcriptions', {
method: 'POST',
headers: { 'Authorization': 'Bearer ' + apiKey },
body: formData,
})결과 화면에서 단어별 색상으로 표시됩니다:
초록: 정확하게 읽음
주황: 비슷하게 읽음
빨강: 틀리게 읽음
3단계 — 시행착오
한글 PDF 깨짐 문제
문제: jsPDF로 PDF를 생성하면 한글이 모두 깨져서 출력됐습니다.
1차 시도 (실패): Google Fonts(Noto Sans KR)를 웹폰트로 불러온 후 인쇄. Chrome의 "PDF로 저장" 기능이 웹폰트를 PDF에 임베딩하지 못하는 버그가 있어 여전히 깨짐.
해결: jsPDF를 완전히 버리고, HTML을 새 창에 열어 브라우저 인쇄 기능을 활용하는 방식으로 전환. 폰트는 시스템에 이미 설치된 '맑은 고딕'(Windows)을 사용. 시스템 폰트는 Chrome이 PDF에 정상 임베딩합니다.
javascript
// 최종 해결 코드
const font = "'맑은 고딕','Malgun Gothic','Apple SD Gothic Neo',sans-serif"
var w = window.open('', '_blank')
w.document.write(html) // 시스템 폰트 사용한 HTML
w.document.close()
setTimeout(function() { w.focus(); w.print() }, 500)Git 배포 충돌 문제
문제: GitHub 웹에서 파일 수정 후 로컬에서 git push --force를 실행했더니 GitHub 웹 수정 내용이 모두 날아갔습니다.
배운 것: git push --force는 원격 저장소의 내용을 로컬로 덮어쓰므로, GitHub 웹 편집과 혼용할 때 절대 사용하면 안 됩니다.
해결: GitHub 웹 에디터에서 직접 파일 수정 후 Commit하는 방식으로 통일했습니다.
4단계 — 배포
Vercel + GitHub 연동으로 코드를 push하면 자동 재배포됩니다.
환경변수 설정:
VITE_ANTHROPIC_API_KEY: Claude AI 진단 분석용VITE_OPENAI_API_KEY: Whisper 음성 인식용결과와 배운 점
결과
배포 URL: litpath-ai.vercel.app (현재 운영 중)
구현 기능: AI 읽기 진단 / 난독증 심층 스크리닝 / 파닉스 레벨 테스트 / 읽기 유창성 테스트
베타 테스터: 영어 학원 원장님 10명
베타 테스터 피드백 (실제 수집):
"파닉스 완성 전 단계 아이들의 수준 파악에 좋다" "직관적이고 깔끔하다" "학원 학생 관리 + 학부모 카톡 전송 연동이 되면 좋겠다" "주관적 체크보다 아이가 직접 문제를 풀어서 점수가 나오면 더 좋겠다"
피드백 중 즉시 반영한 것들:
구체적 티칭 팁 + 예시 활동 추가
용어 설명 툴팁 15개 추가 (파닉스, 디코딩, 블렌딩 등)
난독증 하위 기술 심층 스크리닝 추가
무료 1회 제한 + 유료 전환 화면 추가
배운 점
1. 전문 용어를 정확하게 쓸수록 AI 결과가 달라진다
처음에 "영어 읽기 진단 앱"이라고만 했을 때는 일반적인 결과가 나왔습니다. "Reading Horizons 42개 음소 체계", "LEDDI RSA Lexile", "음운 인식 vs 음소 인식" 같은 전문 용어를 정확하게 쓰자 훨씬 전문적이고 맥락에 맞는 코드와 콘텐츠가 나왔습니다.
2. TTS로 개별 음소를 읽히는 건 불가능하다
브라우저 내장 TTS는 개별 알파벳을 소리가 아닌 이름으로 읽습니다. 음소 인식 테스트를 구현하려면 직접 녹음한 음성 파일이 필요합니다. 이 부분은 아직 미해결 상태입니다.
3. 비개발자가 만든 코드의 한계
Claude가 작성한 코드는 잘 작동하지만, 내가 코드 구조를 이해하지 못하니 오류가 생겼을 때 어디를 고쳐야 할지 모르는 상황이 자주 있었습니다. 다음 단계로는 코드 구조에 대한 기초 이해가 필요할 것 같습니다.
도움이 필요한 부분
음소 개별 녹음 파일을 앱에 연동하는 부분 — 44개 음소를 각각 녹음해서 웹앱에서 재생하는 구조를 구현하려고 하는데, 파일 관리와 타이밍 문제에서 막혀 있습니다.
앞으로의 계획
베타 단톡방 이벤트 (스타벅스 증정 피드백 수집)
와디즈 펀딩 준비
객관식 문항 추가 (아이가 직접 푸는 방식)
학원 관리 + 학부모 카카오톡 전송 기능
도움 받은 글
이 커뮤니티의 Claude Code 활용 사례글들을 참고했습니다.
Whisper API 연동 방식은 OpenAI 공식 문서를 참고했습니다. (platform.openai.com/docs)
