🔥<24기 AI 스터디> 얼리버드 신청하기 🔥

에이전트 / 노코드 자동화
갓생오리
갓생오리
🐶 AI 찐친
☕ 커피챗 오픈
·에이전트 / 노코드 자동화에 게시됨

[Claude Code] Claude Code로 가계부 웹앱을 Vercel에 처음 올려본 후기 — 환경변수부터 배포 에러 해결까지

📝 한줄 요약

Claude Code와 함께 Next.js 가계부 웹앱을 Vercel에 처음 배포해보면서, 첫 배포는 성공했지만 두 번째 배포에서 만난 'No Next.js detected' 에러를 빌드 로그 한 줄로 추적해 해결한 후기입니다.

달력이 컴퓨터 화면에 표시됩니다
원형 차트가 포함된 대시보드 스크린샷
검정색 배경의 화면 스크린샷

바쁘시면 이것만 읽어도 돼요:

  • 목표: 흩어져 있던 지출 기록을 한 곳에 모을 가계부 웹앱 MVP를 만들고, 진짜 공개 URL까지 가보기

  • 인상 깊었던 순간: 환경변수 4개 (Google OAuth 2개, NEXTAUTH_SECRET, NEXTAUTH_URL)를 어떻게 채워야 하는지 AI가 순서대로 안내해줘서 흐름이 한 번도 끊기지 않았다

  • 막혔던 곳: 두 번째 배포에서 "Next.js를 못 찾겠다"는 에러가 났는데, 코드는 멀쩡한데 왜 안 되는지 막막했음

  • 핵심 해결 방법: 에러 메시지만 보지 말고, 빌드 로그 전체를 AI에게 통째로 넘겼더니 "removed 441 packages in 2s" 한 줄에서 단서를 짚어줌 → Vercel 대시보드의 Root Directory 설정을 의심 → 한 번에 해결

  • 얻은 것: 배포·디버깅을 자력으로 할 수 있게 됐고, 다른 Next.js 프로젝트에도 그대로 재사용 가능한 워크플로우를 손에 넣음

  • 배운 교훈: "AI에게 줄 정보가 많을수록 답이 정확해진다" — 에러 메시지 한 줄만 던지면 일반론이 돌아오지만, 로그 전체를 던지면 단서를 짚어낸다

🎯 이런 분들께 도움돼요

  • Next.js 코드는 짤 줄 알지만 Vercel 배포는 이번이 처음인 개발자

  • Vercel CLI를 처음 써보거나, OAuth 환경변수 세팅 흐름을 한 번에 정리해두고 싶은 분

  • 에러가 떴을 때 AI한테 어떤 정보를 어떤 형태로 던지면 효율적인지 패턴을 익히고 싶은 분

  • GPTers Claude Code 스터디 토요일 과제처럼 "MVP를 배포까지 가져가야 하는" 상황의 스터디 참여자

😫 문제 상황 (Before)

개인 지출을 매번 메모장에 끄적이거나 이런저런 가계부 앱에 흩어져서 기록하고 있었어요. 한 달 지나서 다시 보려고 하면 "그때 그 식비를 어디다 적었더라" 하면서 여러 앱을 뒤지는 게 일이었고요.

원하는 건 단순했어요. 달력에서 그날 클릭하면 지출이 보이고, 차트로 카테고리별 합계를 한눈에 볼 수 있는 나만의 도구. 큰 기능은 필요 없고, 우선 한 화면이라도 작동하는 MVP를 만들어서 진짜 공개 URL로 띄워보는 것이 이번 토요일 과제의 목표였습니다.

지금까지 Claude Code로 스킬을 만드는 것까진 해봤지만, 실제 사용자가 접속할 수 있는 배포 단계는 처음이었어요. 그래서 "이번 한 번은 처음부터 끝까지 가본다"를 목표로 잡았습니다.

🛠️ 사용한 도구

  • 도구명: Claude Code

  • 모델: Claude Opus 4.7 (1M context)

  • 배포 플랫폼: Vercel (Fluid Compute, Node.js 24)

  • 기술 스택 (AI가 잡아준 것): Next.js 14 + NextAuth (Google 로그인) + FullCalendar (달력) + Recharts (차트) + Tailwind CSS

