특강) 클로드 코드로 바이브 코딩 시작하기(Vercel로 배포까지!)

이번 특강은 Claude를 활용해서 기획서 기반 웹 서비스를 만들고, DB 연동과 배포까지 진행하는 실습이었다.

정확히는 VS Code를 열고, 터미널 명령어를 치고, 개발 환경을 하나하나 세팅하는 방식이 아니라,

로컬 폴더 안에 마크다운 문서를 준비해 두고 Claude가 그 파일들을 읽어서 앱을 만들어가는 방식이었다.

 

두둥~(넷플릭스 효과음) 요즘 핫한 바이브 코딩 되시겠다.

이름만 들으면 약간 감으로 냅다 만드는 느낌인데,

막상 보니 아무 문장이나 던지는 게 아니라 기획서, 디자인 가이드,

Supabase 정보, GitHub 정보를 미리 문서로 구조화해 두는 게 중요했다.

즉, 바이브는 바이브인데 문서 정리가 안 되어 있으면 AI도 같이 헤맨다.

(적당히 바이브하기)

[게시글 목차]

1. 바이브 코딩이란?
2. 실습 목표
3. 사전 준비
4. 로컬 워크스페이스 만들기
5. Claude에 폴더 연결하기
6. Claude로 프론트엔드 만들기
7. Supabase DB 연동하기
8. GitHub에 코드 업로드하기
9. Vercel로 배포하기
10. 오류 대응과 수정 흐름

 

+) 오늘의 인사이트

 

 

---

 

Claude Code로 내 첫 서비스 0 to 1 빌드하기
-
Github로 버전 관리 + Vercel로 배포까지.. 레쓰고

 

 

1. 바이브 코딩이란?

• 중요한 건 그냥 만들고 싶은 걸 말(채팅)로 설명하는 게 아니라, AI가 참고할 수 있는 문서를 먼저 준비하는 것이다.
• 이번 실습에서는 로컬 폴더 안에 docs와 database 폴더를 만들고,
  그 안에 기획 명세서와 디자인 가이드, Supabase 정보, GitHub 정보를 넣어두었다.

[구조]

my-mbti-app
→ docs
   → requirements.md
   → design-guide.md
   → supabase-info.md
   → github-info.md
→ database

• Claude는 이 폴더를 읽고, 문서에 맞춰 앱을 구현한다.
• 즉, 클로드가 이해할 수 있는 직관적인 구성과 파일링으로 이후 작업이 효율적으로 진행되도록 작업한다.

 

2. 실습 목표

• 이번 실습의 최종 목표는 MBTI 테스트 웹앱을 만드는 것이었다.
  (참고로 실습 교안이다/이전부터 느꼈는데 튜터님들 MBTI를 너무 좋아하시는...)
• 사용자가 질문에 답하면 결과를 보여주고, Supabase에 테스트 결과가 저장되며,
  메인 화면에는 누적 참여자 수가 표시되는 구조였다.

[흐름 정리]

기획서 작성
→ 디자인 가이드 작성
→ Claude가 프론트엔드 생성
→ Supabase DB 구조 생성
→ 테스트 결과 저장
→ GitHub 업로드
→ Vercel 배포
→ 웹앱 접속 확인

• 개발 환경은 최대한 단순하게 가져갔다.
• Node.js 설치, VS Code, 터미널 명령어 입력 없이 진행하는 방식이었다.
  물론 실제 서비스 개발에서는 이런 세팅을 피할 수 없을 때가 많겠지만,
  PM이나 비개발자가 MVP 흐름을 빠르게 경험하기에는 진입장벽을 많이 낮춘 방식이라고 느꼈다.
  (쉽게 말하면 기획부터 디자인, 개발, 배포까지 워크 플로우를 이해하는 과정이었다)

 

3. 사전 준비

GitHub 계정
Supabase 계정
Vercel 계정
Claude Desktop 앱

