직접 코딩 0% — CLAUDE CODE로 진짜 서비스 만들고 배포·운영까지

10장. Vercel 배포

명령어 한 줄로 전 세계 공개 — localhost에서 진짜 인터넷 주소로

직접 코딩 0%1 / 20

10.1 왜 Vercel인가

집 주방에서 — 거리의 가게로 (배포)

이유	의미
무료	개인 프로젝트는 무료 플랜으로 충분 — 카드 등록도 필요 없음
공개 URL	https://내서비스.vercel.app — 진짜 인터넷 주소. 내 컴퓨터를 꺼도 살아 있음
자동 배포	GitHub 금고와 연결하면, 푸시할 때마다 새 버전 자동 공개 — 9.5 자동화의 완성

내가 말하면 → Claude Code가 고치고 → 금고(GitHub)에 푸시되고 → Vercel이 가져가 전 세계 공개.
사람 손이 닿는 곳은 첫 칸뿐입니다.

NOTE — 더 쉬운 공개법(아티팩트 게시, 임시 공유)도 있지만, 이 책의 목표는 '보여주기'가 아니라 잃어버리지 않고, 고치고, 되돌리고, 운영하는 서비스의 주인이 되는 것 — 그래서 GitHub(금고)+Vercel(가게)입니다.

직접 코딩 0%10.1 왜 Vercel인가2 / 20

10장의 흐름

계획하고, 이사하고, 바깥세상에서 검증합니다

MOVE · 이사 준비와 구조 전환

10.1왜 Vercel인가

10.2계정과 GitHub 연결

10.3서버리스 전환·DB·환경 변수

DEPLOY · VERIFY · OPERATE

10.4맛집 챗봇과 비용 울타리

10.5자동 배포와 로그 기반 수정

10.6롤백·로그·다섯 고삐 점검

10.7공개 서비스의 주인으로

학습 리듬계획 → 변환 → 연결 → 배포 → 외부망 검증 → 운영 점검

직접 코딩 0%10장 · 목차3 / 20

10.2 Vercel 계정 만들기와 GitHub 연결

가게(Vercel)에게 금고(GitHub) 열람권을 줍니다

STEP 1

가입

vercel.com Sign Up →
Continue with Google
(GitHub 계정과 같은 방식)

→

STEP 2

Hobby 선택

개인용 무료 요금제
Team Name = GitHub
계정명 그대로

→

STEP 3

Authorize

"Vercel이 저장소에
접근해도 됩니까?" →
승인 (그림 10.4)

→

STEP 4

Install

Only select repositories
— 특정 저장소만 허용
(그림 10.5~10.6)

→

STEP 5

이메일 인증

Verify via email →
숫자 코드 입력 →
qa-board가 목록에 등장

전체 저장소(All)가 아니라 선택한 저장소만 접근을 허용하는 것 — 이것도 울타리(고삐 2)의 감각입니다.
화면이 책과 조금 달라도 과정은 유사 — 당황하지 말고 화면을 읽으며 진행하면 됩니다.

직접 코딩 0%10.2 계정·연결4 / 20

10.3.1 이사 갈 집은 구조가 다릅니다

상시 영업 가게 vs 호출형 주방 — 서버리스

항목	내 컴퓨터 (7~8장)	Vercel (서버리스)
서버	24시간 켜 둔다	요청이 올 때만 깨어난다
서버가 죽으면	PM2가 되살린다	죽음이라는 개념이 없다 — 다음 요청에 새로 깨어난다
데이터 저장	내 컴퓨터의 파일 (data 폴더)	파일이 남지 않는다 — 외부 데이터베이스 필요

요리사가 매번 사라지는 주방에는 장부를 둘 수 없습니다.
손님 명단(질문 데이터)은 주방 밖의 금고 — 데이터베이스 — 에. (0.6 준비물 표의 그 행입니다)

NOTE — PM2는 여기서 은퇴합니다. "죽으면 살리기"를 Vercel이라는 건물 자체가 해 주기 때문. 7.5의 안전벨트 원리는 그대로, 장치만 플랫폼 내장으로 — 배운 것이 사라지는 게 아니라 더 큰 구조에 흡수되는 것. (서버를 직접 빌려 운영하게 되면 PM2가 다시 진가를 발휘합니다)

직접 코딩 0%10.3.1 서버리스5 / 20

10.3.2 Plan 모드로 이사 계획 세우기

