바이브 코딩으로 첫 홈페이지 만들기: Next.js 생성부터 Vercel 배포까지
create-next-app 한 줄, Claude Code에 화면 지시, GitHub 연결, vercel 배포까지 30분 순서입니다. Node 20.9+ 요구와 첫 배포는 production이라는 점을 공식 문서로 확인했습니다.
첫 홈페이지를 만드는 가장 짧은 길은 Next.js 프로젝트를 만들고 Vercel에 올리는 것입니다. 2026년 9월 11일 기준 Next.js 설치 문서는 명령 세 줄로 로컬 실행까지 안내하고, Vercel CLI 문서는 vercel 한 번으로 배포합니다. 코드를 직접 쓰지 않아도 됩니다. 아래 순서대로 Claude Code에 지시하면서 따라가면 됩니다.
준비물
- Node.js 20.9 이상(Next.js 최소 요구). 터미널에서
node -v로 확인합니다. - GitHub 계정과 Vercel 계정(무료 Hobby 플랜으로 시작할 수 있습니다).
- Claude Code(터미널 CLI 또는 Desktop Code 탭). 둘의 차이는 Code 탭 vs CLI에.
1단계: 프로젝트 생성 (5분)
터미널에서 한 줄입니다.
npx create-next-app@latest my-site --yes
cd my-site
npm run dev
--yes는 질문을 건너뛰고 권장 기본값을 씁니다. 문서 기준 기본값은 TypeScript, Tailwind CSS, ESLint, App Router, Turbopack, import alias @/*이고, 코딩 에이전트용 AGENTS.md와 그것을 참조하는 CLAUDE.md까지 함께 만들어 줍니다. 브라우저에서 http://localhost:3000을 열면 기본 페이지가 보입니다.
질문에 직접 답하고 싶으면 --yes를 빼면 됩니다. 첫 질문은 "What is your project named?"이고, 그다음 "권장 기본값을 쓸까요?"를 묻습니다.
2단계: 화면을 말로 바꾸기 (15분)
이제 Claude Code를 프로젝트 폴더에서 엽니다. 첫 지시는 구체적일수록 좋습니다. 이 블로그의 프롬프트 빌더로 목표·대상·제약·산출물을 채워 붙여 넣어도 됩니다. 예를 들면:
app/page.tsx를 1인 사진작가 소개 홈페이지로 바꿔 줘.
- 상단: 이름, 한 줄 소개, 문의 버튼(mailto)
- 중간: 작업 3개를 카드로 (제목·한 줄 설명·이미지 자리)
- 하단: 인스타그램 링크, 저작권
- 모바일에서 세로로 잘 쌓이게
- 새 라이브러리 추가 금지, Tailwind만 사용
Claude가 파일을 고치면 npm run dev 화면이 자동으로 갱신됩니다. 마음에 안 드는 부분은 "카드 간격을 더 넓혀", "제목을 더 크게"처럼 한 번에 하나씩 고칩니다. 파일 구조는 단순합니다. app/layout.tsx가 전체 틀, app/page.tsx가 첫 화면, 이미지는 public/ 폴더에 넣고 /사진.png처럼 참조합니다.
3단계: GitHub에 올리기 (5분)
Vercel은 Git 저장소와 연결하면 이후 push마다 자동 배포합니다. Claude에게 "이 프로젝트를 GitHub 새 저장소 my-site에 올려 줘"라고 하면 git init, 커밋, gh repo create까지 처리합니다. GitHub CLI(gh)가 로그인돼 있어야 합니다.
4단계: Vercel 배포 (5분)
두 가지 길이 있습니다.
| 방법 | 언제 |
|---|---|
| 대시보드에서 Import | vercel.com → Add New → Project → GitHub 저장소 선택. 설정은 자동 감지, Deploy 버튼 |
| CLI | 터미널에서 npm i -g vercel, vercel login, 프로젝트 폴더에서 vercel |
CLI로 하면 첫 실행에서 프로젝트를 연결할지, 어느 계정(scope)에 만들지 묻습니다. 문서에 따르면 새 프로젝트의 첫 배포는 --prod 없이도 항상 production이고, 그 뒤 vercel은 미리보기(preview), vercel --prod는 운영 배포입니다. 출력의 마지막 줄이 배포 URL입니다.
배포가 끝나면 https://my-site-xxxx.vercel.app 같은 주소가 생깁니다. 이 시점에 이미 전 세계에서 접속되는 홈페이지입니다.
5단계: 내 도메인 붙이기 (선택)
Vercel 프로젝트의 Settings → Domains에서 도메인을 추가하고, 안내대로 도메인 등록 업체에서 DNS 레코드를 바꿉니다. 반영에 수 분에서 수 시간이 걸립니다. 도메인 구매 비용은 별도입니다.
다음 배포부터는
수정 → 커밋 → push만 하면 됩니다. 브랜치를 따로 만들어 push하면 미리보기 URL이 생기고, main에 합치면 운영에 반영됩니다. 이미지가 무거우면 next/image를 쓰라고 Claude에게 말하면 자동 최적화됩니다.
흔한 막힘
node -v가 20 미만: nodejs.org에서 LTS를 설치합니다.- 빌드 실패: Vercel 로그의 빨간 줄을 그대로 복사해 Claude에게 붙입니다. 대부분 타입 오류나 빠진 파일입니다.
- 환경 변수: API 키 같은 값은 코드에 쓰지 말고 Vercel Settings → Environment Variables에 넣습니다.
- 폼·문의 저장: 정적 홈페이지에는 DB가 없습니다. 문의는
mailto:나 외부 폼으로 시작하고, 저장이 필요해지면 다음 단계(Supabase)로 갑니다.
다음 단계
- 프롬프트 빌더로 첫 지시문 만들기
- 좋은 프롬프트의 구조
- Pro 홈페이지 과정은 강의 소개에서