• GitHub : 코드를 올리는 저장소 역할
• Supabase : 데이터베이스 역할
• Vercel : 만든 웹앱을 배포하는 역할
• Claude Desktop : 로컬 폴더를 읽고 파일을 생성하거나 수정하는 역할

Claude: 기획서를 바탕으로 코드 생성
Supabase: 사용자 데이터 저장소(Project ID와 Publishable Key를 따로 문서에 정리)
GitHub: 코드 보관함
Vercel: 배포와 운영 환경

 

4. 로컬 워크스페이스 만들기

• 가장 먼저 바탕화면에 my-mbti-app 폴더를 만들었다.
  이 폴더 안에 docs와 database 폴더를 만든다.

[docs 내부에 AI가 읽을 문서들]

requirements.md
design-guide.md
supabase-info.md
github-info.md

• requirements.md : 기획서 역할
  → 어떤 서비스를 만들 것인지, 사용자는 어떤 흐름으로 테스트를 진행하는지, 결과는 어떻게 보여줄지 같은 내용이 들어간다.
• design-guide.md : 디자인 가이드 역할
  → 컬러, 톤앤매너, 레이아웃, 버튼 스타일, 결과 페이지 분위기 같은 내용을 정리한다.
• supabase-info.md : Supabase 프로젝트 정보
• github-info.md : GitHub 저장소 주소
  ⤷가능하면 마크다운 형식으로 정리하는 게 좋다(토큰이 적게 든다고 함).
• AI 입장에서는 긴 문단보다 제목, 목록, 표처럼 구조가 보이는 문서를 더 잘 읽는다.
  (나도 그런데 AI도 그렇구나... 뭐 AI도 결국 사람이 만든 거니까 그럴 수 있지)

 

5. Claude에 폴더 연결하기

1) 폴더를 만든 뒤 Claude Desktop에 해당 폴더를 연결한다.

2) 마운트 : Claude 입력창 근처의 추가 버튼을 누르거나, my-mbti-app 폴더를 Claude 앱에 드래그 앤 드롭하면 된다.

3) 마운트가 되면 Claude가 해당 폴더 안의 파일을 읽고, 필요한 파일을 생성하거나 수정할 수 있다.

4) 현재 마운트 된 폴더 안의 문서를 읽고 그 기준에 맞춰 만들어달라고 요청한다.

+) Figma 등으로 시안 작업한 게 있다면 이미지를 첨부하여 폴더 안에 넣고, 그것도 참고하라고 말할 수 있다.

(디자인 시안이 있으면 AI가 내가 원하는 바를 더 명확히 파악하게 된다)

ex.
docs/requirements.md와 docs/design-guide.md를 읽고,
기획 내용과 디자인 가이드에 맞는 웹 테스트 사이트를 만들어줘.
Next.js와 Tailwind CSS를 사용해서 질문 로직과 UI를 구현해줘.

 

6. Claude로 프론트엔드 만들기

• 첫 번째 프롬프트에서는 프론트엔드와 UI를 만들도록 지시했다.
• Claude는 requirements.md와 design-guide.md를 읽고, MBTI 테스트(실습 교안) 사이트에 필요한 파일들을 생성한다.

[이 단계에서 만들어지는 것]

페이지 구조
질문 화면
선택지 로직
결과 계산 로직
결과 페이지
기본 UI 스타일
Tailwind 기반 스타일링

• 기획서와 디자인 가이드를 넣고 나면, Claude가 알아서 프로젝트 구조를 만들고 필요한 파일을 생성한다.
  (한 번에 완벽한 결과가 나오길 기대하기보다는 초안 수준의 웹앱을 빠르게 얻는다는 목적으로 접근하는 게 좋다)

 

7. Supabase DB 연동하기

• 프론트엔드가 만들어진 뒤에는 Supabase를 연결했다.
• 이번 실습에서는 사용자가 테스트를 완료할 때마다 결과 데이터가 저장되고,
  메인 화면에 누적 참여자 수가 표시되도록 만들었다.

[흐름]