어디를 고쳐야 하는지 — 몰라도 됩니다

Plan 모드 프롬프트 (qa-board, Shift+Tab)

이 게시판을 Vercel에 배포하고 싶어.

알고 있는 것 — 서버리스라 파일(data 폴더) 저장 불가 · GitHub 저장소와 Vercel 계정은 준비됨
요청 — 무엇을 바꿔야 하는지 계획 · 무료 데이터베이스(Upstash Redis 등) 추천 · 7장의 통제 장치들(필터·도배 방지·검증·모니터링)이 배포 후에도 작동하는지 계획에 포함

Q1. 데이터+공유 상태를 어디에 저장? (그림 10.10)

› 1. Upstash Redis (추천) ← 선택

2. Vercel Postgres 3. Supabase

Q2. 실시간 갱신(SSE)은 서버리스에서 불가 (그림 10.11)

› 1. 폴링으로 전환 (추천) ← 선택

Review → Submit → "Ready to code?" (그림 10.13)

1. Yes, and use auto mode ← 승인

계획서에는 "왜 이 작업을 하는가"(파일 저장·SSE·메모리 카운터가 서버리스와 충돌)가 조목조목 — 다른 기술을 선택해도 개발은 가능하나 책과의 동기화를 위해 추천값을 따릅니다.

직접 코딩 0%10.3.2 Plan 모드6 / 20

10.3.2 작업 완료 보고

Claude Code가 건네준 "다음 단계" 5가지

## 다음 단계 (사용자가 직접 — Vercel 콘솔 작업)

1. GitHub qa-board에 푸시 (/저장 추천)

2. Vercel → Import qa-board

3. Storage → Upstash Redis 생성 → 프로젝트 연결

4. Environment Variables에 ANTHROPIC_API_KEY 추가

5. Deploy → 동작·로그 확인

▲ 폴링이 매 호출마다 Redis 1회 읽음(탭 1개 5초

≈ 720명령/시간) — 무료 한도 소비 주의 (그림 10.14)

수정은 끝났지만 아직 GitHub에 올리지 않음 — 9.5에서 만든 /저장으로 푸시 (그림 10.15)
GitHub에서 확인 — 파일이 바뀌었고, 수정 시간이 "now" (그림 10.16)
무료 계정 한도 귀띔 — 사용자가 몰리면 유료 전환 필요할 수 있음

직접 코딩 0%10.3.2 다음 단계7 / 20

10.3.2 Import → Deploy

Vercel에서 금고를 열어 — 가게를 엽니다

Import

대시보드 → Import Project
→ qa-board "Import"
(그림 10.9·10.17)

→

설정 확인

Preset: Express (자동)
값들은 살펴보기만 하고
수정 없이 (그림 10.18)

→

Deploy

빌드 로그가 올라가고
(그림 10.19)

→

완료

Congratulations!

익숙한 게시판 화면 →
Continue to Dashboard
(그림 10.20~10.21)

아직 끝이 아닙니다 — 이 게시판에는 장부(데이터베이스)와 열쇠(환경 변수)가 없습니다.
다음 두 페이지에서 채웁니다.

직접 코딩 0%10.3.2 Deploy8 / 20

10.3.2 다음 단계 3 — Storage

Upstash Redis — 주방 밖의 장부 금고 만들기

Storage

Vercel 왼쪽 메뉴 →
Create a Database →
Upstash for Redis "Create"

→

약관 동의

"Accept and Create"
(그림 10.23)

→

지역 선택

Tokyo 또는 Singapore
(집필 시점 한국 리전 없음)
(그림 10.24)

→

Free 플랜

월 500,000 명령
계정당 DB 1개
(그림 10.25)

→

Connect

qa-board 프로젝트 선택 →
"Connect" — 접속 정보
자동 주입 (그림 10.28)

연결하면 데이터베이스 접속 열쇠(KV_URL 등)가 qa-board의 환경 변수에 자동으로 등록됩니다.
Storage 화면에서 생성한 DB가 qa-board에 연결된 것을 확인할 수 있습니다. (그림 10.29)

직접 코딩 0%10.3.2 Upstash 연결9 / 20

10.3.3 비밀번호는 이사 짐에 없습니다

Vercel의 전용 금고 — 환경 변수

왜 필요한가

.env는 9장에서 금고 반입 금지 목록에 넣어 GitHub에 없습니다. 그럼 Vercel은 열쇠를 어디서 받을까요?

