CloneCV

데모는 로그인 없이 볼 수 있습니다. @kimdev는 코드에 넣어 둔 가상의 프론트엔드 개발자 "김개발" 이고, 실제 사용자 데이터는 노출되지 않습니다.

---

프로젝트 개요

기간	2026.07 ~ 2026.09 (진행 중)
인원	1인 개발 — 기획 · 설계 · 프론트엔드 · 백엔드 · DB · 배포
개발 방식	요구사항 → 기능 명세 → 아키텍처 문서를 먼저 쓰고, AI 페어 프로그래밍(Cursor → Claude Code)으로 구현
주요 기술	Next.js 16 · React 19 · TypeScript · Supabase(Postgres, RLS, pgvector) · Gemini · Upstash Redis
규모	기능 명세 F-01 ~ F-33 · DB 마이그레이션 26개 · 단위 테스트 213개 · Playwright E2E 4종
운영 비용	Gemini · Upstash · Supabase 무료 티어 안에서 운영

왜 만들었나

PDF 이력서는 끝까지 읽히기 어렵고, 웹 포트폴리오는 정적이라 "이 사람한테 직접 물어보고 싶은 것" 을 확인할 방법이 없습니다. CloneCV는 이력서에 있는 사실만 근거로 1인칭으로 답하는 AI를 붙여, 면접관의 경험을 읽기 → 대화로 바꾸는 실험입니다. 핵심 과제는 "그럴듯하게 말하는 챗봇"이 아니라 이력서에 없는 말을 지어내지 않는 챗봇을 만드는 것이었습니다.

---

핵심 기능

면접관(방문자) — 로그인 없이 /@슬러그

• 웹 이력서 열람(데스크톱 섹션 내비게이션, 모바일 대응) + 포트폴리오 이미지 · PDF · 영상
• AI 채팅 — 스트리밍 답변, 이력서에 근거가 있는 추천 질문 3개, 답하기 어려우면 직접 문의 폼
• 카카오톡 · X · 링크 공유

지원자(소유자)

• 이력서 빌더 — 10개 섹션 순서 변경·on/off, 자동 저장, PDF 가져오기(Gemini 추출) · PDF 내보내기
• 발행 — 시스템 프롬프트 조립, 답변 가능 질문 계산, RAG 색인을 한 번에
• 대시보드 — 대화 로그, 조회 통계, 답변하지 못한 질문, 모의 면접, AI 사용량 게이지
• 디자인 커스텀 — 테마 프리셋 5종, 색상 · 글꼴 · 카드 스타일, 실제 공개 화면으로 실시간 미리보기
• 계정당 프로필 최대 3개, 관리자 신고 · 모더레이션

지원자(소유자) 입장

1. 회원가입 & 슬러그 설정 — /@my-name 형태의 고유 주소
2. 이력서 빌더 (/dashboard/edit) — 10개 섹션, 사이드바에서 순서 변경·섹션 on/off
   • 기본 정보, 경력, 학력, 자격·어학·수상, 경험/활동/교육, 기술 스택, 프로젝트, 포트폴리오, 자기소개서, 예상 질문 답변
   • 프로필 사진: 드래그앤드롭 업로드 + 3:4 크롭 편집 (5MB 이하)
   • 포트폴리오: 최대 8개 항목, 이미지(3MB)·PDF(8MB)·YouTube/Vimeo 링크
   • 기술 스택: 태그 입력, 프로젝트별 기술 스택도 자유 입력
   • 외부 링크: GitHub·블로그 등 이름+URL을 자유롭게 추가 (고정 필드 없음)
   • blur·30초 간격 자동 저장, 완성도 카드, PDF 가져오기(Gemini 추출), 공개 화면 미리보기
3. 발행 — 시스템 프롬프트 생성 후 published 상태로 전환
4. 대시보드 (/dashboard)
   • 상단 고정 바 — 공개 주소, 링크 복사, 공개/비공개 토글
   • 한눈에 보기 — 완성도 %, AI 답변 준비율, 최근 대화 3건, 답변 실패 알림
   • 디자인 — 공개 프로필 테마 편집 (아래 참고)
   • 대화 로그 — 방문자가 무엇을 물었는지 확인
   • 통계 — 조회수, 세션 수, 7일 추이, 답변하지 못한 질문
   • 받은 질문 — AI가 답하지 못한 문의 이메일
   • 모의 면접 — 면접관 모드로 답변 연습
   • 챗봇이 답하기 어려운 영역 — 비어 있는 이력서 항목 때문에 못 하는 답변을 짚어 주고 해당 빌더 단계로 이동
   • AI 사용량 — 오늘 Gemini 호출 수, 최근 30일 토큰, 남은 한도 게이지
   • 대화/통계에서 FAQ 원클릭 저장
   • 프로필 삭제 — 슬러그를 다시 입력해야 실행, 업로드한 파일까지 정리
5. 디자인 커스텀 (/dashboard 디자인 탭)
   • 테마 프리셋 5종(모던 슬레이트 · 다크 디벨로퍼 · 웜 미니멀 · 크리에이티브 볼드 · 이그제큐티브 클래식)
   • 포인트 색상, 글꼴 3종, 프로필 사진 모양, 카드 스타일, 헤더 여백
   • 전체 화면 편집 — 실제 공개 화면을 그대로 띄운 채 수정, 데스크톱/모바일 토글
   • 바꾸는 즉시 미리보기에 반영(서버 요청 없음), 저장해야 방문자에게 적용

면접관(방문자) 입장

