바이브코딩 · 6회차 핸즈온 워크북

내 사이트에 AI 심장 달기
— Gemini와 비밀의 방

시간 약 75분
준비물 5회차에 만든 GitHub·Vercel 계정, 안티그래비티, 구글 계정
만들 것 AI 미니앱 한 가지 (다섯 중 택1)
오늘의 약속. 새로운 기능 0개. 오늘은 “AI 키 발급 → 비밀의 방 → 호출 → 배포” 이 한 바퀴를 손에 익을 때까지 천천히 돌리는 게 전부입니다. 외울 필요 없어요. 이 책을 옆에 두세요.

0큰 그림 — 여섯 번째 친구를 만납니다 5분

지난 시간 우리는 다섯 친구를 만났습니다 — 안티그래비티, 노드제이에스, 깃, 깃허브, 버셀. 오늘은 여섯 번째 친구를 만납니다. Gemini API. 우리 사이트에 “말 걸면 답해주는 심장”을 달아주는 친구예요.

식당 주문 비유

오늘 우리는 식당에 주문을 합니다. 줄여서 API(에이피아이)라고 불러요.

Gemini, OpenAI, 카카오 지도, 네이버 검색, 날씨… 세상의 모든 API가 이 네 가지 구조를 똑같이 따릅니다.

오늘 가장 중요한 한 줄. 우리는 API 키를 코드에 박지 않습니다. .env라는 비밀의 방을 만들고, 깃허브에는 절대 올라가지 않게 합니다.

1충격 모먼트 — 내 코드는 사실 공개되어 있다 10분

본격적으로 시작하기 전에, 한 가지 사실을 짚고 갑니다. 지난주에 우리가 한 git push가 사실 무엇이었는지.

1-1. 내 깃허브 저장소를 열어보기3분
  1. 브라우저에서 github.com/내아이디로 가기
  2. 지난주에 만든 저장소(repository) 클릭
  3. 코드 파일들을 하나씩 클릭해서 열어보기
내가 안티그래비티에서 짠 코드가 그대로 다 보이면 OK. 친구한테 주소를 알려주면 친구도 똑같이 다 볼 수 있어요.
그러니까. 만약 우리가 코드에 “비밀번호”나 “API 키”를 적어두면, 그 비밀번호도 깃허브에 그대로 올라가고, 모두에게 공개됩니다. 검색엔진도 가져가고, 키를 훔쳐서 내 quota를 다 써버리는 사람도 생겨요.

그래서 우리는 오늘 두 가지를 함께 합니다.

2스타터 받기 — 강사 저장소 복제 5분

오늘은 빠르게 같은 출발선에 서기 위해, 강사가 미리 준비한 “반제품 스타터”를 다 함께 받아 갑니다. UI는 다 만들어져 있고, Gemini를 부르는 한 자리만 비어 있어요. 그 한 자리를 안티그래비티에게 부탁해서 채우는 게 오늘의 핵심입니다.

2-1. “Use this template” 으로 내 저장소 만들기2분
  1. 다음 주소로 이동: github.com/Gloria3513/ai-mini-app-starter
  2. 오른쪽 위 초록색 “Use this template” 버튼 → Create a new repository
  3. 저장소 이름을 짧게 (예: my-first-ai-app)
  4. Public인지 확인하고 → Create repository
fork 와 다른 점. Use this template은 깨끗한 새 저장소를 만들어줍니다. 강사 저장소와 연결돼 있지 않아서, 자유롭게 푸시할 수 있어요.
2-2. 안티그래비티에서 클론하기3분
  1. 방금 만든 내 저장소 페이지에서 초록 Code 버튼 → HTTPS 주소 복사
  2. 안티그래비티 실행 → 시작 화면의 Clone Repository 클릭
  3. 주소 붙여넣기 → 저장할 폴더 선택 (바탕화면이나 Documents)
  4. 잠깐 기다리면 자동으로 폴더가 열립니다
왼쪽 사이드바에 app/, lib/, README.md가 보이면 OK.
  • “이 폴더 작성자를 신뢰합니까?” → Yes, I trust the authors 클릭 (우리가 만든 저장소예요)
  • Clone Repository 메뉴가 안 보이면 → File → Open Folder로 다운로드한 폴더 열기