Vercel의 Environment Variables — 여기 등록하면 주방이 깨어날 때마다 이 금고에서 열쇠를 꺼내 씁니다. 코드에도, GitHub에도 비밀이 없는 구조 — 7.8의 "비밀은 금고에만" 원칙이 클라우드까지.

등록 절차 (그림 10.30~10.35)

① 프로젝트 선택 → Settings → Environments
② Production 선택 → Environment Variables
③ "Add Environment Variable" — Key: ANTHROPIC_API_KEY, Value: sk-ant-… → Save
④ "Redeploy" — 새 정보로 서비스 재시작

(Upstash 열쇠들은 9페이지에서 이미 자동 등록됨)

직접 코딩 0%10.3.3 환경 변수10 / 20

10.3.4 배포 — 그리고 인터넷과 LTE/5G의 순간

와이파이를 끄세요 — 그것이 진짜 확인입니다

Domains qa-board-kohl.vercel.app

Status ● Ready Created 1h ago (그림 10.36)

같은 와이파이는 "우리 집 안" — LTE/5G는 바깥세상
스마트폰(와이파이 OFF)으로 Domains 주소 접속 → 질문 등록 → 관리자 답변 → AI 답변까지 (그림 10.38~10.39)
QR 공유 — 프로젝트 화면 "Visit" 옆 화살표 → QR 코드 캡처 → 친구에게 전송 (그림 10.40)

다시 침착하게 — 확인 4종

☐ 확인 1 — LTE/5G로 접속되는가 (와이파이 꺼짐 확인)
☐ 확인 2 — 폰에서 등록한 질문이 컴퓨터에서도 보이는가 (= DB 작동 증거)
☐ 확인 3 — 컴퓨터를 종료해도 접속되는가
☐ 확인 4 — 7.2의 욕설 필터가 배포된 서비스에서도 작동하는가 (파괴 테스트는 어디서나)

TIP — 배포 실패 시 부록 A.2("Vercel 빌드 에러"·"데이터 저장 안 됨"·"AI 답변만 실패"). 동시 접속 가능 인원은 구조·DB·Vercel 한도에 따라 다름 — 실제 행사 전 여러 기기로 미리 시험하세요.

직접 코딩 0%10.3.4 LTE/5G 확인11 / 20

10.4 [실습] 맛집 추천 챗봇 배포

같은 길 — 그러나 두 가지가 더 무겁습니다

① 환경 변수 = 내 지갑의 열쇠

food-chatbot에는 Claude API Key + 네이버 키 2종이 들어갑니다. 질문 하나하나가 API 호출이고, API 호출은 과금(7.8) — 사용자들이 쓸수록 내 지갑에서 비용이 나갑니다.

② 도배 방지 = 생존 조건

내 컴퓨터에선 서비스를 지키는 울타리였지만, 전 세계 공개 후 누군가 질문을 수천 번 보내면 — 서비스가 아니라 내 크레딧이 녹습니다. Plan 모드 계획에 방어 요청이 반드시 포함되어야 합니다.

①

검문
(.gitignore)

→

②

비공개 푸시
(9장 프롬프트 재사용)

→

③

Plan 모드
서버리스 전환+제한

→

④

환경 변수
API Key + 네이버 2종

→

⑤

배포
(Redeploy)

→

⑥

LTE/5G 확인

"처음 사용한다"고 프롬프트에 적어도 걱정 없음 — 연결이 준비돼 있으면 Claude Code가 기존 연결을 사용합니다.

직접 코딩 0%10.4 두 가지 추가 주의12 / 20

10.4 Plan 모드 — 지갑을 지키는 두 가지 결정

하루 상한과 도배 식별 기준을 함께 정합니다

Q. 하루 전체 질문 수 상한? (그림 10.42)

› 1. 300건/일 (Recommended) — 보수적

2. 1,000건/일 — 지인 공유 계획이면

3. 100건/일 — 배포 직후 테스트용

# 초과 시 "오늘은 마감되었습니다"

추천값을 그대로 확정하지 말고 — 낮게 시작해 실사용을 보며 올리는 것도 좋은 전략.

Q. 같은 사용자를 무엇으로 식별? (그림 10.43)

› 1. IP 주소 (Recommended) — 우회 어려움

2. IP + 세션 조합 — 더 정밀

3. 세션 ID — 새로 만들면 우회 (권장 안 함)

