StudyHelper — AI 간격 반복 학습 도구

배경

CS 학습에 필요한 도구를 한 번에 만들고 싶었다. 기존 플래시카드 서비스는 마크다운 자료의 구조적 분석, AI 기반 개념 추출, 적응형 복습을 따로따로 제공했다. 복수의 마크다운 파일을 한 번의 LLM 호출로 구조화하면 토픽 누락·파일 분류 오류·비논리적 순서 문제가 반복됐고, 개념 목록에도 품질 편차가 있었다. 개념 품질의 하한선을 보장하면서, 학습과 정리를 같은 인터페이스 안에 두는 구조가 필요했다.

시스템 구조

• 5 레이어: app/(HTTP 라우트) → application/(유스케이스) → workflows/(LLM 파이프라인) → infrastructure/(리포지토리·LLM·파서) → core/(도메인 모델).
• LLM Gateway 추상화: infrastructure/llm/gateway.ts가 Anthropic API와 Claude CLI 프로바이더를 런타임 전환한다. generateAndValidate<T>()에서 Zod 스키마 검증 + 자동 재시도를 내장.
• 워크플로우 엔진: workflows/import-project/{engine, steps}가 토픽 추출 → 파일 분류 → 챕터 구성 → 검증 4단계 프롬프트 체이닝을 주관한다.
• 리포지토리 7종: project, chapter, study, import-job, learn-job, annotation, user-note.

해결 과정

4일 MVP + 클린 아키텍처. Day 1에 단일 커밋으로 동작하는 MVP를 올리고, 같은 날 5 레이어(app / application / workflows / infrastructure / core)로 리팩토링했다. API 라우트는 HTTP 진입·검증만 담당하고, 도메인 로직은 application/으로, LLM 파이프라인은 workflows/로, Prisma 리포지토리는 infrastructure/db/repositories/로 분리했다.

4단계 프롬프트 체이닝. 하나의 복잡한 판단을 토픽 추출 → 파일 분류 → 챕터 구성 → 검증 4단계로 나눠, 각 단계가 이전 단계의 구조화된 출력을 입력으로 받는다. 멀티파일 챕터에는 2단계 개념 분석 체인을 추가하고, 단계 사이에 폴백 캐스케이드를 두어 실패 시 헤딩 기반 결과로 내려간다.

LLM Gateway + Zod 자동 재시도. Claude API와 Claude CLI 양쪽을 LLMGateway 추상화 뒤에 두고, 호출부는 generateAndValidate<T>(prompt, schema) 하나로 스키마 검증된 결과만 받는다. 스키마 불일치 시 프롬프트를 보강해 자동 재시도한다.

개념 품질 자동 보증. 자동 스코어링(총 개수, 보조 비율, Bloom 균일도 등 5개 지표) → 조건부 LLM 수리 패스 → 헤딩 폴백과의 품질 비교 선택이라는 3단계 품질 보증 파이프라인으로 LLM 출력의 하한선을 맞춘다.

SM-2 간격 반복. 학습 후 0~5점 quality를 입력받아 lib/spaced-repetition/sm2.ts가 다음 복습 시점을 계산한다. 3 미만은 오답으로 보고 repetitions를 0으로 리셋해 다음날 다시 띄운다. 3 이상이면 1·3일 → 이후엔 직전 interval × ease factor로 늘리고, EF는 매 복습마다 quality에 따라 ±한다(하한 1.3). EF가 1.5 미만이거나 연속 2회 오답이면 재학습 큐에 들어간다.

백그라운드 프리페칭. DB 기반 잡 큐(LearnJob 테이블)와 인프로세스 백그라운드 워커로 사용자가 첫 개념을 학습하는 동안 나머지 개념 콘텐츠를 미리 생성한다. 캐시 히트 시 즉시 로딩이 된다.

어노테이션 시스템. 텍스트 선택 기반 인라인 하이라이트·메모, 색상 코딩, 필터·정렬, 챕터별 노트북 뷰를 하나의 어노테이션 UI로 통합했다. 학습과 정리가 같은 화면에서 끝난다.

성과

• Next.js 15 + Prisma + SQLite 기반 5 레이어 클린 아키텍처, Prisma 10 모델 · 리포지토리 7 · API 라우트 13.
• 4단계 프롬프트 체이닝 + 개념 품질 자동 스코어링/수리로 LLM 출력 품질 하한선 보장.
• LLM Gateway 추상화로 Anthropic API ↔ Claude CLI 프로바이더 런타임 전환.
• 백그라운드 프리페칭으로 이미 생성된 개념은 즉시 로딩, 학습 몰입 유지.
• 어노테이션 하이라이트·메모·필터·노트북 뷰로 학습·정리 통합 인터페이스 제공.