🔧 작업 과정

환경변수 4개 채우기 — 외우지 말고 순서대로 받기

배포 직전, 빌드를 한 번 돌려보려고 했는데 .env.local 파일에 채워야 할 변수가 4개 있더라고요. Google OAuth 클라이언트 ID/Secret, NEXTAUTH_SECRET, NEXTAUTH_URL. 이름만 봐서는 뭘 어디서 가져와야 하는지 막막했어요.

그래서 그냥 통째로 던졌습니다.

# .env.local 파일을 열어 4개 변수 채우기:
#   GOOGLE_CLIENT_ID=...
#   GOOGLE_CLIENT_SECRET=...
#   NEXTAUTH_SECRET=$(openssl rand -base64 32)
#   NEXTAUTH_URL=http://localhost:3000
npm run build   # 빌드 에러 확인
해당 내용을 채우려면 어떻게 해야하는지 순서대로 알려줄래

AI가 단계별로 안내해줬어요.

  1. Google Cloud Console에서 OAuth 2.0 클라이언트 만들기 — 어디로 들어가서, 어떤 메뉴를 눌러서, 콜백 URL은 뭘로 설정해야 하는지 한 줄씩

  2. NEXTAUTH_SECRET 생성 — openssl rand -base64 32 명령어 한 줄로 즉시 시크릿 생성 (외울 필요 없이 그때그때 받으면 됨)

  3. NEXTAUTH_URL 설정 — 로컬은 http://localhost:3000, 나중에 Production용은 Vercel 배포 후 URL로 바꿔야 한다는 주의사항까지

  4. 빌드 검증 — 다 채운 다음 npm run build로 환경변수 누락이 있는지 한 번 확인

여기서 "오!" 했던 부분이 있어요. 사람이 알려주면 보통 "환경변수가 뭐고, 왜 필요하고, Google Cloud Console이 뭐고…" 하는 배경 설명부터 시작하잖아요. AI는 "지금 당장 클릭할 메뉴 → 복사할 값 → 어느 줄에 붙여넣을지" 만 정확히 짚어줘서 흐름이 한 번도 안 끊겼어요. 모르는 건 추가로 물어보면 되니까 우선 진행이 중요했죠.

Vercel CLI 설치와 로그인 — 인터랙티브 입력은 사용자가 직접

환경변수가 다 채워졌으니 이제 배포할 차례. Vercel CLI도 처음이라 한 줄씩 받았습니다.

npm i -g vercel
vercel --version
vercel login

여기서 살짝 막혔던 건 vercel login이 브라우저를 열어서 인증을 받는 인터랙티브 명령어였다는 점이에요. AI가 직접 실행하면 입력을 받을 사람이 없으니 멈춰버립니다.

해결은 간단했어요. 명령어 앞에 !를 붙여서 사용자가 직접 실행하면 됐어요. (Claude Code의 기능)

! vercel login

이러면 제가 직접 명령을 실행하고, 결과(브라우저 인증 완료 메시지)는 다시 AI 화면으로 돌아옵니다. 흐름이 안 끊기죠.

첫 배포 성공 — vercel --prod 한 줄

로그인까지 끝나고 vercel --prod를 실행했더니, 의외로 한 번에 됐어요. CLI가 자동으로:

  • .vercel/project.json 파일을 만들어서 프로젝트를 Vercel 계정에 자동 연결

  • 환경변수 4개를 Production 환경에 한 번에 등록

  • 빌드 → 배포 → 공개 URL 발급까지 한 흐름으로 처리

여기까지가 토요일 오후의 작업이었어요. "어, 생각보다 쉽네?" 하고 마무리하려는 순간이었죠.

다음 날, 두 번째 배포에서 막힘 — "No Next.js detected"

다음 날 다시 배포를 했더니 갑자기 빌드가 실패합니다.

Error: No Next.js version detected.
Make sure your package.json has "next" in either "dependencies" or "devDependencies".
Also check your Root Directory setting matches the directory of your package.json file.