# reviewer가 "세션은 우회 쉬움"이라 지적했던 부분

어떤 방법도 한 사람을 완벽히 식별하진 못함 — 카운터는 실행 공간이 아니라 공유 DB에 저장(동시 요청 중복 계산 방지 포함)을 요청.

완료 보고 — "서버리스 전환 + 로컬 실측 검증(비용 0) + GitHub 푸시 완료. Upstash 연동·키 입력은 회원님 인증이 필요해 제가 대신 못 합니다." → 이후 Import → Storage(새 DB 권장 — qa-board와 공유 시 이름 충돌 방지 작업 필요) → 환경 변수 3종 → Redeploy.

직접 코딩 0%10.4 상한·식별 결정13 / 20

10.4 ⑥ LTE/5G 확인

5G 화면 속 "맛집 박사" — 그리고 확인 3종

# 스마트폰 · 5G (그림 10.52)

🍜 맛집 박사 — 위치·취향 기반 맛집 추천

나> 안국역 부근에서 맛있는 소금빵이 먹고 싶어

봇> 소금빵 사랑하시는군요 🍜 안국역 근처는

베이커리 카페가 많은 동네라 잘 고르셨어요!

혼자 조용히? 여러 명이서? …

food-chatbot-seven.vercel.app

다시 침착하게 — 확인 3종

☐ 확인 1 — LTE/5G 질문 시 배포된 서버가 네이버 API를 실제 호출해 가게 이름·주소·출처를 표시하는가
☐ 확인 2 — 연속 질문을 빠르게 보내면 차단되는가
☐ 확인 3 — GitHub 저장소에 .env가 없고, 코드에 키가 직접 적혀 있지 않은가 (검문 재확인)

이 챗봇은 Claude API로 답변을 만들고, 네이버 지역 검색에서 실제 가게 정보를 근거로 추천합니다 — 8.3의 구조가 클라우드에서도 그대로.

직접 코딩 0%10.4 배포 확인14 / 20

10.5 수정하고, GitHub에 올리면

이 장에서 가장 마법 같은 실습

# 스마트폰으로 배포된 화면을 열어 둔 채, 컴퓨터에서:

> 대화창 맨 위의 "맛집 박사" 옆에 "since 2026"이라는 문구를 작게 추가해줘.

사람

말한다

한국어로 수정 방향 지시

→

Claude Code

고친다

수정 + 테스트 + 검문

→

GitHub

세이브

금고에 푸시 (9.5 규칙)

→

Vercel

새 단장

감지 → 자동 배포 → Ready

→

스마트폰

새로고침

"since 2026" 등장

코드를 직접 쓰지 않았지만 — 테스트 결과, GitHub 업로드 내용, 배포 성공 여부의 판단과 승인은 사람이 맡았습니다.
그리고 이 고리의 모든 길목에 우리가 채운 고삐(검문·세이브 포인트·롤백·로그)가 있습니다.

직접 코딩 0%10.5 자동 배포의 완성15 / 20

10.5 오류 수정 — 자동 배포의 진짜 위력

500 에러 — 로그를 건네주면 됩니다

배포된 챗봇이 죽었다 (그림 10.55)

500: INTERNAL_SERVER_ERROR
Code: FUNCTION_INVOCATION_FAILED
— 서버 안에서 문제 발생. 우리는 코드를 본 적도 없는데?

에러 번호만 주면 Claude Code가 이런저런 시도로 토큰과 시간을 허비할 수 있습니다. 조금 더 수고하면 — Vercel Logs 화면에서 빨간 글자를 클릭 → 상세 메시지 확보 (그림 10.57)

> 다음과 같은 에러가 발생한다.

500: INTERNAL_SERVER_ERROR / FUNCTION_INVOCATION_FAILED

에러를 찾아보니: Invalid export found in module

"/var/task/server.js" … (그림 10.58)

● 수정해서 푸시했습니다. GitHub 연동 프로젝트는

푸시하면 Vercel이 자동으로 새 배포를 시작하니,

이번엔 그 500 에러가 사라져야 합니다. (그림 10.59)

문장의 의미는 몰라도 됩니다 — Claude Code에게는 결정적 단서. 수정 후에는 같은 기능 재실행 + 로그·화면 직접 확인.

주의 — 오류 로그를 전달하기 전, API 키·비밀번호·사용자 질문·이메일 같은 민감 정보가 없는지 확인하고 민감한 값은 ***로 가린 뒤 전달하세요.

