책메이트 개발일지 1일차 — 기획에서 Walking Skeleton까지

포트폴리오
개발일지
책메이트
AI 기반 한국어 도서 추천 서비스 MVP. 오늘 하루 API 검증·아키텍처 확정·온보딩 구현·Claude 연동까지 끝냈다.
Published

2026.04.17

오늘 한 것

오늘은 기획 단계에서 실제로 돌아가는 Walking Skeleton까지 한 번에 가는 날이었다. 예상보다 훨씬 많은 것이 해결됐다.

1. 데이터 소스 확정

국립중앙도서관 ISBN API — BOOK_SUMMARY_URL 포기

API 인증키를 발급받아 실제 호출해봤다. BOOK_SUMMARY_URL / BOOK_INTRODUCTION_URL / BOOK_TB_CNT_URL 세 필드 모두 대부분의 책에서 빈값이었다. 채식주의자(한강, ISBN 9788936433598) 같은 유명작도 마찬가지였다. RAG 소스로 쓰기엔 신뢰도가 너무 낮아서 포기를 결정했다. 부수적으로 발견한 것: requests 기본 헤더는 서버에서 차단되니 User-Agent를 크롬으로 설정해야 호출이 된다.

도서관 정보나루 — 메인 데이터 소스로 확정

recommandList API가 ISBN 입력 → 함께 대출된 책 최대 200건을 바로 반환해줘서 협업 필터링을 직접 구현할 필요가 없어졌다. srchDtlList API의 <description> 필드(CDATA 텍스트 인라인)가 실제 책 소개를 제공하는 것도 확인했다. RAG 벡터 DB 소스를 여기서 가져오기로 결정.

usageAnalysisList는 대출 횟수, 핵심 키워드, 함께 대출된 책까지 주는데 현재 MVP에서는 description/keywords 추가를 v2 백로그로 미뤘다. KDC 파라미터 체계도 실제 호출로 검증하면서 재설계했다 — 처음엔 kdc='813'으로 넣었더니 0건이 나왔고, 실제로는 kdc='8'(대주제) + dtl_kdc='81'(세부주제) + 응답 후처리 필터 class_no_prefix='813' 구조여야 했다. 문서 기반 설계의 한계를 확실히 느꼈다.

2. 아키텍처 확정

정보나루 recommandList → 협업 필터링 대체 (후보 풀)
정보나루 srchDtlList description → RAG 벡터 DB 소스
알라딘 API → 표지 이미지·판매가 실시간 조회 전용 (저장 불가)
Claude API → 후보 풀 + 대화 컨텍스트 기반 자연어 추천

협업 필터링 직접 구현은 아예 사라졌다. 덕분에 ML 구현 부담 없이 데이터-AI 파이프라인에 집중할 수 있게 됐다.

3. 주요 설계 결정 (DECISION LOG)

오늘 내린 결정들을 트렐로 DECISION LOG 리스트에 카드로 기록했다.

  • 서비스명 chaekmate 확정 — 책 + mate. 한국어 색이 살아있고 GitHub 검색 결과 동일 이름 활성 프로젝트 없음.
  • MVP 범위: 문학(소설/에세이/시/인문교양) 중심 — 정보나루 대출 데이터가 문학에 가장 풍부하고 RAG description 품질도 여기가 높다.
  • 프론트엔드: Streamlit — Gradio(멀티스텝 어색)·Next.js(학습 비용 MVP 초과) 검토 후 채택. 온보딩 3단계 + 챗 인터페이스 모두 네이티브 지원.
  • Walking Skeleton 방식 — 추천 엔진 없이 온보딩 end-to-end를 먼저 완성하는 전략. 포트폴리오 데모는 ’실제로 돌아가는 것’이 핵심이라 판단.
  • 온보딩 4단계 평점 — ❤️ 좋았어요 / 👎 별로였어요 / ✨ 끌려요 / ⏭️ 안 끌려요. 미독 호감도가 콜드스타트 해결에 가장 강력한 시그널.
  • 분위기 태그 Step 제거 — 정보나루 API에 분위기 필드가 없고 LLM 자동 추출은 MVP 비용 초과. 사용자 평가 책의 keywords 가중합으로 대체.
  • 3-tier 대표 도서 선정 — Tier A(최근 1년 상위 3권) + Tier B(최근 3년 상위 4권) + Tier C(정규화 점수 상위 2권). Popularity Bias를 막기 위한 설계.
  • 표지 이미지 fixed height container — st.image() → HTML img 태그 + height: 260px, object-fit:contain 으로 그리드 정렬 해결.

4. 구현 완료된 것들

트렐로 DONE 리스트 확인 + GitHub chaekmate 레포 구조:

chaekmate/
├── app.py              # Streamlit 메인 앱 (온보딩 3단계 + 챗 인터페이스)
├── requirements.txt
├── src/
│   ├── library_api.py  # 도서관 정보나루 API 래퍼
│   ├── claude_client.py # Claude API 연동
│   ├── recommender.py  # 추천 로직 (recommandList 기반)
│   ├── genres.py       # 장르/KDC 데이터
│   └── seed_books.py   # 시드 데이터 수집
└── scripts/
    └── run_seed_books.py

Streamlit 앱에서 장르 선택 → 도서 평가 → Claude 대화 추천 흐름이 end-to-end로 동작하는 상태다.

현재 진행 중 (DOING)

  • [데이터] 책 데이터 수집 파이프라인 구축 (500~1000권)
  • [AI] RAG 구성 — 책 소개 텍스트 벡터 DB 구축

내일 할 것

  • 데이터 수집 파이프라인 완성 + 문학 장르 500~1000권 로컬 확보
  • 벡터 DB 선택 (ChromaDB vs Pinecone vs Qdrant) 및 임베딩 파이프라인 설계
  • RAG 결과를 Claude 컨텍스트에 붙이는 로직 구현

레포: sigolyori/chaekmate · 트렐로: 📚 책 추천 AI 서비스 포트폴리오