바이브코딩으로 첫 화면 만들기 — 아이디어를 코드로 바꾸는 실전 가이드

CLAUDE.md까지 작성했다면 이제 본격적으로 코드를 만들어볼 준비가 됐습니다. 이 글에서는 실제로 Claude Code를 사용해 간단한 웹 서비스의 첫 화면을 만드는 과정을 처음부터 끝까지 따라가봅니다.

예제로는 북마크 앱(링크를 모아두는 서비스)을 만들어봅니다. “나중에 읽을 링크를 저장해두는 간단한 서비스”입니다. 복잡하지 않으면서도 실제 서비스와 비슷한 구조를 가지고 있어 바이브코딩을 익히기에 좋습니다.

아이디어를 프롬프트로 바꾸는 방법

바이브코딩에서 가장 먼저 익혀야 할 기술은 아이디어를 AI가 이해할 수 있는 말로 바꾸는 것입니다. 막연하게 “멋진 앱 만들어줘”라고 하면 AI도 막연한 결과물을 냅니다.

좋은 프롬프트와 나쁜 프롬프트의 차이는 구체성에 있습니다.

구분	프롬프트 예시	문제점
나쁜 프롬프트	“북마크 앱 만들어줘”	어떤 기술을 쓸지, 어떻게 생겼으면 하는지 전혀 모름
보통 프롬프트	“React로 북마크 저장하는 앱 만들어줘”	기술은 명시했지만 기능, 디자인, 범위 불명확
좋은 프롬프트	아래 참고	기술, 기능, 시각적 목표, 제약 조건 모두 포함

좋은 첫 프롬프트는 이렇게 작성합니다.

북마크를 저장하고 목록으로 보여주는 간단한 웹 앱을 만들어줘.

기술 스택:
- React (Vite 기반)
- 별도 백엔드 없이 브라우저 localStorage에 데이터 저장
- CSS는 별도 라이브러리 없이 인라인 스타일로

기능:
- URL과 제목을 입력하면 목록에 추가
- 저장된 북마크 목록을 카드 형태로 표시
- 각 카드에 삭제 버튼

시각적 목표:
- 흰 배경, 심플한 디자인
- 화면 가운데 정렬, 최대 너비 600px

일단 이것만 먼저 만들어줘. 다른 기능은 나중에 추가할 거야.

프롬프트 작성 원칙

기술 스택 명시: 어떤 언어와 프레임워크를 쓸지 정확히 적습니다. 적지 않으면 AI가 임의로 선택합니다.
기능 범위 한정: 한 번에 너무 많은 것을 요청하지 않습니다. 작게 시작하고 단계적으로 추가합니다.
마지막 문장 추가: “일단 이것만 먼저”처럼 범위를 명시적으로 제한합니다. AI는 좋은 의도로 기능을 추가하는 경향이 있어 이를 방지합니다.

AI와 주고받으며 코드를 완성하는 흐름

Claude Code에 위 프롬프트를 입력하면 AI가 프로젝트 구조를 만들고 파일을 작성합니다. 이때부터는 대화를 주고받으며 결과를 다듬는 과정이 시작됩니다.

1단계: 프로젝트 생성

터미널에서 작업할 폴더로 이동한 뒤 Claude Code를 실행합니다.

# 작업 폴더 만들기
mkdir bookmark-app
cd bookmark-app

# Claude Code 실행
claude

Claude Code가 실행되면 > 프롬프트가 나타납니다. 여기에 위에서 준비한 프롬프트를 입력합니다.

AI가 작업을 시작하면 이런 메시지들이 보입니다.

Creating project structure...
Writing src/App.jsx...
Writing src/components/BookmarkList.jsx...
Writing src/components/AddForm.jsx...
...

파일을 만들고 코드를 작성하는 과정을 실시간으로 볼 수 있습니다.

2단계: 실행해보기