당황스러웠어요. 어제는 됐는데 오늘은 왜 안 되지? 코드는 하나도 안 바뀌었고, package.json을 열어봐도 next: 14.2.5가 멀쩡히 들어있었거든요.

검색해보면 흔한 해결책은 "package.json에 next 추가하세요" 같은 일반론인데, 제 경우엔 이미 들어 있었으니 도움이 안 됐어요.

빌드 로그 통째로 던지기 — "removed 441 packages" 한 줄의 단서

여기서 AI한테 그냥 에러 메시지가 아니라 빌드 로그 전체를 까서 보여달라고 했어요.

이거 디버깅 좀 도와줘
[Vercel 빌드 실패 화면 그대로 복붙]

AI가 vercel inspect --logs 명령으로 빌드 로그 전체를 가져왔어요. 그리고 사람 눈에는 잘 안 보일 한 줄을 짚어줬어요.

"'removed 441 packages in 2s' — 이게 핵심 단서예요. npm install이 패키지를 설치한 게 아니라 제거한 거예요. 이건 업로드된 package.json에 next 같은 dependency가 안 들어있다는 뜻이에요. 그런데 우리 로컬 package.json엔 멀쩡히 있죠. 그럼 Vercel이 보는 package.json이 다른 위치의 것이라는 얘기예요."

그러면서 가설을 하나 던졌어요.

"Vercel 대시보드의 Root Directory 설정에 혹시 web/ 같은 값이 들어있나요? CLI는 이미 web/ 폴더에서 업로드를 시작하는데, 대시보드에서도 web/를 설정해 놓으면 Vercel은 web/web/package.json을 찾게 돼서 못 찾는 거예요."

대시보드 들어가서 Settings → Build and Development Settings → Root Directory를 확인했는데… 비어 있었어요. 가설은 살짝 빗나갔지만, 어쨌든 정상 설정이 확인됐으니 일단 다시 배포만 해보기로 했어요.

Root Directory 비어있어, 다시 배포해봐

vercel --prod 한 번 더 → 16초 만에 빌드 성공. 깔끔하게 끝났어요. 첫 배포 직후 캐시가 잠시 꼬여 있었던 것 같은데, 정확한 원인을 100% 짚진 못해도 로그 분석 → 가설 → 검증 사이클을 한 번 돌린 것만으로도 다음에 같은 에러를 만났을 때 어디서부터 봐야 할지 감이 잡혔어요.

결과 URL: https://web-wine-nine-38.vercel.app

✅ 결과 (After)

Before vs After

항목

Before

After

지출 기록

메모장·앱 여러 곳에 흩어짐

공개 URL 하나로 접근 가능

배포 능력

Vercel 배포 한 번도 안 해봄

CLI 설치 → 환경변수 → 배포 → 에러 디버깅까지 자력

에러 대응

에러 메시지로 구글링

빌드 로그를 통째로 AI에게 던지는 패턴

다음 프로젝트

0부터 시작

같은 워크플로우를 다른 Next.js 앱에 그대로 재사용 가능

결과물

💬 이 과정에서 배운 AI 활용 팁

효과적이었던 것

  1. 에러 메시지 한 줄만 던지지 말고 로그 전체를 통째로 던지기 — 에러 메시지만 던지면 일반론(검색하면 나오는 답)이 돌아옵니다. 빌드 로그 200줄을 통째로 던지면 AI가 사람 눈에 안 보이는 한 줄(예: "removed 441 packages")을 단서로 짚어줘요. 정보를 많이 줄수록 답이 정확해집니다.

  2. 외울 명령어는 외우지 말고 흐름으로 묻기 — openssl rand -base64 32 같은 한 줄을 외우는 것보다 "환경변수 4개 채우려면 어떻게 해?"라고 흐름으로 물어보는 게 빠릅니다. AI가 그때그때 필요한 명령을 정확한 순서로 던져줘요.

  3. 인터랙티브 입력은 ! 접두사로 사용자가 직접 — vercel login처럼 브라우저 인증이 필요한 명령은 AI가 직접 못 돌립니다. ! vercel login처럼 사용자가 받아서 실행하면 결과가 다시 AI 화면으로 돌아와서 흐름이 안 끊겨요.