3Gemini API 키 받기 10분

식당 멤버십 카드 비유

API 키는 식당 멤버십 카드와 비슷합니다. 식당(Gemini)에 들어갈 때 “저 이 카드 손님이에요”라고 보여주는 거예요. 카드가 없으면 주문을 받아주지 않습니다. 카드를 잃어버리면(공개되면) 다른 사람이 내 카드로 마구 주문하니, 조심해야 해요.

3-1. Google AI Studio 접속2분
  1. 브라우저에서 aistudio.google.com 접속
  2. 본인 구글 계정으로 로그인
  3. 이용약관에 동의
안심하세요. 카드 등록 필요 없습니다. 무료 할당량이 충분히 큽니다 (수업에 쓰기엔 충분).
3-2. 키 만들기3분
  1. 왼쪽 메뉴에서 “Get API key” 클릭
  2. “Create API key” 버튼 → 잠깐 기다리면 키가 생성됩니다
  3. 생성된 키(AIzaSy...로 시작) 옆 복사 아이콘 클릭
  4. 안티그래비티 메모장이나 별도 메모장에 잠시 붙여둡니다
이 키 절대 누구한테도 보여주지 마세요. 카톡, 슬랙, 스크린샷, 화면 공유 모두 위험합니다. 실수로 보였다면 즉시 AI Studio에서 그 키를 “삭제”하고 새로 만들면 됩니다.

4비밀의 방 만들기 — .env + .gitignore 15분

오늘의 두 번째 중요한 한 줄. 비밀을 만들기 전에, 비밀을 숨길 자리부터 만듭니다. 순서를 거꾸로 하면 비밀이 깃 기록에 한 번 박혀서 영원히 남습니다.
4-1. .gitignore가 이미 잘 되어 있는지 확인3분

이 스타터는 .gitignore 파일이 이미 들어 있어요. 우리는 그저 잘 들어 있는지 확인만 합니다.

  1. 안티그래비티 왼쪽 사이드바에서 .gitignore 파일 클릭
  2. 파일 안에 .env* 라는 줄이 있는지 눈으로 확인
이 한 줄의 뜻. “.env로 시작하는 모든 파일은 깃이 무시하라” 입니다. 그래서 .env 안에 비밀을 적어둬도 깃허브에 절대 안 올라가요.
4-2. .env 파일 만들기5분

스타터에 .env.example이라는 “예시 파일”이 있어요. 우리는 이걸 복제해서 진짜 .env를 만듭니다.

.env.example 파일을 같은 폴더에 .env 라는 이름으로 복제해줘.
복제만 하고, 안의 내용은 아직 손대지 마.

안티그래비티가 새 파일을 만들면, 사이드바에 .env가 생깁니다.

사이드바에 .env.example(원본)과 .env(복제본) 두 개가 보이면 OK.
4-3. .env 파일에 내 키 붙여넣기3분
  1. 사이드바에서 .env 클릭해서 열기
  2. 다음과 같이 적혀 있는 줄을 찾습니다:
GEMINI_API_KEY=여기에_본인_키를_붙여넣으세요

→ 여기에_본인_키를_붙여넣으세요 자리에 3-2에서 복사한 키를 붙여넣고 저장(⌘S 또는 Ctrl+S).

예시 (이건 가짜 키예요):

GEMINI_API_KEY=AIzaSyAbCdEfGhIjKlMnOpQrStUvWxYz1234567
4-4. 깃이 진짜로 무시하는지 눈으로 확인4분

안티그래비티 AI에게 부탁해봅니다.

지금 git status 를 실행해서 결과를 보여줘.
.env 파일이 변경 목록에 보이는지 안 보이는지 알려줘.
결과 화면에 .env가 안 보이면 성공. (깃이 진짜로 무시하고 있다는 뜻) .env.example은 보여도 OK — 그건 예시 파일이라 같이 올라가야 해요.
  • 혹시 .env가 변경 목록에 떴다면 → .gitignore에 .env*가 있는지 다시 확인
  • 그래도 떴다면 AI에게: 왜 .env가 git status에 보이는지 한국어로 알려줘