직접 코딩 0%10.5 500 에러 해결16 / 20

10.6 배포 후 통제 체계 작동 확인

집이 바뀌었으니 — 고삐 전수 점검

고삐	내 컴퓨터에서 (7~8장)	Vercel에서 (지금)
1 규칙	CLAUDE.md, Skill.md → 코드에 반영	코드에 반영된 그대로 작동
2 울타리	욕설 필터, 도배 방지	작동 — 단 도배 방지는 DB 기반으로 진화 (10.3~10.4)
3 검증	자동 테스트, reviewer	그대로 — 배포 전 reviewer 검토를 거치면 더 좋음
4 안전벨트	PM2 + Git 세이브 포인트	PM2 은퇴 → Vercel 내장 + 롤백 버튼
5 CCTV	대시보드, 로그, 작업 기록 훅	기존 대시보드 + Vercel 로그·통계

표에 새 얼굴이 둘 — 롤백(클라우드의 시간 여행)과 Vercel 로그(건물 출입구의 CCTV). 다음 페이지에서 직접 확인합니다.

직접 코딩 0%10.6 고삐 재점검 표17 / 20

10.6 새 얼굴 둘 — 직접 확인

롤백과 Vercel 로그

롤백 — 클라우드의 시간 여행 (그림 10.60~10.61)

Deployments 메뉴 = 배포 기록이 시간순으로 — 각 항목이 9장의 세이브 포인트. 문제가 생기면 이전 Ready 배포에서 롤백(Instant Rollback 등) 실행.

단, 롤백은 코드 버전만 — DB에 저장된 질문·환경 변수·외부 데이터까지 과거로 가진 않음. 데이터 구조 변경 후엔 이전 코드와 현재 데이터의 호환 확인 필요. (오래된 배포는 보관 정책에 따라 삭제될 수 있음)

Vercel 로그 — 출입구의 CCTV (그림 10.62)

Logs 메뉴 — 어떤 요청이 왔고 어떤 오류가 났는지. 배포 직후엔 텅 비어 있다가, 친구가 폰으로 접속하는 순간 줄이 하나 올라옵니다.

7.6의 대시보드가 "서비스 내용"의 CCTV라면, Vercel 로그는 "건물 출입구"의 CCTV. 빨간 글자가 보이면 — 침착하게 복사해서 Claude Code에게(민감 정보 가리기).

다시 침착하게 — 확인 3종

☐ 일부러 망가뜨린 배포를 롤백으로 복구해 봤는가 · ☐ 스마트폰 접속이 로그에 실시간으로 찍히는가 · ☐ 관리자 대시보드가 로그인한 관리자에게만 열리고, 암호는 환경 변수에 있으며, 오입력 반복 시 차단되는가 (7.6 NOTE — 이제 정말 중요)

직접 코딩 0%10.6 롤백 · 로그18 / 20

10.7 이 장에서 달라진 것들

localhost가 사라지고, 진짜 주소가 생겼습니다

데이터는 내 컴퓨터의 파일에서 외부 데이터베이스(Upstash Redis)로 이사
PM2는 은퇴 — 죽으면 살리기는 플랫폼 내장, 문제 버전은 롤백으로 복귀
수정에서 반영까지 — 말하기 → 고치기 → 푸시 → 자동 배포의 전 과정이 자동
2장의 마지막 벽이 무너졌습니다 — 내 컴퓨터를 꺼도 접속되는 서비스

서비스는 완성되었습니다. 하지만 공개된 서비스의 주인에게는 새로운 일이 생깁니다 —
지갑을 지키고, 비밀을 지키고, 서비스가 자라는 것을 지켜보는 일.

직접 코딩 0%10.7 정리19 / 20

10장 마무리

코드를 쓰는 사람이 아니라 — AI에게 일을 시키고 통제하는 사람.
그 사람의 서비스가 지금, 전 세계에서 돌아가고 있습니다.
이것이 이 책이 처음부터 약속했던 그림입니다.

NEXT · 11장. 운영 — 공개된 서비스의 주인이 되는 법

전 세계가 접속한다는 것은, 모르는 사람도 들어온다는 뜻 —
비용 알림과 지출 한도, 비밀 관리, 성장 관찰. "주인의 일"을 배우고, 이 책을 졸업합니다.

직접 코딩 0%20 / 20