부록 F · 제로부터 배포까지 — 계정·키 발급 & Claude Code로 서비스 만들기

부록 실습노트 — 제로부터 배포까지: 계정·키 발급 & Claude Code로 서비스 만들기 이 문서 하나만 순서대로 따라 하면, 계정이 하나도 없는 상태에서 시작해 GitHub·Vercel·OpenAI·Supabase 계정과 키를 만들고, Claude Code로 코드를 생성해 실제 인터넷 주소로 배포까지 끝낼 수 있습니다. Hans17 Academy와 동일한 스택(Next.js 16 + TypeScript + Tailwind 4 · Vercel · Supabase · OpenAI 임베딩 · Claude · ElevenLabs)을 그대로 씁니다.

화면 명칭·메뉴 위치는 2025~2026년 기준입니다. 각 서비스가 UI를 자주 바꾸므로, 버튼 이름이 조금 다르면 비슷한 뜻의 항목을 찾으세요. 요금이 발생할 수 있는 지점에는 매번 경고를 달았습니다. 확실치 않아 원문 그대로 확인이 필요한 부분은 "(확인)"으로 표시했습니다.

0. 준비물과 전체 그림

먼저 최종적으로 우리가 채워 넣을 .env.local 키 목록을 머리에 그려두면 길을 잃지 않습니다. 아래 키들이 이 실습의 "목표 수집물"입니다. 각 섹션이 하나씩 발급해 채워 줍니다.

# .env.local  (프로젝트 루트, git에 올리지 않음 — .gitignore에 포함)

# Claude (강사/에이전트 두뇌)
ANTHROPIC_API_KEY=sk-ant-...

# OpenAI (임베딩 전용: text-embedding-3-small)
OPENAI_API_KEY=sk-...

# Supabase (DB + 인증키 3종)
NEXT_PUBLIC_SUPABASE_URL=https://xxxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...        # 공개 가능(브라우저 노출 OK)
SUPABASE_SERVICE_ROLE_KEY=eyJ...            # 절대 공개 금지(서버 전용)

# ElevenLabs (음성 TTS/STT — 음성 기능 쓸 때만)
ELEVENLABS_API_KEY=...

# Vercel Blob (파일 업로드 저장 — 쓸 때만, 보통 Vercel이 자동 주입)
BLOB_READ_WRITE_TOKEN=vercel_blob_rw_...

준비물: 이메일 계정 하나, 휴대폰(문자 인증용), 신용/체크카드 1장(OpenAI 크레딧 결제 시 필요할 수 있음 — 소액), 그리고 Mac 또는 Windows PC.

용어 3개만 기억하세요.