5AI에게 부탁해서 “호출 코드” 짜기 15분

이제 오늘의 가장 중요한 단계입니다. 스타터에서 딱 한 자리만 비어 있어요 — Gemini를 부르는 함수. 이걸 안티그래비티가 대신 채워주게 합니다.

전화기 비유 — 패키지가 뭐예요?

Gemini와 대화하려면 “정해진 형식의 편지”를 인터넷으로 보내야 합니다. 주소도 외워야 하고, 봉투 모양도 맞춰야 하고, 한 글자라도 틀리면 거절당해요.

그래서 구글이 “전화기”를 만들어줬어요. 이름이 @google/generative-ai입니다. 우리는 그 전화기에 대고 “이거 보내줘”라고만 말하면, 봉투·주소·형식을 전화기가 알아서 챙겨서 보냅니다.

그래서 우리는 전화기를 먼저 깔고, 그 전화기로 부탁합니다. 깐다는 행위가 npm install이에요.

5-1. 전화기 깔기 — 패키지 설치3분

안티그래비티 AI 채팅창에 그대로 부탁하세요.

이 프로젝트에 @google/generative-ai 패키지를 설치해줘.
설치 명령은 직접 치지 말고, 네가 터미널에서 대신 실행해줘.
끝나면 잘 깔렸는지 알려줘.
터미널에 added 1 package 같은 줄이 뜨고, package.json 파일의 dependencies 안에 @google/generative-ai가 보이면 OK.
패키지가 뭔지 한 줄로. “누가 미리 잘 짜둔 코드 묶음을 빌려쓰는 것”이에요. 우리가 처음부터 다 짜지 않고, 잘 만들어진 도구를 받아서 씁니다.
5-2. 호출 코드 자리 찾기2분
  1. 사이드바에서 app 폴더 펼치기
  2. 그 안의 api → gemini → route.ts 클릭
  3. 가운데 화면에 큰 TODO 주석 블록이 보입니다 — 거기가 우리가 채울 자리예요
파일 안에 // TODO — 여기에 Gemini API 호출 코드를 작성하세요 비슷한 줄이 보이면 OK.
5-3. 안티그래비티에게 한 번에 부탁하기7분

route.ts 파일을 연 상태에서 AI 채팅창에 이 문장을 그대로 붙여넣으세요.

이 route.ts 파일의 TODO 자리를 채워줘.
prompt 변수의 내용을 @google/generative-ai 의 gemini-2.0-flash 모델로 보내고,
답변 텍스트만 { text: '...' } JSON 형태로 NextResponse.json 으로 돌려줘.
API 키는 process.env.GEMINI_API_KEY 에서 읽어줘.
키가 없거나 호출이 실패하면 500 상태와 에러 메시지를 돌려줘.

안티그래비티가 변경안을 보여줍니다. 살펴보고 Apply 또는 Accept를 누르세요.

파일 위쪽에 import { GoogleGenerativeAI } from "@google/generative-ai";가 생기고, TODO 주석이 사라지면 OK.
  • AI가 다른 모델 이름(gemini-pro 등)을 씀 → 채팅에 한마디: 모델은 정확히 gemini-2.0-flash로 해줘
  • AI가 키를 코드에 직접 박음 → 키는 절대 코드에 박지 말고 process.env.GEMINI_API_KEY에서 읽어줘
  • Apply 후에도 빨간 줄이 보임 → 이 파일에서 빨간 줄이 보이는데 무엇이 문제인지 알려줘
5-4. 로컬에서 작동 확인3분
이제 dev 서버를 실행해줘 (npm run dev).
브라우저에서 어떤 주소를 열어야 하는지 알려줘.
  1. 터미널에 Local: http://localhost:3000 비슷한 줄이 뜨면 켜진 거예요
  2. 그 주소를 ⌘+클릭(또는 Ctrl+클릭)으로 열기
  3. 표지가 보이면 5개 모드 카드 중 하나 클릭
  4. 입력창에 한 줄 쓰고 버튼 → “생각하는 중…” → AI 답변이 뜨면 성공 ✨