이렇게 하면 안 돼요

  1. 검색부터 시작하기 — 에러가 떴다고 곧장 구글링부터 가면 일반론에 휘둘려서 본인 상황과 안 맞는 해결책을 시도하게 됩니다. 먼저 AI한테 로그를 통째로 줘서 본인 상황에 맞는 가설부터 받으세요.

  2. AI한테 "왜 안 돼?"만 묻기 — "왜 안 돼?"보다 "이 로그/에러 메시지/현재 설정을 보고 가능한 원인을 짚어줘"가 훨씬 정확한 답을 받습니다.

🌍 다른 업무에 적용한다면?

  • API 호출이 실패할 때 — 응답 메시지만 보지 말고 요청·응답 헤더 + 상태 코드 + 본문을 통째로 던지면 인증 토큰 만료, CORS, 페이로드 형식 등 정확한 원인을 짚어줍니다.

  • 사내 도구의 빌드/배포 실패 — Jenkins, GitHub Actions 등 어디든 로그를 통째로 던지는 패턴이 통합니다.

  • 엑셀 함수가 안 돌 때 — 에러 셀 하나만 캡처하지 말고 수식 + 참조하는 셀 + 데이터 형식까지 함께 던지세요.

핵심은 같아요. "이 에러 왜 떠?" → "이 컨텍스트 전부를 보고 가능한 원인을 짚어줘" 로 질문 패턴을 바꾸는 것.

🚀 앞으로의 계획

이번 배포가 끝이 아니라 시작이에요. 다음 주차 PRD 워크스페이스로 이어가서 기능을 한 단계씩 붙일 계획입니다.

  • 카테고리별 차트 — 식비/교통/문화 등 카테고리 단위로 월간 분포 시각화

  • 월간 리포트 — 매월 1일 자동 정리되는 한 달 요약 뷰

  • 예산 알림 — 카테고리별 예산 한도에 가까워지면 알림

  • 데이터 영속화 — 지금은 로그인까지만이라 다음은 Vercel Marketplace의 데이터베이스(Neon Postgres, Upstash Redis 등) 연결

토요일 MVP를 베이스로 PRD를 다듬어서 한 단계씩 진행하는 게 2주차 목표입니다.

📋 재사용 가능한 프롬프트

프롬프트 1: 환경변수 처음 채울 때

다음 환경변수를 채워야 하는데, 각각 어디서 어떻게 가져와야 하는지 순서대로 알려줘. 외울 필요 없이 그때그때 받아서 진행할 수 있게 명령어 한 줄씩 던져주면 좋겠어.

[채워야 할 환경변수 이름들 붙여넣기]

[본인 프로젝트의 프레임워크/플랫폼] 환경입니다.

프롬프트 2: 배포·빌드 에러로 막혔을 때

배포에서 다음 에러가 떴어. 에러 메시지만 보고 일반적인 해결책을 주지 말고, 빌드 로그 전체를 까서 사람 눈에 안 보이는 단서가 있는지 먼저 짚어줘. 그 단서로 가능한 원인 가설 2-3개를 우선순위 매겨서 알려줘.

[에러 메시지 + 빌드 로그 통째로 붙여넣기]

현재 프로젝트 구조: [폴더 구조 한 줄 요약]

프롬프트 3: 인터랙티브 명령이 필요할 때

다음 명령은 브라우저 인증/사용자 입력이 필요해서 AI가 직접 못 돌리지? 내가 직접 실행할 수 있게 ! 명령어 형식으로 알려주고, 결과를 어디서 어떻게 확인하면 다음 단계로 넘어갈 수 있는지도 알려줘.

[실행이 필요한 명령]
1
1개의 답글
밀어주고 끌어주는

온·오프라인 AI 스터디

AI로 어디까지 할 수 있는지
직접 확인하실 분만 신청하세요.

→ 9/21까지만 이 가격 →