사용자가 테스트 완료
→ 결과 데이터 생성
→ Supabase에 저장
→ 전체 참여자 수 조회
→ 메인 화면에 표시

• Claude에게는 Supabase 정보가 담긴 문서를 읽고, 그 값을 코드에 반영하라고 지시했다.
  그리고 테이블 생성용 SQL은 채팅창에 바로 출력하지 말고, database/schema.sql 파일로 만들어달라고 했다.
  이 방식이 좋았던 이유는 SQL 코드도 프로젝트 폴더 안에 남기기 때문이다.
  → 채팅창에만 있으면 나중에 밀리거나 하는 미확인 이슈가 생길 수 있으니 파일로 남겨두면 다시 확인하거나 수정하기 쉽다.
• 그다음 Supabase 대시보드에 들어가서 SQL Editor를 열고, schema.sql 내용을 붙여 넣어 실행하면 테이블이 생성된다.
  (호... CSV로 작업하던 것도 이제는 수작업이 되었구나... 그거 하느라 머리 터지는 줄 알았는데)

 

8. GitHub에 코드 업로드하기

• 이번 실습에서는 Git CLI를 쓰지 않고 GitHub 웹에서 직접 업로드했다.
• Claude가 GitHub 업로드 페이지 URL을 안내하면,
  해당 페이지로 들어가서 로컬 폴더 안의 파일들을 드래그 앤 드롭으로 업로드한다.

[업로드 대상]

app
database
docs
public
package.json
기타 설정 파일

• 주의할 점은 node_modules 폴더는 올리면 안 된다는 것이다.
  GitHub 웹 업로드는 한 번에 올릴 수 있는 파일 수 제한이 있어서, 파일이 너무 많으면 오류가 날 수 있다.
  오류 메시지로 Yowza, that’s a lot of files 같은 문구가 나오면 node_modules를 빼고 올리면 된다.
  (폴더 자체가 안 올라가고 파일만 올라간다면 이를 의심해 볼 필요가 있다)
• 실무에서는 보통 Git 명령어로 관리하지만,
  이번 실습은 개발 환경 없이 진행하는 것이 목표였기 때문에 웹 업로드 방식을 사용했다.
  (간단한 프로젝트는 이런 식으로 형상관리해도 뭐... 무방하지 않나 싶다/딥하게 뭔갈 따로 할 필요 없는 건 굳이...?)

 

9. Vercel로 배포하기

• GitHub에 코드가 올라가면 Vercel에서 해당 저장소를 Import한다.
  이후 별도 설정 없이 Deploy를 누르면 배포가 진행된다.
  (대박... 깃에서 배포하는 건 여러모로 과정이 복잡했던 걸로 기억하는데 말이죠)
• 배포가 완료되면 vercel.app 형태의 주소가 발급되고,
  그 주소로 접속하면 내가 만든 MBTI 테스트(실습 교안) 웹앱을 확인할 수 있다.

[간단 전체 흐름 보기-웹 서비스 배포 과정]

Claude가 코드 생성
→ GitHub에 업로드
→ Vercel이 GitHub 저장소를 가져감
→ 자동 빌드
→ 배포 URL 생성

 

 

10. 오류 대응과 수정 흐름

• 배포 과정에서 404가 뜨거나 빌드 에러가 날 수 있다.
• 이럴 때는 에러 메시지를 통째로 복사해서 Claude에게 다시 전달하면 된다.
  (이왕이면 구체적인 상황과 오류 코드가 포함된 캡쳐 이미지를 포함하면 더 좋다)

ex.
이 에러 원인을 파악하고,
마운트된 폴더 안의 소스코드를 수정해줘.

• Claude가 수정한 뒤에는 변경된 파일을 다시 GitHub에 업로드하고 Commit하면 된다.
• Vercel은 GitHub 변경 사항을 감지해서 다시 배포한다.
  (깃허브 내용만 변경하면 알아서 배포된 것들이 조정된다... 대박이다 진짜로)