AI가 답변을 만들어서 결과 박스에 보이면 한 사이클의 절반 완성입니다. 잘 하셨어요.
  • 답변이 “아직 Gemini API가 연결되지 않았어요…” → 5-3 TODO가 아직 안 채워진 상태. 다시 시도
  • 500 에러 → .env 키 오타 확인, dev 서버 재시작 (Ctrl+C 후 다시 npm run dev)
  • 주의. .env를 수정한 뒤에는 항상 dev 서버를 재시작해야 새 키를 읽습니다

6Vercel에도 비밀 알려주기 10분

여기서 가장 많이 막힙니다. 로컬에선 잘 되는데 배포 후엔 “500 에러” — 거의 100% 이 단계를 빠뜨려서 그래요. Vercel은 우리의 .env 파일을 못 봅니다. (당연하죠 — 깃허브에 안 올렸으니까) 그래서 Vercel에게 따로 알려줘야 합니다.
6-1. 내 GitHub에 코드 푸시3분
지금까지의 변경 내용을 git에 커밋하고, 내 깃허브 저장소에 푸시해줘.
커밋 메시지는 "Gemini API 연결" 로.
깃허브 저장소 페이지를 새로고침했을 때 새 커밋이 보이면 OK. 그리고 거기에 .env 파일이 안 보이는지도 다시 확인.
6-2. Vercel에 새 프로젝트로 import4분
  1. 브라우저에서 vercel.com/new 접속
  2. 본인 깃허브 계정 선택 → 방금 만든 저장소 옆 Import 클릭
  3. 설정 화면에서 Environment Variables 영역을 펼친다
  4. Name 자리에 GEMINI_API_KEY, Value 자리에 본인 키 붙여넣기
  5. Add 버튼 → 그 다음 Deploy
왜 Vercel에는 또 알려줘야 하나. Vercel은 깃허브에 있는 코드만 봅니다. .env는 깃허브에 없으니까 못 봐요. 그래서 Vercel 자기 화면에 따로 적어줘야 알게 됩니다.
6-3. 배포가 끝나면 라이브 주소 열기3분
  1. 2~3분 기다리면 “Congratulations!” 화면이 뜹니다
  2. your-app.vercel.app 같은 주소가 생겨요
  3. 주소 클릭해서 새 탭에서 열기
  4. 모드 하나 골라서 입력 → 버튼 → 답변이 뜨면 ✨ 진짜 완성
라이브 주소에서 5-4와 똑같이 AI 답변이 뜨면 한 사이클 완성. 이제 친구한테 주소를 보내면, 친구도 내 AI 미니앱을 쓸 수 있어요.

라이브 사이트에서만 500 에러가 뜬다면:

  • ① Vercel 프로젝트 → Settings → Environment Variables에 GEMINI_API_KEY가 있는지 확인
  • ② 있다면 Deployments 탭 → 가장 위 배포 옆 ⋯ → Redeploy 한 번 더
  • ③ 핵심. 환경변수를 나중에 추가했다면 반드시 Redeploy가 필요합니다

7짝꿍이랑 서로 보여주기 5분

7-1. 카톡으로 라이브 주소 공유2분
  1. 옆자리 짝꿍과 카톡(또는 메모) 친구
  2. 본인 your-app.vercel.app 주소를 서로 보내기
  3. 짝꿍 사이트에 들어가서 한 번 입력해보고, 어떤 답이 나오는지 본다
이게 진짜 “세상에 내놓는 모먼트”예요. 누군가 내 사이트를 처음으로 쓰는 순간. 부담스러우면 가족한테만 보내도 됩니다.

8다양한 API 맛보기 — 보너스 5분

오늘 Gemini로 한 사이클을 돌렸으니, 다른 API들도 똑같은 원리입니다.

