Claude Code 상세 사용법 31: Vercel 첫 Preview 배포를 맡기는 법 | DAKER 커뮤니티

Claude Code 상세 사용법 31: Vercel 첫 Preview 배포를 맡기는 법

2026년 6월 6일 기준 Claude Code 공식 문서는 CLI에서 claude, claude -p, --permission-mode, --tools 같은 실행 경계를 제공한다고 설명한다. Vercel 공식 문서는 CLI 배포가 기본적으로 preview deployment를 만들고, production은 --prod를 붙일 때라고 정리한다. 이 글은 클로드 코드에게 Vercel 첫 배포를 맡길 때 production을 건드리지 않는 안전한 시작 루프다.

위 SVG는 Mermaid 구조를 DAKER 편집기용 튜토리얼 이미지로 옮긴 것이다.

1. 먼저 프로젝트를 읽게 한다

처음부터 vercel --prod를 요청하지 않는다. Claude Code에게 package.json, lockfile, framework, build script를 읽고 배포 전제부터 확인하게 한다.

이 저장소를 Vercel preview로 배포할 준비가 되었는지 확인해줘.
package manager, build command, required env 이름, 실패 가능성을 먼저 보고하고
production 배포는 절대 하지 마.

이 단계에서 Claude Code가 해야 할 일은 코드 수정이 아니라 지도 만들기다. npm run build가 있는지, Next.js인지 Vite인지, monorepo root가 맞는지 확인한다. Vercel은 많은 framework preset을 자동 감지하지만, AI 코딩에서는 자동 감지를 검증 대상으로 두는 편이 안전하다.

2. 권한은 preview까지만 연다

Claude Code permissions 문서는 Bash와 파일 수정이 승인 대상이고, mode와 allow/deny rule로 제한할 수 있다고 설명한다. 배포 작업에서는 읽기, 테스트, preview 배포만 허용한다.

claude --permission-mode plan

계획을 확인한 뒤에는 다음 정도만 허용한다.

npm test
npm run build
vercel link
vercel deploy

환경변수 값, 토큰, 쿠키는 Claude Code 채팅에 붙이지 않는다. 필요한 이름만 말한다. 예를 들어 NEXT_PUBLIC_API_BASE_URL이 없다는 사실은 보고하게 해도 되지만 실제 secret value는 Vercel 대시보드나 안전한 CLI 흐름에서 사람이 넣는다.

3. Preview URL을 완료 기준으로 둔다

vercel deploy가 성공하면 Claude Code에게 URL만 보고 끝내지 말고 다음 검증을 요청한다.

방금 생성된 Vercel preview URL 기준으로
1. 빌드 로그의 warning
2. 첫 화면 로딩
3. API 호출 실패 가능성
4. production 배포 전 남은 체크리스트
를 정리해줘.

실패하면 “고쳐줘”보다 “첫 번째 실패 원인만 좁혀줘”가 낫다. build log, framework preset, install command, output directory 중 어느 축인지 먼저 분류하게 한다.

Senior takeaway: Vercel 사용법을 Claude Code에 맡길 때 핵심은 배포 명령이 아니라 배포 경계다. preview URL, 로컬 build, 실패 로그, 남은 리스크가 한 세트로 보고될 때 agentic coding이 개발 생산성으로 바뀐다.