파일 생성이 끝나면 Claude Code가 실행 방법을 알려줍니다. Vite 기반 프로젝트라면 보통 이렇습니다.

npm install
npm run dev

터미널에 나타나는 주소(http://localhost:5173 같은 형태)를 브라우저에 입력하면 방금 만든 화면이 보입니다.

3단계: 수정 요청하기

결과물을 보면 마음에 들지 않는 부분이 있을 것입니다. 그때는 Claude Code에 구체적으로 수정을 요청합니다.

디자인 수정 요청 예시

카드 배경에 연한 회색(#f5f5f5)을 넣고,
카드 사이 간격을 더 넓혀줘.
삭제 버튼은 카드 오른쪽 상단에 × 모양으로 바꿔줘.

기능 수정 요청 예시

북마크 추가할 때 URL이 http:// 또는 https://로 시작하지 않으면
"올바른 URL을 입력해주세요"라는 경고를 보여줘.

이렇게 작은 단위로 수정을 요청하는 것이 중요합니다. 한 번에 많은 수정을 요청하면 AI가 예상치 못한 방향으로 코드를 바꾸는 경우가 생깁니다.

4단계: 반복

수정 → 확인 → 추가 수정 사이클을 반복합니다. 바이브코딩의 리듬이 여기에 있습니다.

결과물을 브라우저에서 확인하기

개발 서버가 실행 중인 상태(npm run dev)에서는 코드를 수정할 때마다 브라우저가 자동으로 업데이트됩니다. 따로 새로고침하지 않아도 됩니다.

개발 서버 실행 상태 확인

터미널에 아래와 같은 메시지가 있으면 서버가 실행 중입니다.

  VITE v5.x.x  ready in 300 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: http://192.168.x.x:5173/

http://localhost:5173/를 브라우저에 입력하면 됩니다.

자주 쓰는 개발 서버 명령어

명령어	역할
`npm run dev`	개발 서버 시작 (자동 새로고침 포함)
`Ctrl + C`	개발 서버 종료
`npm run build`	배포용 파일 생성 (나중에 사용)
`npm run preview`	빌드된 파일을 로컬에서 미리보기

자주 겪는 문제와 해결 방법

바이브코딩으로 첫 화면을 만들다 보면 몇 가지 상황을 자주 마주칩니다.

상황	원인	해결 방법
브라우저에 빈 화면만 보임	에러가 있거나 서버가 실행 안 됨	터미널에 에러 메시지 확인 후 Claude Code에 전달
“Cannot find module” 에러	패키지 설치 안 됨	`npm install` 실행
AI가 만든 코드에 빨간 밑줄	에디터의 문법 경고 (동작에는 문제없을 수 있음)	Claude Code에 에러 메시지 복사해서 물어보기
수정했는데 화면이 안 바뀜	개발 서버 미실행	`npm run dev` 다시 실행

AI에게 에러를 전달하는 방법

에러가 나면 터미널에 빨간 글씨로 메시지가 출력됩니다. 이것을 그대로 복사해서 Claude Code에 붙여넣으면 됩니다.

아래 에러가 나고 있어. 고쳐줘.

[에러 메시지 전체를 여기에 붙여넣기]

코드를 이해하지 못해도 괜찮습니다. AI가 원인을 분석하고 수정해줍니다.

여기까지 만든 것

이 단계가 끝났다면 브라우저에서 실제로 동작하는 북마크 앱의 첫 버전이 만들어진 셈입니다. 아직 로컬(내 컴퓨터)에서만 동작하고, 새로고침하면 저장된 내용이 유지되는 정도지만, 아이디어가 실제 동작하는 화면이 됐습니다.

다음 편에서는 이렇게 빠르게 만들기 시작할 때 반드시 마주치는 문제를 다룹니다. 기능을 빠르게 추가할수록 프로젝트 구조가 무너지는 현실과, 이를 어떻게 관리할 수 있는지입니다.