OpenAI (ChatGPT)
더 똑똑한 AI. 글쓰기에 강함.
난이도 ⭐⭐ (카드 등록 필요)
카카오 지도
내 사이트에 지도 띄우기.
난이도 ⭐⭐⭐
네이버 검색
실시간 뉴스·블로그 검색 결과.
난이도 ⭐⭐
OpenWeather
오늘 날씨를 내 사이트에 표시.
난이도 ⭐⭐
다 같은 원리. ① 키 발급 → ② .env에 보관 → ③ 안티그래비티에 부탁해서 호출 코드 작성 → ④ Vercel 환경변수 등록 → ⑤ Redeploy. 오늘 배운 사이클 그대로예요. 평생 다른 API도 직접 붙일 수 있는 베이스가 잡혔습니다.
더 깊이 가고 싶다면. 스마택트 워크숍 사이트의 인터랙티브 체험 페이지에서 Postman·공개 API·에러 코드를 손으로 직접 쳐볼 수 있어요. 호기심 많은 분들의 보너스 트랙.
→ smartact.kr/workshop/vibecoding/api/worksheet

9다음 주(7회차) 미션 5분

다음 시간은 “진짜 내 프로젝트로 완성”하는 시간입니다. 두 가지를 준비해 오세요.

미션 ①. 내 도메인 사오기1주일 내

오늘 내 사이트 주소는 your-app.vercel.app으로 끝나죠. 다음 주에는 그 자리에 “내가 산 진짜 도메인”을 답니다.

  • 가성비 추천: Namecheap 또는 Porkbun에서 .xyz 도메인 — 첫 1년에 약 ₩1,000~3,000
  • 이름은 짧고 영어 소문자로 (예: mydiary.xyz, jiyoung-ai.xyz)
  • 카드 결제 부담되면 안 사도 OK. 7회차에는 vercel.app 그대로 써도 됩니다
미션 ②. README.md 채워오기30분

저장소 첫 페이지에 보이는 그 글이 README.md입니다. 일종의 “내 프로젝트 자기소개서”예요. 다음 주에 같이 다듬을 거니, 일단 빈 자리에 한국어로 3가지만 채워 오세요.

  • 이 사이트는 무엇을 하는 사이트인가 (1~2문장)
  • 어떻게 쓰는지 (1~2문장)
  • 본인 이름·만든 날짜
마크다운(.md)이 뭔지는 다음 주에. 오늘은 그냥 한국어로 자유롭게 적어 오시면 됩니다.

✓오늘의 자가 점검

다 체크됐다면 — 오늘 한 사이클 완성입니다. 오늘 처음 만들면서 정신 없었어도 괜찮습니다. 이 책을 옆에 두고 한 번 더 천천히 돌려보세요. 두 번째에는 훨씬 빨리, 덜 헷갈리게 됩니다.

★부록 — 자주 막히는 곳

증상해결
로컬에선 되는데 라이브 사이트에선 500 에러 Vercel Environment Variables 등록 + Redeploy
.env가 깃허브에 같이 올라갔다 안티그래비티에 실수로 .env가 깃에 올라갔어. 안전하게 빼주고, 키도 새로 발급받게 안내해줘
키를 수정했는데 답변이 그대로 dev 서버 재시작 (Ctrl+C → npm run dev)
“quota exceeded” 에러 잠시 기다리거나 AI Studio에서 새 키 발급
한국어 답변이 어색 lib/prompts.ts 파일 열어서 프롬프트 문장 다듬기

⌧부록 — 오늘의 용어 8개

API다른 서비스의 기능을 “주문해서 받아쓰는 창구”
키 (API key)내가 그 창구를 쓸 수 있게 해주는 멤버십 카드
.env비밀(키, 비밀번호)을 보관하는 파일. 코드에 직접 박지 않기 위해
.gitignore깃이 무시할 파일 목록. 여기에 .env를 적어두면 안 올라감
패키지 (package)누군가가 미리 잘 짜둔 코드 묶음. 빌려쓰는 도구
npm install그 도구를 내 프로젝트에 깔기
환경변수코드 밖에 따로 두는 “설정값”. .env나 Vercel 화면에 들어감
Redeploy환경변수를 바꾼 뒤 “다시 배포” 해서 적용시키기
스마택트 Smartact · 바이브코딩 6회차 한 사이클을 끝까지 — 천천히, 한 번 더