책잇 (Bookit)
독후감을 읽고 되묻는 AI로 초등·중학생의 독서 이해도를 검증하고 포인트로 보상하는 서비스
원티드 AI Championship 2026 출품작. 제출 마감 2026.9.20, 심사 기간 10.5까지 배포 링크가 살아 있어야 합니다.
무엇을 만드나
아이가 책을 읽고 독후감을 쓰면, AI가 독후감에서 논리의 빈틈을 찾아냅니다. 그 빈틈을 근거로 아이가 쓴 문장을 인용해 "왜 그렇게 생각했어?"라고 되묻고, 30~60초 안에 답하게 합니다. 답변이 독후감과 논리적으로 맞고 충분히 구체적이면 통과 처리하고 책갈피(포인트)를 지급합니다.
기존 독서 앱은 "읽었다/안 읽었다"만 확인합니다. 책잇은 "이해했는가"를 확인합니다. 이게 유일한 차별점이고, 심사 점수도 대부분 여기서 갈립니다.
기술 스택
| 영역 | 선택 |
|---|
| 프레임워크 | Next.js (App Router, TypeScript) |
| DB | Supabase PostgreSQL |
| 인증 | Supabase Auth — 구글 로그인만 |
| 서버리스 | Vercel Route Handler 만 사용 (Edge Functions 미사용) |
| LLM | Anthropic Claude claude-sonnet-5 — 1개 벤더로 통일, 서버에서만 호출 (Gemini 에서 전환, #54) |
| 배포 | Vercel |
| 스토리지 | 사용 안 함 (업로드 기능 없음) |
| 패키지 매니저 | npm (#7) |
시작하기
npm ci
cp .env.example .env.local # 값은 김민경에게 요청
npm run dev
필요한 환경변수는 .env.example에 전부 적혀 있습니다. 변수를 추가했다면 .env.example도 같이 갱신해주세요. .env.local은 절대 커밋하지 않습니다.
Supabase · 구글 로그인 설정 (최초 1회)
프로젝트를 아직 안 만들었다면 이 순서대로 합니다. 4번까지 끝나야 로그인이 돕니다.
-
Supabase 프로젝트 생성 — 리전은 Northeast Asia (Seoul). 대시보드 Settings → API 에서 Project URL, anon key, service_role key 를 .env.local 에 옮겨 적습니다.
-
구글 OAuth 클라이언트 발급 — Google Cloud Console → 사용자 인증 정보 → OAuth 클라이언트 ID (웹 애플리케이션).
승인된 리디렉션 URI 에 Supabase 주소를 넣습니다 (우리 앱 주소가 아닙니다):
https://<project-ref>.supabase.co/auth/v1/callback
-
Supabase 에 구글 연결 — Authentication → Providers → Google 을 켜고 2번의 Client ID / Secret 을 붙여 넣습니다.
-
리디렉션 주소 등록 — Authentication → URL Configuration:
- Site URL:
http://localhost:3000 (배포 후에는 Vercel 주소)
- Redirect URLs:
http://localhost:3000/auth/callback 과 배포 주소의 /auth/callback 을 둘 다 등록
-
스키마·시드 적용 — SQL Editor 에서 supabase/migrations/ 의 파일을 번호 순서대로 실행한 뒤 supabase/seed.sql 을 실행합니다. (supabase link 후 supabase db push 도 같은 결과입니다.)
로그인 흐름은 이렇습니다: 로그인 화면 → 구글 → Supabase(/auth/v1/callback) → 우리 앱(/auth/callback, 여기서 세션 쿠키를 심습니다) → / → 미들웨어가 학생/교사/온보딩으로 나눠 보냅니다.
폴더 구조
docs/ spec.md(스키마·API 계약), design-tokens.md, prompts.md
src/
├── app/ 라우트만. 로직은 넣지 않습니다
│ ├── (auth)/ 로그인, 온보딩
│ ├── (main)/ 홈, 작성, 마이, 서재, 챌린지
│ ├── (teacher)/ 교사 대시보드 (데스크톱 전용)
│ └── api/ 모듈별 Route Handler
├── modules/ 핵심 로직. 담당자별로 하나씩 소유합니다
└── shared/ ui / styles / supabase / types — 공용
supabase/migrations/
규칙 두 개만 지켜주세요.
- 다른 모듈을 쓸 때는
index.ts를 통해서만 import 합니다. 내부 파일을 직접 가져오지 않습니다.
src/shared/와 supabase/migrations/는 김민경이 관리합니다. 수정이 필요하면 직접 고치지 말고 요청해주세요. 여기가 겹치면 전원이 멈춥니다.
역할 분담
프론트·백엔드를 가로로 나누지 않고 화면 단위로 세로로 나눴습니다. 각자 자기 화면의 UI와 API를 함께 소유하기 때문에 남의 작업을 기다릴 일이 거의 없습니다.
| 담당 | 모듈 | 맡은 것 |
|---|
| 강민구 | ai, reader | AI 프롬프트 4종(글쓰기 도우미·빈틈 분석·꼬리질문·채점), 장르 태그 정규화, 책잇 서재 리더와 단어 사전 |
| 김민경 | auth, teacher, shared | DB 스키마·RLS·API 계약, 구글 로그인, 반 코드, 교사 대시보드, PWA, 배포와 통합 |
| 이승환 | books | 알라딘·국립어린이청소년도서관·국립중앙도서관 API, 검색, 장르 인접 추천, 국회도서관 이동 |
| 박재경 | review, verification | 독후감 에디터와 자동저장, 빈틈 분석 화면, 타이머 질문 화면, 채점 결과와 재작성 |
| 문민재 | rewards, growth, ranking, guardian | 책갈피 원장, 열람권 교환, 스트릭, 책나무·도장판, 반 대항전, 챌린지, 보호자 공유 링크 |
김민경이 통합 책임자입니다. 코드 양은 가장 적은 대신 스키마와 API 계약을 쥐고 있고, 남의 PR을 붙이고 배포를 지키는 역할을 합니다. 심사 기간 내내 링크가 살아 있어야 하니 사실상 가장 중요한 자리입니다.
강민구와 박재경은 자주 붙어야 합니다. 서비스의 유일한 차별점이 이 두 사람 사이에서 나옵니다. 프롬프트가 바뀌면 화면도 바뀌고, 화면 제약이 프롬프트를 바꿉니다.
화면 목록
| # | 화면 | 담당 |
|---|
| 1 | 로그인 | 김민경 |
| 2 | 온보딩 — 역할 선택, 학년, 반 코드 입력 | 김민경 |
| 3 | 홈 — 인사, 검색, 추천 4권, 이어서 쓰기 | 이승환 |
| 4 | 국회도서관 이동 안내 (바텀시트) | 이승환 |
| 5 | 독후감 작성 — 글쓰기 도우미, 자동저장 | 박재경 |
| 6 | 빈틈 분석 결과 — 3곳 하이라이트 + 유형 라벨 | 박재경 |
| 7 | AI 꼬리질문 — 타이머, 문장 인용, 답변 입력 | 박재경 |
| 8 | 채점 결과 — 통과/재작성, 책갈피 획득 | 박재경 |
| 9 | 마이페이지 — 책갈피, 스트릭, 읽은 책, 반 순위 | 문민재 |
| 10 | 책갈피 교환 — 열람권, 알라딘 연결 | 문민재 |
| 11 | 나의 책나무 · 장르 도장판 | 문민재 |
| 12 | 챌린지 — 반 목표, 시즌 테마 | 문민재 |
| 13 | 책잇 서재 — 공개저작물 리더, 단어 사전 | 강민구 |
| 14 | 보호자 공유 링크 (읽기 전용) | 문민재 |
| 15 | 교사 대시보드 — 반 대항전, 학생별 현황 (데스크톱 전용) | 김민경 |
| 16 | 독서성향 리포트 | 문민재 |
교사 계정에 대해
학생과 교사가 같은 구글 로그인을 쓰되 profiles.role로 갈립니다.
- 교사가 반을 만들면 6자리 참여 코드가 발급됩니다
- 학생은 온보딩에서 그 코드를 입력해 반에 소속됩니다
- 학교·반 자유 입력은 쓰지 않습니다. 아무나 입력할 수 있으면 남의 반 아이들 점수가 보이게 됩니다
교사도 독후감 원문은 볼 수 없습니다. 점수, 통과 여부, 완독 수까지만입니다. 보호자에게도 마찬가지고요. 아이가 감시받는다고 느끼면 솔직하게 쓰지 않기 때문에, 이건 편의가 아니라 서비스의 전제입니다.
디자인
목업에서 뽑은 토큰은 docs/design-tokens.md에 있습니다. 요약하면 크림색 줄노트 배경(#FDF6EC)에 코랄(#FF6B4A)과 노랑(#FFD866)을 포인트로 쓰는 노트·플래너 톤입니다. 폰트는 Noto Sans KR.
검증 화면만 어둡습니다(#2B211B). 의도된 대비니까 다른 화면과 톤을 맞추려고 밝게 바꾸지 마세요. "지금 검사받는 중"이라는 신호입니다.
반응형은 768px에서 끊습니다. 그 아래는 하단 탭 5개(홈·독후감·챌린지·나·서재), 그 위는 왼쪽 아이콘 레일과 2단 배치입니다. 교사 대시보드는 데스크톱 전용이라 모바일 레이아웃을 만들지 않습니다.
말투는 아이에게 건네는 반말입니다. 포인트는 UI에서 항상 책갈피라고 부릅니다.
작업 규칙
- 브랜치:
feat/<모듈명>-<짧은설명>
- 커밋:
feat(verification): 타이머 추가 — 스코프는 모듈명으로
main 직접 푸시 금지, PR로만- PR은 Vercel 프리뷰 URL을 확인하고 머지
일정
| 일차 | 할 일 |
|---|
| 1일차 | 전원 모여 스키마·RLS·API 계약 확정, LLM 모델 결정. 김민경이 당일 안에 빈 엔드포인트까지 배포. 구글 로그인 리다이렉트 URL 3종 등록 |
| 2~3일차 | 목 데이터로 병렬 구현. 누구도 남의 API를 기다리지 않습니다. 강민구는 초등학생 수준 독후감 20건으로 채점 기준을 잡습니다 |
| 4일차 | 1차 통합. 여기서 안 붙는 기능은 잘라냅니다 |
| 5~6일차 | 2차 통합, 실연동, 버그 수정. 시연 시나리오 처음부터 끝까지 리허설 3회 |
| 7일차 | 배포 안정성 확인, 제출 |
1일차에 확정한 docs/spec.md를 각자 Claude Code 세션 첫 프롬프트에 통째로 넣고 시작하세요. 5명이 병렬로 짤 때 무너지는 지점은 속도가 아니라 합입니다.
잘라내는 순서
일정이 밀리면 이 순서로 뺍니다.
- 챌린지
- 독서성향 리포트
- 레벨·뱃지
- 책나무·도장판
- 장르 인접 추천 → 같은 태그 목록 수준으로 축소
검증 플로우(5~8번 화면), 책잇 서재, 교사 대시보드, 반 대항전은 마지막까지 남깁니다. 심사 점수가 걸린 곳입니다.
주의사항
- LLM은 절대 클라이언트에서 호출하지 않습니다. API 키는 서버 환경변수에만 둡니다
- RLS는 테이블을 만드는 마이그레이션에서 같이 켭니다. 나중에 켜면 이미 짠 쿼리가 전부 깨집니다
- 책갈피는 원장(ledger) 누적 합계로 계산합니다. 잔액 컬럼을 직접 수정하지 않습니다
- 포인트는 통과했을 때만 지급됩니다. 실패한 시도도 기록은 남기되 +0입니다
- 재작성 시에는 반드시 새 질문을 생성합니다. 같은 질문을 다시 주면 부정행위 방지가 무너집니다
- Supabase 무료 프로젝트는 7일간 요청이 없으면 일시정지됩니다.
.github/workflows/keepalive.yml 이 매일 09:00 KST 시연 로그인 → 서재 조회로 핑하고, 실패하면 GitHub 가 메일로 알립니다
npm run audit:prod — 프로덕션을 심사자 경로대로 훑습니다 (접속·시연 로그인·핵심 API·교사/학생 경계·보호자 응답에 본문 없음). 제출 직전과 심사 중 이상할 때npm run demo:reset — 데모 학생을 시드 상태로 되돌립니다 (미리보기). -- --write 로 실행. 심사 전에 테스트 흔적을 지울 때docs/spec.md에 없는 기능은 만들지 않습니다. 필요해 보이면 먼저 이야기해주세요
