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

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

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

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

바이브코딩에서 가장 먼저 익혀야 할 기술은 아이디어를 최대한 상세하고 자세하게 기술하는 것입니다. AI서비스에 대해 환상을 가진 사람들은 AI는 사람과 달리 막연한 주문에도 원하는 결과물을 내준다고 생각하지만, 사실 그건 어디까지나 재미로 만드는 결과물 수준에서일 뿐, 예상과 다른 결과가 오차로 동작하는 산업 프로젝트에서는 맞지 않습니다. 사람이나 AI나 막연한 요구에서 생각할 수 있는 결과물의 범위는 너무 넓기 때문에, 상세하게 설명하여 그 오차를 줄여야 예상한 결과를 얻을 수 있습니다.

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

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

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

북마크를 저장하고 목록으로 보여주는 간단한 웹 앱을 만들어줘.URL과 제목을 입력하면 목록에 추가하는 거야. 그리고 저장된 목록은 카드 형태로 표시하고. 각 카드에는 삭제 버튼이 있어서 삭제도 할 수 있어야 해. 일단 최소로 만들고 세부적인 내용은 추가해가자. 일단 React Vite 기반으로 만들려고 하는데 어떻게 만들면 좋을까?

프롬프트 작성 원칙

무엇을 만들지 명확하게: 프로젝트에서 꼭 수행해야 하는 핵심적인 기능들과 그 형태를 최대한 상세하게 적습니다.
기능 범위 한정: 한 번에 너무 많은 것을 요청하지 않습니다. 작게 시작하고 단계적으로 추가합니다.
모르는 내용은 묻기: 모든 스펙을 무리하게 정할 필요 없습니다. 한번에 모든 것을 전달하기보다, 실제 사람과 대화할 때처럼 모르는 내용은 물어가며 같이 결정합니다.

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가 실행 방법을 알려줍니다. 예를 들어 React Vite 기반 프로젝트라면 보통 이렇습니다.

npm install
npm run dev

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

3단계: 수정 요청하기

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

디자인 수정 요청 예시

카드 배경에 연한 회색(#f5f5f5)을 넣고, 카드 사이 간격은 조금 더 넓혀줘.
삭제 버튼은 assets 폴더에 추가한 아이콘으로 바꿔줘.

기능 수정 요청 예시

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

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

4단계: 반복

수정 → 확인 → 추가 수정 사이클을 반복합니다. 이 반복의 과정이 중요한데, 모든 창작은 아주 얇지만 완성도 높은 구성요소가 쌓여서 만들어진다는 점을 유념해야 합니다. 바이브코딩 역시 크게 다르지 않습니다.

결과물 확인하기

프로젝트에 따라 다르지만, 이 예제에서 예시로 든 React Vite의 경우 개발 서버에서 열어두면 실시간으로 수정사항이 반영됩니다. 프로젝트 기반에 따라 적합한 방법으로 결과물을 확인합니다.

eg) Vite 개발 서버 실행 상태 (Terminal)

  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`	빌드된 파일을 로컬에서 미리보기

자주 겪는 문제와 해결 방법

바이브코딩으로 첫 화면을 만들다 보면 문제 상황을 자주 마주칩니다. AI서비스가 스스로 문제를 인식하고 해결하는 경우도 많지만, AI가 직접 문제 메시지를 읽을 수 없는 상황이거나 아예 독립된 환경에서 재현되는 경우 사용자가 문제 상황을 설명하고 분석하도록 해야 합니다.

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

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

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

사람이 직접 수행하는 코딩 과정에서도 이 트러블슈팅(Trouble Shooting) 과정이 가장 어렵고 중요한데, 이 과정을 잘 수행하는 것이 바이브코딩의 성패를 좌우한다고 해도 과언이 아닐 정도입니다. 이 부분에서 많은 경험과 역량이 요구됩니다.

여기까지 만든 것

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

다음 편에서는 바이브코딩 과정에서 종종 마주치는 문제를 다룹니다. 기능을 추가할수록 프로젝트 구조가 무너지는 현상과, 이를 어떻게 관리할 수 있는지입니다.