[서비스 문구나 디자인을 수정할 때]

Claude에게 수정 요청
→ 로컬 파일 변경
→ GitHub에 수정 파일 업로드
→ Commit
→ Vercel 자동 재배포

• 실무에서는 브랜치, PR, 리뷰, 환경 변수 같은 복잡한 절차가 있겠지만, 첫 배포 경험을 하기에는 적절하지 않나 싶다.

 

---

 

오늘의 인사이트

 

바이브 코딩은 이전에 '깜놀방지-회의 볼륨 평준화 서비스'를 제작하며 살짝 경험하긴 했었다.

그때는 지피티만으로 작업을 했었는데 클로드 코드로 배포까지 하는 걸 보니 흥미로웠다.

AI가 이해할 수 있게 기획과 맥락을 정리해 두는 작업이 특히 신기했다.

(그에 맞는 확장자로 제공한다는 면에서... 그게 또 토큰 절약에 도움이 된다니)

 

AI 코딩에서 중요한 건, 내가 만들고 싶은 서비스의 목적,

사용자 흐름, 화면 구성, 데이터 저장 방식까지 문서로 구조화하는 능력인 것 같다.

사실 AI 뿐 아니라 프로덕트 전반에 해당하는 말이기도 하다.

 

개인적으로도 PM도 서비스가 만들어지고 배포되는

전체 흐름을 한 번쯤은 직접 경험해봐야 한다고 생각하는 편이다.

해 본 것과 안 해 본 것은 아주 큰 차이가 있다.

(특히 오류는 많이 내봐야 대응할 수 있다지 않은가/실패 경험도 자산이다)

 

실제로 해봐야 워크플로우 이해도 잘 되고

도메인과 프로덕트에 대해 한 발짝 더 내딛는 느낌이 강하게 든다.

이제야 이쪽 세계에 진짜 발을 들였구나 싶은 느낌.

(아주 쬐에끔이지만...)

 

특강에서 바로 실습을 해보니 GitHub, Supabase, Vercel이

각각 어떤 역할을 하는지 이해됐고, 너무 유용하다고 생각한다.

(모든 것을 분석하고 문제를 발견하면 해결해야만 한다 주의라서... 겁나 피곤한 삶)

 

실제 서비스라면 보안과 형상/버전 관리를 더 신경 써야 하겠지만...

(괜히 유지보수만 하는 사람을 뽑는 게 아니라 이 말이야)

그래도 0에서 1까지 한 번 연결해 보는 경험 자체는 의미가 있었다.

 

이전에 지인과 약속했던 중소기업 수출 관련 서비스를

이번 미니 프로젝트에서 진행해 볼까 하는데

이 작업이 세상에 나온다고 생각하니 기대되고 재밌을 것 같다.

(다만... 설문 수집이 너무 안 됨......ㅋㅋㅋㅋㅋㅋㅋㅋㅋ

일부러 네이버 카페에 잠입해서 강퇴하든 말든 설문지 뿌리고 왔는데...

후 쉽지 않군... 다른 커뮤도 돌아야 하나)

 

 

---

 

오늘의 KPT 회고

 

Keep	• 바이브 코딩을 AI에게 온전히 맡기는 작업이 아니라, 기획과 맥락을 문서로 구조화하는 과정과 AI를 도구로 활용하는 방법으로 이해했다. • Claude Code로 GitHub, Supabase, Vercel까지 연결해보며 서비스 제작 흐름이 더 현실적으로 느껴졌다.(신기하고 유익했다!)
Problem	• AI가 좋은 결과물을 만들려면 기획서와 디자인 가이드가 충분히 구조화되어 있어야 한다.(잘 할 수 있겠지..? 지피티와 클로드를 양쪽으로 핸들링하면서 진행해야지 모..)
Try	• 서비스 목적, 사용자 흐름, 핵심 기능, 데이터 구조를 먼저 정리한 뒤 Claude로 구현과 배포까지 연결해볼 것.(아 가보자고~!)