1. /@슬러그 접속 — 로그인 없음
2. 히어로 → 이력서 본문 순으로 열람, 데스크톱은 우측 섹션 내비게이션으로 이동
3. 포트폴리오 섹션에서 이미지·PDF·영상 확인
4. 우하단 버튼으로 AI 채팅 창 열기 — 스트리밍 답변, 이력서에 근거가 있는 추천 질문 3개, 답변이 어려울 때 직접 문의 폼
   • 데스크톱에서는 좌상단 모서리 드래그로 창 크기 조절, 헤더 버튼으로 확대/축소
5. 카카오톡·X·링크 복사로 공유

예시 프로필 @kimdev

• 코드에 박아 둔 가상 데이터(김개발, 프론트엔드 3년차)
• DB·조회수·신고와 무관, 랜딩 예시 보기 전용
• 실제 사용자 이력서가 노출되지 않음

---

아키텍처

flowchart LR
  V["면접관<br/>/@slug"] --> PX
  O["지원자<br/>/dashboard"] --> PX

  subgraph VC["Vercel · Next.js 16 App Router"]
    PX["proxy.ts<br/>/@slug → /[id] rewrite<br/>세션 갱신 · 관리자 확인"]
    RSC["Server Components<br/>공개 프로필 · 대시보드"]
    API["Route Handlers<br/>/api/chat · /api/prompt/generate<br/>/api/resume/import-pdf · export-pdf"]
  end

  PX --> RSC
  PX --> API

  subgraph SB["Supabase"]
    AUTH["Auth<br/>이메일 · Google OAuth"]
    DB[("Postgres + RLS<br/>pgvector")]
    ST["Storage<br/>사진 · 포트폴리오"]
  end

  RSC --> DB
  API --> AUTH
  API --> DB
  API --> ST
  API --> GM["Google Gemini<br/>채팅 스트리밍 · PDF 추출 · 임베딩"]
  API --> RD["Upstash Redis<br/>레이트리밋"]

발행 시점에 무거운 일을 끝내 둡니다. 소유자가 발행하면 /api/prompt/generate가 한 번에 처리합니다.

1. 이력서 · FAQ · 자기소개서를 템플릿으로 조합해 시스템 프롬프트를 만듭니다. LLM이 이력서를 다시 쓰지 않습니다.
2. 이력서로 답할 수 있는 질문 목록(coverage) 을 계산해 system_prompts.coverage(jsonb)에 저장합니다.
3. 이력서를 청크로 나눠 gemini-embedding-001(768차원)로 pgvector 색인을 만듭니다.

덕분에 채팅 요청 경로에서는 추가 계산이나 DB 조회 없이 저장된 결과만 읽습니다.

채팅 한 턴의 흐름 (lib/chat/handle-chat-request.ts)

sequenceDiagram
  autonumber
  participant B as 방문자 브라우저
  participant C as /api/chat
  participant R as Upstash
  participant D as Supabase
  participant G as Gemini

  B->>C: 질문 (500자 이하)
  C->>R: 레이트리밋 (분당 5 · 일 50)
  C->>D: 시스템 프롬프트 + coverage, FAQ, RAG 청크 병렬 조회
  Note over C: FAQ와 맞으면 준비된 답변 블록 주입<br/>아니면 관련 청크 focus 블록 (플래그 on일 때)
  C->>G: 스트리밍 생성 (실패 시 다음 모델로 폴백)
  G-->>B: SSE로 토큰 전달
  Note over C: 민감정보 필터 → 거절 답변인지 판정
  alt 답변 성공
    C->>G: 꼬리질문 생성
    Note over C: coverage로 검증하고<br/>부족하면 답변 가능한 질문으로 채움
  else 거절
    C-->>B: 직접 문의 폼 제안 (2차 호출 생략)
  end
  C->>D: chat_messages 기록 (answer_status · 모델 · 토큰)
  C-->>B: 다음 추천 질문 3개

• 1인칭 존댓말, 지원동기·STAR·경력기술 질문 유형별 답변 가이드
• 이력서에 없는 내용은 지어내지 않음 → 모를 때 정해진 문구 + 직접 문의 유도
• 전화번호·정확한 생년은 채팅에서 비공개 (나이대만), 이력서 패널 표시는 소유자가 토글
• FAQ 우선 응답 — 등록한 예상 질문은 키워드 + 임베딩 의미 매칭(유사도 0.72)으로 준비된 답변을 그대로 재서술
• 근거 있는 질문만 추천 — 프로젝트 트러블슈팅이 비어 있으면 "가장 어려웠던 문제" 질문 자체가 나오지 않음
• RAG 검색 주입은 RAG_RETRIEVAL_ENABLED 플래그로 제어 (기본 off = 전체 컨텍스트 방식, 색인은 항상 수행)
• 모델 폴백 — 기본 모델이 쿼터/404로 실패하면 GEMINI_MODELS 체인의 다음 모델로 재시도
• 레이트리밋 — 방문자 분당 5회·일 50회, 소유자 분당 10회·일 200회
• 질문 500자 제한, 히스토리는 최근 10턴까지만 전달
• 시스템 프롬프트 원문은 클라이언트에 노출하지 않고, 프롬프트 인젝션·역할 탈출 요청에 응하지 않음

인사말은 짧게 고정되어 있습니다.

안녕하세요, {이름}의 AI 챗봇입니다! 궁금하신 점이 있으시면 편하게 물어보세요.

---

This is the beginning of the README. Read the rest at the original. Read the full README ↗