레포지토리(repo): 코드가 담기는 GitHub의 저장소. "프로젝트 폴더의 온라인 백업 + 협업 공간"입니다.
환경변수(env): 코드에 직접 안 적고 따로 넣는 비밀값(키). 로컬은 .env.local, 배포 서버는 Vercel 대시보드에 넣습니다.
배포(deploy): 내 코드가 인터넷 주소(https://…)로 실제 동작하게 올리는 것.

1. GitHub — 계정 생성·레포 생성·토큰 발급

GitHub는 코드 저장소이자, Vercel이 코드를 가져가는 출발점입니다. 여기 레포가 있어야 Vercel이 "이 코드 배포해줘"를 할 수 있습니다.

1-1. 회원가입 → 이메일 인증

브라우저에서 https://github.com 접속 → 우측 상단 Sign up 클릭.
Email(실제 받을 수 있는 주소), Password(강력하게), Username(영문 소문자·숫자·하이픈, 나중에 URL에 노출됨 예: github.com/내아이디) 순서로 입력.
사람 확인(퍼즐/캡차)을 통과합니다. 사이트가 요구하는 퍼즐은 본인이 직접 풉니다.
입력한 이메일로 8자리 인증 코드(launch code) 가 옵니다. 코드를 입력하면 계정이 활성화됩니다. → 이메일 인증을 끝내지 않으면 레포 생성·푸시가 막히니 반드시 완료.
요금 플랜은 Free로 충분합니다(공개·비공개 레포 무제한).

1-2. 새 레포지토리 생성 (New repository)

로그인 후 좌측 상단 초록색 New 버튼(또는 우측 상단 + → New repository) 클릭.
항목 입력:
- Repository name: 예 my-ai-agent (소문자·하이픈 권장).
- Description: 선택. "나의 첫 AI 에이전트" 등.
- Public / Private: 학습용이면 Private 추천(코드가 남에게 안 보임). Vercel 무료 플랜은 Private도 배포 가능.
- Add a README file: 체크하면 빈 레포가 아니라 파일 1개가 생겨 편함. (Claude Code로 로컬에서 시작할 거면 체크 안 해도 됨.)
- Add .gitignore: 템플릿에서 Node 선택 → node_modules, .env* 등이 자동 제외됨. 중요: 이게 있어야 .env.local(비밀키)이 실수로 업로드되지 않습니다.
Create repository 클릭. 생성된 주소는 https://github.com/내아이디/my-ai-agent.

주의: 절대 .env.local을 커밋하지 마세요. .gitignore에 .env*가 들어 있는지 반드시 확인. 키가 공개 레포에 올라가면 자동 스캐너가 몇 분 내 도용합니다.

1-3. Personal Access Token 발급 (범위: repo)

Claude Code나 로컬 git이 GitHub에 코드를 올릴 때 비밀번호 대신 토큰으로 인증합니다.

우측 상단 프로필 사진 → Settings.
좌측 맨 아래 Developer settings 클릭.
Personal access tokens → 두 종류가 있습니다.
- Tokens (classic): 간단. 범위 체크박스로 권한 지정.
- Fine-grained tokens: 레포별 세밀 권한(권장·최신). 특정 레포에만 권한 부여 가능.
초보자용 classic 기준:
- Generate new token (classic) 클릭.
- Note(용도 메모): claude-code-push 처럼 알아볼 이름.
- Expiration(만료): 90일 권장(무기한은 보안상 비추천).
- Select scopes에서 repo 전체 체크 (Private 레포 push·pull 전 권한). 이것만 있으면 코드 올리기·내리기 충분.
- 맨 아래 Generate token.
화면에 뜨는 ghp_... 토큰을 즉시 복사해 안전한 곳에 저장. → 이 화면을 벗어나면 다시 볼 수 없습니다. 잃어버리면 새로 발급.

용도: 로컬에서 git push 시 GitHub가 아이디/비밀번호를 물으면, 비밀번호 자리에 이 토큰을 붙여넣습니다(비밀번호로는 push 불가). Vercel이 GitHub와 연동될 때는 이 토큰이 아니라 GitHub 앱 권한(OAuth)을 쓰므로 토큰이 없어도 됩니다 — 즉 Vercel 연동만 할 거면 토큰은 없어도 되고, Claude Code가 터미널에서 직접 push하게 할 때 유용합니다.

2. Vercel — 계정·프로젝트·배포·환경변수·Blob·Supabase 통합

Vercel은 Next.js를 만든 회사의 배포 플랫폼입니다. GitHub 레포를 연결하면 git push만 해도 자동 배포됩니다.

2-1. GitHub로 로그인

https://vercel.com → Sign Up.
Continue with GitHub 선택(이게 핵심 — GitHub와 바로 연결됨). GitHub 인증 화면에서 Authorize Vercel.
개인 학습용이면 팀 유형은 Hobby(무료) 선택. 무료로 배포·커스텀 도메인·환경변수 다 됩니다.

2-2. 프로젝트 Import & 배포

대시보드에서 Add New… → Project.
Import Git Repository 목록에서 1장에서 만든 레포(my-ai-agent)를 찾아 Import. 목록에 없으면 Adjust GitHub App Permissions(또는 "Configure GitHub App")로 그 레포 접근 권한을 Vercel에 부여.
설정 화면:
- Framework Preset: Next.js로 자동 감지됨.
- Root Directory: 레포 루트에 코드가 있으면 그대로.
- Build & Output Settings: 기본값 유지(Next.js는 자동). Hans17처럼 커스텀 빌드 커맨드가 있다면 여기서 지정.
- Environment Variables: 지금 넣어도 되고 나중에 넣어도 됨(다음 항목).
Deploy 클릭 → 1~3분 빌드 후 https://my-ai-agent.vercel.app 같은 주소가 생깁니다. 처음엔 코드가 비어 있어도 빈 페이지가 뜨면 성공.

2-3. 환경변수 넣기 (가장 중요)

로컬 .env.local의 키들을 똑같이 Vercel에도 넣어야 배포본이 동작합니다(로컬 파일은 서버에 안 올라감).

프로젝트 → 상단 Settings 탭 → 좌측 Environment Variables.
각 키를 Key / Value 쌍으로 추가. 예: Key ANTHROPIC_API_KEY, Value sk-ant-....
적용 환경 선택: Production / Preview / Development — 보통 셋 다 체크.
NEXT_PUBLIC_로 시작하는 키는 브라우저에 노출되어도 되는 값(예: Supabase anon key, Supabase URL)이고, 접두어 없는 키(SUPABASE_SERVICE_ROLE_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY)는 서버 전용 비밀입니다. 이 규칙은 Next.js가 강제합니다 — NEXT_PUBLIC_이 없으면 브라우저 코드에서 읽을 수 없습니다.
값을 추가/변경한 뒤에는 재배포해야 반영됩니다: Deployments 탭 → 최신 배포 우측 ⋯ → Redeploy.

팁: vercel env pull 명령으로 Vercel에 넣은 값을 로컬 .env.local로 내려받을 수 있고, 반대로 Vercel CLI로 올릴 수도 있습니다. Claude Code가 이 동기화를 도와줄 수 있습니다(5장).

2-4. Blob 토큰 — BLOB_READ_WRITE_TOKEN

Vercel Blob은 이미지·오디오 같은 파일을 저장하는 스토리지입니다(음성 파일 저장 등에 사용).

프로젝트 → Storage 탭 → Create Database(또는 Connect Store) → Blob 선택 → 이름 짓고 생성.
생성 후 Connect to Project를 하면 Vercel이 BLOB_READ_WRITE_TOKEN을 환경변수로 자동 주입합니다(직접 복붙 안 해도 됨).
로컬에서도 쓰려면 vercel env pull로 이 토큰을 .env.local에 내려받습니다.

용도: 코드에서 @vercel/blob 패키지로 파일 업로드 시 이 토큰으로 인증. 파일 기능을 안 쓰면 생략 가능.

2-5. Marketplace에서 Supabase 통합 (선택)

Supabase를 4장처럼 직접 만들어도 되고, Vercel Marketplace로 연결하면 환경변수를 자동으로 꽂아줘 더 편합니다.

프로젝트 → Storage 또는 상단 Integrations(팀 대시보드 → Integrations → Browse Marketplace).
Supabase 선택 → Add Integration → 프로젝트 선택.
새 Supabase 프로젝트를 만들거나 기존 것을 연결하면, Vercel이 NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY 등을 자동으로 환경변수에 추가합니다.
이 방식을 쓰면 4장의 키 복붙 과정을 건너뛸 수 있습니다. (단, 키가 무엇인지 이해하려면 4장을 읽어 두세요.)

2-6. Deployment Protection (배포 보호)

배포한 주소를 아무나 못 보게 막는 기능. 개발 중 미완성 화면 노출을 막습니다.

프로젝트 → Settings → Deployment Protection.
Vercel Authentication: 켜면 Vercel 로그인한 사람만 접근(팀 내부 검토용). Preview 배포에 특히 유용.
일반 사용자에게 공개할 서비스라면 Production은 보호 해제(Disabled)로 두어야 방문자가 로그인 없이 접속합니다. → 라이브 서비스인데 접속이 막혀 있다면 이 설정을 먼저 확인.
Password Protection(유료 플랜): 비밀번호 아는 사람만 접근. 소규모 비공개 데모에 적합.

3. OpenAI — 계정·API 키 (임베딩 전용)

우리 스택에서 OpenAI는 오직 임베딩(text-embedding-3-small, 1536차원)에만 씁니다. 강의노트 텍스트를 숫자 벡터로 바꿔 RAG 검색에 쓰는 용도입니다. 대화 생성은 Claude가 담당하므로 GPT 대화 모델은 필요 없습니다.

3-1. 계정 생성

https://platform.openai.com 접속 → Sign up(구글/이메일 가입 가능).
휴대폰 번호 인증(SMS 코드)이 요구될 수 있습니다.
로그인하면 개발자용 Platform 대시보드가 나옵니다(챗봇 화면 chatgpt.com과 다름 — 반드시 platform.openai.com).

3-2. 결제/크레딧 설정

임베딩 API는 유료입니다(다만 매우 저렴 — text-embedding-3-small은 100만 토큰당 수 센트 수준(확인)). 사용하려면 크레딧 충전이 필요합니다.

좌측/우측 상단 Settings(톱니) → Billing.
Add payment details로 카드 등록 → Add credits로 소액(예 $5) 선충전. → 크레딧 없이 키만 있으면 호출이 429/quota 오류로 실패합니다.
(권장) Usage limits에서 월 상한(hard limit)을 낮게 걸어 과금 사고 방지.

카드번호·결제정보는 본인이 직접 OpenAI 사이트에 입력하세요. 저(조교)는 결제정보를 대신 입력하지 않습니다.

3-3. API 키 발급 → OPENAI_API_KEY

좌측 메뉴 API keys(또는 Settings → API keys).
Create new secret key 클릭.
Name: hans17-embedding 등 용도 메모. Project 선택(기본 프로젝트 OK). 권한은 기본(All) 또는 임베딩만 필요하면 제한 가능.
생성된 sk-... 키를 즉시 복사. → 이후 다시 볼 수 없음. 잃으면 재발급.
.env.local에 넣기:
```
OPENAI_API_KEY=sk-...
```
Vercel에도 동일하게 OPENAI_API_KEY 추가(2-3 참고).

용도 요약: 코드의 임베딩 생성 스크립트(예 npm run embed)가 이 키로 OpenAI를 호출해 content/*.md를 벡터로 만들어 embeddings.json에 저장 → 런타임에 코사인 유사도로 관련 문단을 찾음(벡터DB 불필요).

4. Supabase — 계정·프로젝트·API 키·테이블·RLS

Supabase는 PostgreSQL 데이터베이스 + 인증 + 스토리지를 얹은 백엔드입니다. 대화 로그·FAQ·수집 데이터 저장에 씁니다.

4-1. 계정 & New project

https://supabase.com → Start your project → Continue with GitHub 로그인.
New organization(팀 이름·플랜=Free) 생성 → New project.
항목:
- Name: my-ai-agent.
- Database Password: 강력하게 설정하고 따로 저장(DB 직접접속·마이그레이션에 필요, 분실 시 재설정).
- Region: 사용자와 가까운 곳(한국이면 Northeast Asia (Seoul/Tokyo) 권장 — 지연 감소).
- Plan: Free.
Create new project → 1~2분 프로비저닝.

4-2. API 키 3종 확보 → .env.local

프로젝트 생성 후 좌측 하단 Settings(톱니) → API(또는 Project Settings → API / API Keys)로 이동:

Project URL → NEXT_PUBLIC_SUPABASE_URL (https://xxxx.supabase.co)
anon public 키 → NEXT_PUBLIC_SUPABASE_ANON_KEY (브라우저 노출 OK, RLS로 보호되는 공개 키)
service_role 키 → SUPABASE_SERVICE_ROLE_KEY (RLS를 우회하는 관리자 키 — 절대 클라이언트/공개 레포에 노출 금지, 서버 코드에서만)

NEXT_PUBLIC_SUPABASE_URL=https://xxxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOi...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOi...

참고: Supabase가 2025년 들어 키 체계를 새로운 publishable / secret 키로 개편 중입니다(확인). 화면에 anon/service_role 대신 publishable/secret으로 보이면, publishable ≈ anon(공개), secret ≈ service_role(비밀)로 대응해 같은 환경변수에 넣으면 됩니다. Vercel Marketplace 통합(2-5)을 쓰면 이 값들이 자동 주입됩니다.

Vercel 대시보드에도 위 3개를 동일하게 추가(2-3).

4-3. 테이블 만들기

두 가지 방법:

Table Editor(좌측 메뉴) → New table → 이름·컬럼 지정(GUI). 예: chat_logs (id, created_at, question text, answer text, ...).
SQL Editor(좌측 메뉴) → SQL 직접 실행:
```
create table chat_logs (
  id bigint generated always as identity primary key,
  created_at timestamptz default now(),
  question text,
  answer text
);
```
Claude Code에게 "이런 테이블 만들어줘"라고 하면 이 SQL을 대신 작성/실행(MCP 연결 시)해 줍니다(5장).

4-4. RLS (Row Level Security) — 반드시 이해

RLS는 "행 단위 접근 제어"입니다. anon 키로 오는 요청은 RLS 정책이 허용한 행만 접근합니다.

새 테이블은 기본적으로 RLS가 켜져 있고 정책이 없어 anon 키로는 아무것도 못 읽/씁니다(안전한 기본값).

공개적으로 읽기만 허용하려면 정책 추가:

alter table chat_logs enable row level security;
create policy "public read" on chat_logs
  for select using (true);

쓰기(insert)는 service_role 키를 쓰는 서버 코드로만 하는 게 안전합니다. service_role 키는 RLS를 우회하므로, 서버(예: Next.js API 라우트)에서만 이 키로 저장하세요. → 그래서 클라이언트엔 anon, 서버 저장엔 service_role로 역할을 나눕니다.
경고: service_role 키가 브라우저 번들이나 GitHub에 노출되면 DB 전체가 무방비가 됩니다. NEXT_PUBLIC_ 접두어를 절대 붙이지 마세요.

5. Claude Code — 가입 & 위 서비스 연결·셋팅

5-1. Claude Code란

Claude Code는 터미널에서 동작하는 AI 코딩 에이전트입니다. 자연어로 "이런 기능 만들어줘"라고 하면 파일을 직접 읽고/쓰고, 명령을 실행하고, git 커밋·배포까지 수행합니다. 앞 장에서 모은 키들을 이 도구가 코드에 연결해 줍니다.

5-2. 가입 & 설치

Claude 계정: https://claude.ai 가입. Claude Code 사용에는 유료 플랜(Pro/Max) 또는 Anthropic Console의 API 크레딧이 필요합니다(확인 — 플랜별 제공 범위는 공식 문서에서 확인).
설치(Node.js 18+ 필요):
```
npm install -g @anthropic-ai/claude-code
```
또는 공식 안내의 설치 스크립트 사용.
프로젝트 폴더에서 실행:
```
cd my-ai-agent
claude
```
최초 실행 시 브라우저로 로그인/인증을 진행합니다(계정 연결). 안내에 따라 승인.

5-3. .env.local에 키 모으기

프로젝트 루트에 .env.local을 만들고 1~4장에서 모은 키를 전부 넣습니다(0장의 목록 참고). Claude Code에게 이렇게 시켜도 됩니다:

"루트에 .env.local 만들고 이 키들 넣어줘. 그리고 .gitignore에 .env* 있는지 확인해줘."

Claude Code는 키 값 자체를 코드에 하드코딩하지 않고 process.env.KEY로 참조하도록 작성합니다. 값은 여러분이 붙여넣습니다.

5-4. MCP로 Supabase / Vercel 연결

MCP(Model Context Protocol)는 Claude Code가 외부 서비스를 "도구"로 직접 다루게 해주는 연결 규격입니다. 연결하면 Claude가 브라우저 없이 DB에 테이블을 만들거나 배포 상태를 조회할 수 있습니다.

Supabase MCP: 연결하면 Claude Code가 SQL 실행, 테이블/마이그레이션 생성, 로그 조회를 직접 수행. 등록 예:
```
claude mcp add supabase --scope project -- npx -y @supabase/mcp-server-supabase@latest
```
(연결에는 Supabase 액세스 토큰/프로젝트 ref가 필요할 수 있음 — 안내에 따라 입력. 정확한 패키지명·인자는 Supabase 공식 MCP 문서에서 확인.)
Vercel MCP: 배포 목록·빌드 로그·환경변수·배포 보호를 Claude가 조회·조작. Vercel의 MCP 서버/커넥터를 등록하고 OAuth로 인증(확인 — 최신 등록 방식은 Vercel 문서 확인). 인증은 대화형 세션에서 /mcp 또는 커넥터 설정으로 진행합니다.
연결된 MCP는 세션 안에서 /mcp로 상태를 확인할 수 있습니다.

주의: MCP 인증(OAuth)은 대화형(interactive) 세션에서만 됩니다. 처음엔 브라우저로 권한 승인 창이 뜹니다 — 본인이 직접 승인.

5-5. CLAUDE.md — 프로젝트 규칙 메모

루트에 CLAUDE.md를 두면 Claude Code가 매번 자동으로 읽는 프로젝트 설명서가 됩니다. 스택·명령어·규칙을 적어두면 헛짓을 줄입니다. 예:

# My AI Agent — 컨텍스트
- 스택: Next.js 16 + TS + Tailwind 4, Vercel 배포, Supabase, OpenAI 임베딩, Claude.
- 로컬 실행: `npm run dev`. 임베딩 재생성: `npm run embed`.
- 배포: `vercel --prod`.
- 규칙: 비밀키는 .env.local에만. service_role 키는 서버 코드에서만 사용.

/init 명령을 쓰면 Claude Code가 코드베이스를 훑어 CLAUDE.md 초안을 만들어 줍니다.

5-6. 권한/설정

Claude Code는 파일 수정·명령 실행 전에 권한을 물어봅니다. 안전한 명령은 "허용"으로, 위험한 명령(삭제 등)은 매번 확인.
자주 쓰는 안전한 명령은 .claude/settings.json의 allowlist에 넣어 확인 프롬프트를 줄일 수 있습니다.
비밀키·설정 파일은 신뢰할 수 있는 본인 지시로만 변경하세요.

6. Claude Code와 연결된 상태에서 서비스 만드는 법

이제 실전 루프입니다. 자연어 요구 → 코드 생성 → 로컬 검증 → 브라우저 확인 → 커밋 → 배포를 반복합니다.

6-1. 기본 루프

요구를 자연어로: 예)

"질문을 입력하면 Claude가 답하고, 질문·답변을 Supabase chat_logs에 저장하는 채팅 페이지를 만들어줘. 답변 생성은 서버 API 라우트에서 ANTHROPIC_API_KEY로 호출하고, 저장은 service_role 키로 서버에서만 해줘."
코드 생성: Claude Code가 app/에 페이지·API 라우트, 필요한 패키지 설치(npm install)까지 수행. 진행 중 권한을 물으면 확인.
로컬 검증:
```
npm run dev
```
http://localhost:3000이 뜹니다. 에러가 나면 그 로그를 그대로 Claude에게 붙여넣고 "이 에러 고쳐줘".
브라우저 확인: 실제로 질문을 넣어 답이 오는지, Supabase Table Editor에 행이 쌓이는지 눈으로 확인.
커밋:

"지금까지 변경 커밋해줘. 메시지는 'feat: 채팅+로그 저장'." Claude가 git add/commit을 수행(비밀키 파일은 .gitignore로 제외됨).
배포:
```
vercel --prod
```
또는 GitHub에 push하면 Vercel이 자동 배포. 배포 후 .vercel.app 주소에서 최종 확인. → 로컬은 되는데 배포본이 안 되면 99%가 Vercel 환경변수 누락(2-3). 그 키를 추가하고 Redeploy.

6-2. 프롬프트 팁

역할과 제약을 함께: "무엇을" 뿐 아니라 "어디서(서버/클라이언트), 어떤 키로, 어떤 제약으로"를 명시. 예: "service_role 키는 클라이언트에 노출하지 말고 API 라우트에서만."
작게 쪼개기: 한 번에 거대한 기능 대신 "먼저 채팅 UI만 → 다음에 저장 → 다음에 RAG" 순서로. 검증 지점이 잦을수록 디버깅이 쉽습니다.
에러는 원문 그대로: 터미널·브라우저 콘솔 에러를 통째로 붙여넣으세요. 요약하지 말고.
검증을 시켜라: "npm run dev로 띄워서 실제로 동작하는지 확인하고, 안 되면 고칠 때까지 반복해줘."
되돌리기: 마음에 안 들면 "방금 변경 되돌려줘(git으로)". 그래서 자주 커밋하는 게 안전망.
비용 주의: 임베딩 재생성(npm run embed)은 OpenAI 과금이 있으니 콘텐츠가 바뀐 뒤에만.

6-3. RAG 파이프라인을 붙일 때 (이 스택의 핵심 흐름)

답변에 참고시킬 지식 문서를 content/*.md로 작성.
npm run embed — OpenAI text-embedding-3-small로 각 문단을 벡터화해 embeddings.json 생성.
사용자의 질문도 같은 모델로 임베딩 → 코사인 유사도로 가장 가까운 문단 몇 개를 뽑음(벡터DB 없이 인메모리 계산).
뽑힌 문단을 Claude 프롬프트에 컨텍스트로 넣어 답변 생성. "주어진 근거에 없으면 모른다고 답하라"는 지시로 환각을 차단.
배포 시 content/*.md와 embeddings.json을 함께 커밋해야 서버에서 같은 답을 냅니다.

7. 서비스 기획에 필요한 것 — Hans17 서비스의 특장점 요약

좋은 AI 서비스는 "모델이 좋아서"가 아니라 문제·사용자·차별화가 뾰족해서 좋습니다. 기획 뼈대와, Hans17 서비스가 그 뼈대를 어떻게 채웠는지(그리고 왜 좋은지)를 나란히 봅니다.

7-1. 기획 3요소

문제 정의: 누구의 어떤 불편을, 지금은 어떻게(불편하게) 해결하나? — 한 문장으로.
사용자: 대상이 구체적일수록 기능이 선명해집니다("여행자" 대신 "혼자 처음 일본 밤거리를 다니는 20~30대 한국인").
차별화: 남들과 다른 한 가지. 기술이 아니라 사용자가 체감하는 결과로 표현.

7-2. Hans17의 실제 특장점 — "왜 좋은가"로

벡터DB 없는 하이브리드 코사인 RAG — 별도 벡터 데이터베이스(Pinecone 등)를 두지 않고 임베딩을 파일로 갖고 인메모리 코사인 + 키워드를 섞어 검색합니다. 왜 좋은가: 인프라가 1개 줄어 배포·운영·비용이 단순해지고, 강의 규모의 데이터에선 지연도 짧습니다. 키워드를 섞어 고유명사·숫자 같은 "의미 임베딩이 놓치는 것"까지 잡아 정확도가 올라갑니다.
환각 차단 — "근거 문단에 없으면 지어내지 말고 모른다고 답하라"를 구조로 강제합니다. 왜 좋은가: 교육·상담처럼 틀린 답의 대가가 큰 도메인에서 신뢰를 지킵니다. 그럴듯한 거짓말보다 "모른다"가 더 안전합니다.
웹검색 + 리플렉션(2차 자기검증) — Anthropic 서버사이드 웹검색으로 최신 정보를 가져온 뒤, 답을 한 번 더 스스로 검토(reflection)합니다. 왜 좋은가: 지식 컷오프 이후의 최신성 문제를 메우고, 2차 검증으로 초안의 오류·과장을 걸러 품질을 끌어올립니다.
클론 음성 TTS/STT — ElevenLabs로 복원한 실제 목소리로 답을 읽어주고(TTS), 사용자의 말을 받아씁니다(STT). 왜 좋은가: 텍스트만인 봇 대비 정체성·몰입·접근성(화면 못 보는 상황, 이동 중)이 확 올라가 서비스가 기억에 남습니다.
GPS + 날씨 + 기념일 컨텍스트 — 위치(역지오코딩), 실시간 날씨, 그 나라의 공휴일을 자동으로 읽어 답에 반영합니다. 왜 좋은가: 같은 질문이라도 "지금·여기·오늘"에 맞는 답을 주므로 조언이 실제로 쓸모 있어집니다(비 오면 실내 추천, 축일이면 붐빔 경고).
현지어 자동 전환 — 사용자가 위치한 나라의 언어로 서비스 전체가 동작합니다. 왜 좋은가: 여행지에서 언어 장벽을 없애 "번역 앱 따로 켜기"를 없앱니다 — 하나의 흐름 안에서 통역·말걸기까지 이어집니다.
대화세트 사전 추론 — 상황별 대화 시나리오(단계·상대 관점 추론 포함)를 미리 설계해 둡니다. 왜 좋은가: 실시간 생성만 의존할 때의 들쭉날쭉함을 없애고, 검증된 흐름으로 첫 마디부터 자연스럽게 이어가게 합니다.
DB 누적 심층분석 — 수집·분석 결과를 Supabase에 계속 쌓습니다. 왜 좋은가: 쓸수록 데이터가 축적되어 분석이 깊어지고, 개인화·재방문 가치가 커지는 복리형 자산이 됩니다.

7-3. 관통하는 원칙 — "사이트가 곧 교재"

Hans17 Academy는 강의에서 가르친 기술 선택(RAG·환각차단·리플렉션 등)을 사이트 코드가 그대로 구현합니다. 여러분의 서비스도 "설명한 대로 실제로 동작하는가"를 기준으로 만들면, 데모가 곧 신뢰가 됩니다.

7-4. 기획 → 이 문서로 실행하는 순서(요약)

문제·사용자·차별화 한 문장씩 정의(7-1).
GitHub 레포(1장) → Vercel 배포 뼈대(2장).
필요한 키만 발급: 대화=Claude, 검색용 벡터화=OpenAI(3장), 저장=Supabase(4장), 음성=ElevenLabs(선택).
Claude Code 연결(5장)로 자연어 개발 루프(6장) 시작.
작게 배포하고 실제 사용자에게 보여주며 차별화 한 가지를 계속 날카롭게.

마지막 점검: 배포본이 동작하려면 (a) Vercel 환경변수에 모든 키가 있고, (b) service_role 같은 비밀키가 GitHub에 노출되지 않았고, (c) Supabase RLS 정책이 의도대로 설정됐는지 — 이 셋을 항상 확인하세요.