프롤로그

저는 인문계를 졸업하고 기자로 일을 하다가 뒤늦게 개발자로 커리어를 바꿨습니다. 인생에서 정말 잘한 일이라고 생각합니다. 필요한 게 있으면 직접 만들고, 아이디어가 있으면 세상에 내놓을 수 있게 됐으니까요. 무한한 가능성이 열렸습니다.

그런데 이제는 굳이 개발자가 되지 않아도 그럴 수 있는 세상이 됐습니다. AI 덕분에요. 저도 요즘엔 코드를 직접 쓰지 않습니다. 대신 AI와 대화하면서 소프트웨어를 만듭니다.

바이브코딩으로 모바일 앱을 출시하고, B2B SaaS를 만들면서 배운 것들을 이 가이드에 담았습니다. 무료로 공개합니다. 한국어로 된 양질의 자료는 대부분 유료인데, 영어권에는 좋은 자료가 무료로 넘쳐납니다. 그 격차가 아깝다고 생각했습니다.

이 가이드는 코딩을 배우는 책이 아닙니다. 만들고 싶은 게 있는데 코딩을 모른다는 이유로 포기했거나, 외주를 맡기기엔 너무 초기 단계라 묻어뒀던 것들을 꺼내도록 돕는 책입니다. 끝까지 따라오시면 여러분의 아이디어를 세상에 내놓을 수 있습니다.

업무를 자동화하고 싶은 분도, 다음 유니콘을 꿈꾸는 분도 환영합니다.

그럼, 시작합니다.

P.S. 이 가이드만으로 충분히 시작할 수 있습니다. 더 깊고 체계적으로, 글로 다루기 힘든 부분까지 배우고 싶다면 오프라인 강의에서 직접 도와드립니다.

1장: 코딩의 규칙이 바뀌었다

바이브코딩이란 무엇인가

2025년 2월, AI 연구자 Andrej Karpathy가 트위터에 짧은 글을 올렸습니다.

"There's a new kind of coding I call 'vibe coding', where you fully give in to the vibes, embrace exponentials, and forget that the code even exists."

코드가 존재한다는 사실조차 잊어버리고, 그냥 분위기에 몸을 맡겨라. 이것이 바이브코딩입니다.

구체적으로는 이런 방식입니다. AI에게 "할 일 관리 앱 만들어줘"라고 말합니다. AI가 코드를 씁니다. 결과를 보고 "완료된 항목은 회색으로 바꿔줘"라고 말합니다. AI가 수정합니다. 이 과정을 반복하면 앱이 완성됩니다. 코드를 직접 쓰는 일은 한 줄도 없습니다.

전통적 코딩 vs 바이브코딩

전통적 코딩은 프로그래밍 언어를 배우는 것에서 시작합니다. 문법을 익히고, 로직을 설계하고, 한 줄 한 줄 직접 타이핑합니다. 에러가 나면 어디가 잘못됐는지 직접 찾아야 합니다. 수개월에서 수년의 학습이 필요합니다.

바이브코딩은 다릅니다. AI에게 원하는 결과를 말로 설명합니다. AI가 코드를 생성합니다. 여러분은 결과를 확인하고 방향을 조정합니다. 프로그래밍 언어를 모르는 사람도 첫날부터 무언가를 만들 수 있습니다.

핵심적인 차이는 역할의 전환입니다. 전통적 코딩에서 사람은 "코드를 쓰는 사람"이었습니다. 바이브코딩에서 사람은 "방향을 잡는 사람"입니다. AI가 코드를 쓰고, 여러분은 무엇을 만들지 결정하고, 결과가 맞는지 확인합니다.

용어를 둘러싼 논쟁

"바이브코딩"이라는 말이 퍼지면서 논쟁도 함께 생겼습니다. 개발자 커뮤니티에서는 이 용어가 적절하지 않다는 목소리가 적지 않습니다.

주된 비판은 이렇습니다. "바이브"라는 단어가 주는 인상이 너무 가볍다는 겁니다. 분위기로 대충 만든다는 느낌이 강하고, 실제 서비스에 올릴 수 있는 수준의 소프트웨어 개발과는 거리가 있다는 지적입니다. 실제로 Karpathy 본인도 이후에 "에이전틱 엔지니어링(agentic engineering)"이라는 표현으로 옮겨갔습니다. AI 에이전트가 코드를 쓰고 사람이 감독하는 구조에는 "엔지니어링"이라는 단어가 더 맞다는 취지입니다.

이 가이드에서는 편의상 "AI를 활용한 코딩" 전반을 바이브코딩이라 부르겠습니다. 용어의 경계가 어디인지는 전문가들이 정리할 문제이고, 우리의 관심사는 "AI와 함께 내 프로젝트를 만드는 것"이니까요.

바이브코딩으로 할 수 있는 것들

바이브코딩으로 만들 수 있는 것은 생각보다 넓습니다.

웹 애플리케이션(웹앱): 브라우저에서 열리는 서비스입니다. 랜딩 페이지, 예약 시스템, 커뮤니티 사이트, 관리자 대시보드처럼 URL을 통해 접속하고 로그인, 데이터 저장, 결제 같은 기능이 있는 것들이 여기에 해당합니다. 이 가이드에서 실습하는 영역입니다.

업무 자동화: 엑셀 데이터를 자동으로 정리하는 스크립트, 이메일을 자동 발송하는 도구, 파일을 일괄 변환하는 프로그램 등을 만들 수 있습니다.

데이터 분석: CSV 파일을 읽어 차트를 만들고, 패턴을 찾고, 보고서를 생성하는 프로그램도 가능합니다.

모바일 앱: React Native나 Flutter 같은 프레임워크를 활용하면 앱스토어에 올릴 수 있는 앱도 만들 수 있습니다.

이 가이드는 웹앱을 중심으로 다루지만, 바이브코딩의 방식 자체는 무엇을 만들든 동일합니다. AI에게 원하는 걸 설명하고, 결과를 확인하고, 방향을 잡는 것.

그러려면 먼저 도구가 필요합니다. 다음 장에서 바이브코딩에 쓸 도구들을 살펴보고, 직접 설치해보겠습니다.

2장: 도구와 환경 설정

이 장에서는 바이브코딩에 필요한 도구를 설치하고 실제로 동작시킵니다. 그 전에 한 가지 개념을 짚고 갑니다.

AI 모델 vs 하네스

AI 모델은 Claude Sonnet, GPT-5.4와 같은 두뇌 자체입니다. 텍스트를 넣으면 텍스트를 내놓습니다. 그게 전부입니다. 파일을 만들지도, 명령어를 실행하지도, 에러를 고치지도 못합니다.

하네스(harness)는 두뇌를 감싸서 실제로 일하게 만드는 환경입니다. 원래 말에 채우는 마구라는 뜻입니다. 고삐와 안장이 없으면 말을 탈 수 없듯이, 하네스가 없으면 AI는 텍스트를 생성하는 데서 끝납니다. 하네스가 있어야 실제로 파일을 만들고 수정하고 실행까지 합니다. 같은 모델이라도 하네스를 어떻게 설계하느냐에 따라 결과물의 품질이 달라집니다.

	AI 모델	하네스 (Claude Code)
코드 생성	✅ 텍스트로 출력	✅ 텍스트로 출력
파일 직접 생성	❌	✅ 실제 파일 만듦
라이브러리 설치	❌	✅ 알아서 설치
에러 자동 수정	❌	✅ 실행 후 직접 수정
프로젝트 전체 파악	❌	✅ 폴더 전체 읽음

모델에게 "투두 앱 만들어줘"라고 하면 코드 텍스트가 나옵니다. 그걸 파일로 저장하고, 라이브러리를 설치하고, 실행하는 건 전부 여러분의 몫입니다. Claude Code에서 같은 말을 하면 파일을 직접 생성하고, 필요한 것을 알아서 설치하고, 브라우저에서 열 수 있는 상태까지 만들어줍니다. 이 차이가 바이브코딩을 가능하게 합니다.

Claude Code와 Antigravity

Claude Code를 쓰려면 터미널이 필요하고, Claude Code가 만든 결과물을 보려면 편집기가 필요합니다. 이 가이드에서는 편집기로 Antigravity를 씁니다.

터미널은 검은 화면에 흰 글씨뿐이라 낯설 수 있지만, 그냥 "텍스트로 대화하는 창"입니다. claude를 입력해서 Claude Code를 실행하고, 한국어로 말하면 됩니다. 명령어를 외울 필요도 없습니다. Claude Code가 알아서 실행합니다.

Antigravity는 VS Code를 기반으로 만든 코드 편집기입니다. Claude Code가 파일을 만들거나 수정하면 왼쪽 파일 탐색기에 바로 나타납니다. 파일을 클릭하면 코드를 볼 수 있고, 직접 수정할 수도 있습니다. 내장 터미널도 있어서 Antigravity 하나로 편집기와 Claude Code를 동시에 쓸 수 있습니다.

둘을 함께 쓰는 흐름은 이렇습니다.

Antigravity를 열고, 내장 터미널에서 Claude Code를 실행한다
Claude Code에게 작업을 시킨다
Claude Code가 파일을 만들거나 수정한다
Antigravity 왼쪽 패널에서 바뀐 파일을 확인한다
브라우저에서 결과를 확인하고, 다시 Claude Code에게 수정을 요청한다

Cursor나 Windsurf 같은 편집기는 AI 기능이 내장되어 있고, VS Code에 Claude Code를 연동할 수도 있습니다. 하지만 도구를 비교하는 데 시간을 쓰는 것보다, 하나를 빠르게 익혀서 실제로 만들기 시작하는 게 더 중요합니다. 이 가이드에서는 Claude Code + Antigravity 조합을 기준으로 설명합니다.

터미널 기본 명령어 5개

Claude Code를 쓰다 보면 이 명령어들을 가끔 직접 입력해야 할 때가 있습니다. 외우지 않아도 괜찮지만, 한 번씩 실제로 입력해보세요.

pwd — 지금 내가 어느 폴더에 있는지 보여줍니다.

$ pwd
/Users/jaehoo/Documents/my-project

ls — 현재 폴더 안의 파일과 폴더 목록을 보여줍니다.

$ ls
index.html   style.css   app.js   images/

cd 폴더이름 — 해당 폴더로 이동합니다. cd ..은 한 단계 상위 폴더로 이동합니다.

$ cd my-project
$ pwd
/Users/jaehoo/Documents/my-project

mkdir 폴더이름 — 새 폴더를 만듭니다.

$ mkdir my-first-page

claude — Claude Code를 실행합니다. 이게 가장 중요한 명령어입니다.

$ claude
✻ Welcome to Claude Code!
...
>

> 프롬프트가 나오면 준비된 겁니다. 여기서부터 한국어로 대화하면 됩니다.

Claude Code 대화 중 알아두면 좋은 것들

대화를 끝내고 싶으면 /exit를 입력하거나 Ctrl+C를 누릅니다
긴 응답이 나오는 도중에 멈추고 싶으면 Ctrl+C를 누릅니다
이전 명령어를 다시 쓰고 싶으면 키보드 위 방향키(↑)를 누릅니다

Claude Code 설치하기

macOS에 설치

1단계: 터미널을 엽니다.

Spotlight 검색(Cmd+Space)에서 "터미널"이라고 입력하면 나옵니다. 또는 Finder에서 응용 프로그램 > 유틸리티 > 터미널을 찾으면 됩니다. 처음 열면 흰 배경 또는 검은 배경에 $ 기호가 깜빡이는 창이 나옵니다. 정상입니다.

2단계: 아래 명령어를 그대로 복사해서 붙여넣고 Enter를 누릅니다.

curl -fsSL https://claude.ai/install.sh | bash

설치가 진행되면서 텍스트가 쭉 나옵니다. 중간에 비밀번호를 묻는 경우 macOS 로그인 비밀번호를 입력합니다 (입력할 때 화면에 아무것도 표시되지 않습니다, 정상입니다). 마지막에 Claude Code installed successfully 같은 메시지가 나오면 설치 완료입니다.

3단계: 터미널을 껐다가 다시 킵니다. 새 터미널 창에서 아래를 입력해서 설치를 확인합니다.

claude --version

버전 번호가 나오면 성공입니다.

Windows에 설치

Windows는 먼저 Git for Windows가 필요합니다.

1단계: https://git-scm.com/downloads/win 에서 설치 파일을 다운로드해서 실행합니다. 설치 중 물어보는 것들은 모두 기본값으로 두고 "Next"를 눌러 끝까지 진행합니다.

2단계: 시작 메뉴에서 "PowerShell"을 검색해서 "Windows PowerShell"을 엽니다. 아래 명령어를 입력합니다.

irm https://claude.ai/install.ps1 | iex

3단계: 새 PowerShell 창을 열고 설치를 확인합니다.

claude --version

설치 후 첫 실행

claude를 입력하면 처음에는 로그인 안내가 나옵니다.

$ claude

Welcome to Claude Code!

터미널에 /login을 입력하면 브라우저가 자동으로 열리고 Anthropic 계정 로그인 화면이 나옵니다. 구독이 연결된 계정으로 로그인하면 터미널로 돌아와서 > 프롬프트가 나타납니다. 한 번만 하면 이후에는 자동으로 로그인 상태를 유지합니다.

Antigravity 설치 및 Claude Code 연동

1단계: https://antigravity.google 에 접속합니다.

2단계: 운영체제에 맞는 설치 파일을 다운로드합니다. macOS는 .dmg, Windows는 .exe 파일입니다.

3단계: 설치합니다.

macOS: 다운로드한 .dmg 파일을 더블클릭하고, Antigravity 아이콘을 Applications 폴더로 드래그합니다. 처음 실행할 때 "인터넷에서 다운로드한 앱"이라는 경고가 나올 수 있습니다. 이 경우 System Settings > Privacy & Security에서 "Open Anyway"를 클릭합니다.

Windows: .exe 파일을 실행하면 설치가 진행됩니다. "Windows가 PC를 보호했습니다"라는 메시지가 나올 수 있는데, "추가 정보"를 클릭한 후 "실행"을 클릭합니다.

4단계: Antigravity를 열고 첫 화면을 확인합니다.

처음 실행하면 이런 화면이 보입니다.

왼쪽 사이드바: 파일 탐색기 (아직 프로젝트를 열지 않았으면 비어있습니다)
가운데: 편집 영역
하단: 내장 터미널 (보이지 않으면 Ctrl+백틱 으로 열 수 있습니다)

5단계: 내장 터미널에서 Claude Code가 잘 실행되는지 확인합니다.

하단 터미널에 claude --version을 입력합니다. 버전 번호가 나오면 연동 완료입니다. 이제 이 창 하나에서 파일도 보고 터미널도 쓸 수 있습니다.

✏️ 실습: Claude Code에게 자기소개 페이지를 만들게 하고 브라우저에서 열어보기

설치가 끝났으면 바로 해봅시다. 코딩 경험이 전혀 없어도 됩니다.

1단계: Antigravity를 열고, 내장 터미널(Ctrl+백틱)에서 작업 폴더를 만듭니다.

mkdir my-first-page
cd my-first-page

2단계: Claude Code를 실행합니다.

claude

> 프롬프트가 나오면 준비된 겁니다.

3단계: 아래처럼 말합니다. [본인 이름] 부분은 실제 이름이나 닉네임으로 바꿔주세요.

내 이름은 [본인 이름]이야.
간단한 자기소개 웹페이지를 만들어줘.
이름, 한 줄 소개, 좋아하는 것 3가지를 카드 형태로 예쁘게 보여주는 HTML 파일로 만들어줘.
배경색은 부드러운 색으로, 폰트는 읽기 편하게 해줘.

4단계: Claude Code가 작업하는 것을 지켜봅니다.

화면에 이런 흐름이 보입니다.

● I'll create a simple personal introduction webpage for you...

● Writing index.html...
  ✓ Created index.html

파일을 만들 때 허락을 구하는 확인 창이 뜨면 허용하면 됩니다. "Always allow for this project" 또는 "Always allow"를 선택하면 이후에는 매번 묻지 않습니다.

5단계: Antigravity 왼쪽 파일 탐색기에 index.html이 생긴 것을 확인합니다. 클릭하면 코드가 보입니다.

6단계: 파일을 브라우저에서 엽니다.

Antigravity에서 index.html을 마우스 오른쪽 클릭합니다.

macOS: "Reveal in Finder"를 클릭하면 파인더가 열립니다. 거기서 index.html을 더블클릭합니다.
Windows: "Reveal in File Explorer"를 클릭하면 파일 탐색기가 열립니다. 거기서 index.html을 더블클릭합니다.

기본 브라우저에서 자기소개 페이지가 열립니다.

7단계: 마음에 안 드는 부분이 있으면 Claude Code에게 말합니다.

배경색을 더 어둡게 바꿔줘. 그리고 이름을 더 크게 강조해줘.

변경하고 저장하면 브라우저에서 새로고침(F5 또는 Cmd+R)해서 바뀐 모습을 확인할 수 있습니다.

코드를 한 줄도 직접 쓰지 않고 웹페이지를 만들었습니다. 이게 바이브코딩의 시작입니다. 다음 장에서는 AI에게 더 정확하게 일을 시키는 방법, 즉 프롬프트를 다룹니다.

3장: 프롬프트 — 바이브코딩의 핵심 스킬

바이브코딩에서 여러분이 직접 하는 일은 딱 하나입니다. AI에게 말하는 것. 이 "말"을 프롬프트라고 합니다. 코드를 얼마나 아느냐보다 프롬프트를 얼마나 잘 쓰느냐가 결과를 결정합니다.

프롬프트란 무엇인가

프롬프트는 AI에게 보내는 지시문입니다. "투두 앱 만들어줘"도 프롬프트이고, "버튼 색깔을 파란색으로 바꿔줘"도 프롬프트입니다.

중요한 건 AI는 여러분의 머릿속을 읽을 수 없다는 점입니다. 여러분이 "멋진 웹사이트"를 상상할 때, 그 "멋진"이 정확히 무엇인지 AI는 모릅니다. 여러분이 당연하게 여기는 것들 — 이 사이트는 모바일에서도 봐야 한다, 한국어로 나와야 한다, 외부 라이브러리는 쓰지 않았으면 한다 — 을 말하지 않으면 AI는 그냥 자기 판단대로 합니다.

프롬프트는 그 간격을 메우는 도구입니다. 여러분이 상상하는 것을 AI가 이해할 수 있는 언어로 풀어내는 것, 그게 프롬프트입니다.

나쁜 프롬프트 vs 좋은 프롬프트

세 가지 예시를 봅시다. 같은 목표인데 프롬프트에 따라 결과가 얼마나 달라지는지 비교해보세요.

예시 1: 투두 앱

나쁜 프롬프트:

투두 앱 만들어줘.

AI가 뭔가를 만들긴 합니다. 하지만 어떤 기술 스택을 쓸지, 어떻게 생겨야 하는지, 어떤 기능이 있어야 하는지 전혀 모릅니다. Python으로 만들 수도 있고, 아주 기초적인 HTML로 만들 수도 있습니다.

좋은 프롬프트:

HTML 파일 하나로 동작하는 투두 앱을 만들어줘.
- 할 일 입력 필드와 추가 버튼
- 추가된 할 일은 목록으로 표시
- 각 항목마다 완료 체크박스와 삭제 버튼
- 완료된 항목은 취소선으로 표시
- 새로고침해도 목록이 유지되게 localStorage 사용
- 배경은 흰색, 심플한 디자인

기술 스택(HTML 하나), 기능(추가/체크/삭제), 동작 방식(localStorage), 디자인 방향을 모두 명시했습니다.

예시 2: 에러 수정

나쁜 프롬프트:

에러 고쳐줘.

어떤 에러인지, 어디서 났는지 AI가 알 수 없습니다.

좋은 프롬프트:

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

TypeError: Cannot read properties of undefined (reading 'map')
  at ProductList (src/components/ProductList.jsx:12)

에러 메시지 전체를 복사해서 붙여넣고, 어떻게 처리하면 좋은지를 같이 줬습니다. 에러 메시지의 뜻을 몰라도 됩니다. 그대로 복사해서 AI에게 주면 AI가 해석합니다.

예시 3: 디자인 수정

나쁜 프롬프트:

디자인 예쁘게 바꿔줘.

"예쁘다"의 기준이 사람마다 다릅니다. AI는 자기 기준으로 바꿉니다.

좋은 프롬프트:

헤더 디자인을 바꿔줘.
- 배경색: 짙은 남색(#1a237e)
- 로고와 메뉴 텍스트: 흰색
- 높이: 60px
- 메뉴 항목 간격: 24px
- 스크롤해도 화면 상단에 고정

색상 코드, 수치, 동작 방식까지 명시하면 AI가 정확하게 반영합니다.

5가지 프롬프트 패턴

바이브코딩에서 반복해서 쓰는 패턴 다섯 가지입니다. 외울 필요 없이 상황에 따라 참고하면 됩니다.

패턴 1. 구체적 지시

무엇을 만들지, 어떤 요소가 포함되어야 하는지 구체적으로 나열합니다. 가장 기본적이고 자주 쓰는 패턴입니다.

핵심은 이것들을 명시하는 겁니다.

무엇을: 어떤 페이지, 기능, 화면 요소인지
어떻게 생겼는지: 레이아웃, 색상, 크기
어떻게 동작하는지: 클릭하면 무슨 일이 일어나는지
어떤 기술로: HTML, React, Next.js 등

예시:

로그인 페이지를 만들어줘.
- 이메일 입력 필드
- 비밀번호 입력 필드 (입력값이 보이지 않게)
- 로그인 버튼 — 클릭하면 /dashboard로 이동
- "비밀번호를 잊으셨나요?" 링크
- 전체 화면 가운데 정렬, 카드 형태
- Tailwind CSS 사용

뭔가 빠뜨린 것 같아도 괜찮습니다. 결과를 보고 추가로 요청할 수 있습니다.

패턴 2. 역할 부여

AI에게 특정 전문가의 역할을 맡기면 그 관점에서 접근합니다.

너는 사용성 전문가야.
이 회원가입 폼을 처음 쓰는 사람 입장에서 불편한 점을 찾아줘.
그리고 개선 방법도 제안해줘.

같은 코드를 봐도 역할에 따라 다른 것에 집중합니다. 보안 전문가는 취약점을, 디자이너는 시각적 일관성을, 사용성 전문가는 사용 흐름을 봅니다.

실제로 자주 쓰는 역할들:

너는 시니어 프론트엔드 개발자야. 이 코드에서 개선할 수 있는 부분을 알려줘.

너는 UX 디자이너야. 이 화면에서 사용자가 헷갈릴 수 있는 부분을 찾아줘.

너는 한국 사용자를 위한 서비스를 만드는 사람이야. 이 텍스트들을 자연스러운 한국어로 바꿔줘.

패턴 3. 단계 분리

복잡한 작업은 한 번에 다 시키면 AI가 중요한 부분을 빠뜨리거나 엉뚱한 방향으로 가기 쉽습니다. 단계를 나눠서 각 단계마다 결과를 확인하는 게 훨씬 안전합니다.

예를 들어, 쇼핑몰을 만든다면:

1단계 -- 먼저 설계만:

온라인 서점을 만들려고 해. 어떤 페이지들이 필요할지 목록으로 정리해줘.
각 페이지에 어떤 기능이 있어야 하는지도 간단히 써줘.
코드는 아직 쓰지 마.

목록을 확인하고, 방향이 맞으면:

2단계 -- 첫 번째 페이지 구현:

좋아. 먼저 메인 페이지부터 만들어줘.
책 목록을 카드 형태로 보여주고, 각 카드에 표지 이미지, 제목, 저자, 가격이 나오게.

3단계 -- 다음 페이지로 이동:

메인 페이지 완성됐어. 이제 책 상세 페이지 만들어줘.
메인에서 카드 클릭하면 이 페이지로 이동하게.

이렇게 하면 뭔가 잘못됐을 때 일찍 발견하고 수정할 수 있습니다.

패턴 4. 예시 제공

말로 설명하기 어려운 레이아웃이나 데이터 구조는 예시를 직접 보여주면 AI가 훨씬 정확하게 파악합니다.

텍스트로 레이아웃 스케치:

아래처럼 생긴 대시보드를 만들어줘.

[상단 헤더: 로고 | 메뉴 | 로그인 버튼]
--------------------------------------------
[사이드바]  | [메인 콘텐츠]
- 홈        | 월별 매출 그래프 (상단)
- 주문      |
- 고객      | 최근 주문 목록 (하단)
- 설정      |

데이터 구조 예시:

상품 데이터가 아래 형태로 되어 있어.
이걸 화면에 표로 보여줘.

{
  "products": [
    { "id": 1, "name": "아메리카노", "price": 4500, "stock": 100 },
    { "id": 2, "name": "카페라떼", "price": 5000, "stock": 80 }
  ]
}

비슷한 서비스 참고:

Notion의 사이드바처럼, 클릭하면 하위 항목이 펼쳐지는 트리 메뉴를 만들어줘.

패턴 5. 제약 조건

하지 말아야 할 것, 반드시 지켜야 할 조건을 명시합니다. 이걸 빠뜨리면 AI가 자기 판단으로 결정하고, 나중에 "이건 이렇게 하지 말았어야 했는데"가 생깁니다.

하지 말 것을 명시:

이 기능을 추가할 때 기존 CSS 파일은 건드리지 마.
style.css는 수정하지 말고, 새 클래스는 인라인 스타일로 처리해줘.

외부 라이브러리 추가하지 말고, 순수 HTML/CSS/JavaScript로만 만들어줘.

반드시 지킬 것을 명시:

모든 텍스트는 한국어로.
버튼, 안내 문구, 에러 메시지 전부 한국어야.

색상은 현재 디자인 시스템을 유지해줘.
primary: #2563EB, text: #111827, background: #F9FAFB
이 색상 값만 써.

기술 스택을 명시:

이 프로젝트에서 쓰는 기술 스택(React, TypeScript, Tailwind CSS)에 맞게 만들어줘.

프롬프트를 점진적으로 발전시키기

처음부터 완벽한 프롬프트를 쓸 필요가 없습니다. 오히려 짧게 시작해서 결과를 보고 수정하는 방식이 더 효율적입니다.

실제 대화 흐름을 보면 이렇습니다.

나: 투두 앱 만들어줘.

기본 투두 앱이 나왔습니다. 기능은 되는데 디자인이 마음에 안 듭니다.

나: 디자인을 바꿔줘. 배경은 연한 회색(#f5f5f5), 각 할 일 항목은 흰색 카드로.
    카드에 살짝 그림자 넣어줘.

디자인이 좋아졌습니다. 그런데 완료된 항목이 일반 항목과 구분이 안 됩니다.

나: 완료 체크한 항목은 텍스트에 취소선 긋고, 텍스트 색을 회색으로 바꿔줘.

이제 완료 항목이 구분됩니다. 새로고침하면 목록이 사라지는 게 불편합니다.

나: 새로고침해도 목록이 유지되게 localStorage에 저장해줘.

이렇게 대화를 이어가면서 원하는 것에 점점 가까워집니다. 처음에 모든 걸 한 번에 말하려다 보면 오히려 중요한 걸 빠뜨리기 쉽습니다.

AI가 엉뚱한 방향으로 갔을 때

결과가 기대와 많이 다를 때는 두 가지 방법이 있습니다.

첫째, 방향을 잡아줍니다.

아, 이 방향이 아니야. 현재 코드는 두고,
버튼 색깔만 파란색으로 바꿔줘. 다른 건 건드리지 마.

둘째, 처음부터 다시 합니다. Claude Code에서 /clear를 입력하면 대화 내용이 초기화되고 새로 시작할 수 있습니다. 대화가 꼬였다 싶으면 새로 시작하는 게 빠를 때가 많습니다.

바이브코딩 프롬프트 실전 팁

몇 가지 습관을 들이면 결과가 달라집니다.

기술 스택을 항상 명시하세요. "페이지 만들어줘"보다 "Next.js로 페이지 만들어줘"가 훨씬 정확한 결과를 줍니다. 프로젝트 초반에 CLAUDE.md에 기술 스택을 써두면 (5장에서 다룹니다) 매번 명시하지 않아도 됩니다.

파일 형태를 말해주세요. "만들어줘"보다 "HTML 파일 하나로 만들어줘" 또는 "React 컴포넌트로 만들어줘"가 낫습니다.

"왜"를 설명하면 더 좋은 결과가 나옵니다. "버튼을 크게 해줘"보다 "모바일 사용자가 손가락으로 누르기 편하게 버튼을 크게 해줘"라고 하면 AI가 맥락을 이해하고 더 적절하게 처리합니다.

화면을 캡처해서 보여주세요. Claude Code는 이미지를 볼 수 있습니다. 수정하고 싶은 화면을 캡처해서 "이 화면에서 헤더 부분을 바꿔줘"라고 하면 훨씬 정확합니다.

✏️ 실습: 같은 앱을 3가지 다른 프롬프트로 만들어보고 차이 비교하기

프롬프트의 차이를 직접 체험해봅시다.

1단계: Antigravity에서 내장 터미널을 열고 새 폴더를 만듭니다.

mkdir prompt-test
cd prompt-test
claude

2단계: 세 가지 프롬프트를 순서대로 시도합니다. 하나 만들고 결과를 브라우저에서 확인한 뒤, /clear로 대화를 초기화하고 다음 프롬프트를 시도합니다. 폴더 이름은 헷갈리지 않게 바꿔주세요.

프롬프트 A — 모호하게:

계산기 만들어줘.

프롬프트 B — 기능을 구체적으로:

웹 브라우저에서 동작하는 계산기를 만들어줘.
- 숫자 버튼 0~9
- 사칙연산 버튼 +, -, ×, ÷
- 등호(=)와 초기화(C) 버튼
- 상단에 계산 결과를 보여주는 화면
- 버튼 클릭으로 동작
- HTML 파일 하나로 만들어줘

프롬프트 C — 기능 + 디자인 + 제약 조건:

웹 브라우저에서 동작하는 계산기를 만들어줘.
- 숫자 버튼 0~9
- 사칙연산 버튼 +, -, ×, ÷
- 등호(=)와 초기화(C) 버튼
- 상단에 계산 결과를 보여주는 화면
- 버튼 클릭으로 동작
- HTML 파일 하나로, 외부 라이브러리 없이 만들어줘

디자인:
- 어두운 배경(#1c1c1e)
- 버튼은 둥글게, 숫자는 회색, 연산자는 주황색
- iPhone 계산기 앱 느낌으로

3단계: 세 결과를 비교합니다. 확인할 포인트입니다.

A는 어떤 기술로 만들어졌나요? 어떻게 생겼나요?
B와 A를 비교했을 때 어떤 부분이 달라졌나요?
C는 B보다 어떤 부분이 더 내 의도에 가까운가요?

같은 Claude Code, 같은 AI 모델인데 프롬프트 하나가 결과를 어떻게 바꾸는지 느껴보세요.

4장: AI와 대화 전략

프롬프트를 잘 쓰는 것만큼, AI와 대화하는 방식도 결과에 큰 영향을 줍니다. 같은 작업을 시키더라도 어떤 순서로, 어떤 모드에서, 얼마나 많은 맥락을 주느냐에 따라 결과가 달라집니다.

한 번에 다 시키기 vs 단계별로 시키기

AI에게 일을 시키는 방식은 크게 두 가지입니다.

한 번에 다 시키기는 원하는 걸 한 프롬프트에 전부 담는 방식입니다.

투두 앱을 만들어줘.
할 일 추가, 완료 체크, 삭제 기능이 있고,
localStorage에 저장해서 새로고침해도 유지되게 해줘.
디자인은 흰 배경에 카드 스타일로.

범위가 명확하고 내가 원하는 게 확실할 때 빠릅니다.

단계별로 시키기는 하나씩 확인하면서 진행합니다.

먼저 투두 앱 화면 레이아웃만 만들어줘. 기능은 아직 넣지 마.

→ 결과 확인 →

좋아. 이제 할 일 추가 기능을 넣어줘.

→ 결과 확인 →

완료 체크와 삭제 기능도 추가해줘.

어떤 방식을 써야 할지 판단 기준은 이렇습니다.

작업 범위가 작고 명확하면 한 번에 시키세요. 여러 기능이 엮여 있거나, 중간 결과를 보면서 방향을 조정하고 싶거나, 잘못 만들어졌을 때 되돌리기 부담스러운 작업이면 단계별로 시키세요.

잘 모르겠으면 단계별이 안전합니다. 한 번에 많이 시킬수록 의도를 잘못 해석할 확률이 높아지고, 잘못된 결과를 되돌리는 데 시간이 더 듭니다.

Reverse Prompting — AI에게 먼저 질문하게 하기

보통은 내가 AI에게 지시합니다. Reverse prompting은 순서를 뒤집습니다. 내가 지시하기 전에, AI에게 먼저 질문하게 합니다.

중고 거래 플랫폼을 만들려고 해.
구현하기 전에 내가 뭘 빠뜨리고 있는지 확인하고 싶어.
물어봐줘.

그러면 AI가 이런 식으로 물어봅니다.

거래는 직거래인가요, 택배 거래인가요, 아니면 둘 다 지원하나요?

대답하면 다음 질문으로 넘어갑니다.

결제는 플랫폼 안에서 처리하나요, 아니면 사용자끼리 알아서 하나요?

이걸 몇 번 반복하면, 혼자서는 미처 생각하지 못했던 것들이 드러납니다. 직거래면 위치 기능이 필요하고, 플랫폼 결제면 에스크로가 필요하고, 둘 다 지원하면 분기 처리가 필요합니다. 질문에 답하다 보면 자연스럽게 요구사항이 정리됩니다.

언제 쓰면 좋은가

내가 뭘 원하는지 아직 정리가 안 됐을 때 씁니다. "이런 거 만들고 싶긴 한데…" 정도만 있고 세부 사항이 떠오르지 않을 때. 프롬프트 입력창 앞에서 뭘 써야 할지 막막할 때.

반대로, 원하는 게 이미 뚜렷하면 굳이 쓸 필요 없습니다. "버튼 색 빨간색으로 바꿔줘"에 reverse prompting을 붙이면 시간만 낭비합니다.

권한 모드 — AI에게 얼마나 맡길 것인가

Claude Code가 파일을 만들거나 명령어를 실행할 때 매번 "이거 해도 될까요?"라고 물어봅니다. 처음에는 이게 안전하게 느껴지지만, 작업에 집중하고 있을 때는 흐름이 끊깁니다.

권한 모드는 이 허락의 범위를 조절하는 설정입니다. "매번 물어봐"부터 "알아서 해"까지 단계가 있습니다.

바이브코더가 쓰는 세 가지 모드

모드	AI가 허락 없이 할 수 있는 것	언제 쓰나
default	파일 읽기만	처음 시작할 때
**acceptEdits	파일 읽기 + 수정	기본으로 쓰는 모드**
auto	거의 모든 것 (위험한 작업만 자동 차단)	큰 작업을 통째로 맡기고 싶을 때
bypassPermissions	모든 것 (제한 없음)	모든 확인을 건너뛰고 싶을 때

default는 파일을 읽는 것만 자동이고, 수정할 때마다 허락을 구합니다. Claude Code를 처음 켜면 이 모드입니다. 매번 확인 창을 누르느라 흐름이 끊기기 때문에 잘 사용하지 않습니다.

acceptEdits를 기본으로 쓰세요. 파일 수정까지 자동으로 진행하고, 명령어 실행(npm install 같은 것)만 허락을 구합니다. 코드 작업의 대부분은 파일 수정이기 때문에, 이 모드가 속도와 안전 사이에서 가장 균형이 좋습니다.

auto는 AI가 대부분의 작업을 알아서 처리합니다. 백그라운드에서 위험한 작업인지 자동으로 판단해서, 문제가 될 수 있는 것만 멈추고 물어봅니다. "이 기능 만들어줘"라고 하고 잠깐 자리를 비워도 됩니다. auto를 적극 추천합니다.

bypassPermissions는 어떤 작업이든 확인 없이 바로 실행합니다. auto와 달리 위험한 작업도 멈추지 않습니다. 확인 창 없이 완전히 자동으로 돌리고 싶을 때 선택할 수 있습니다.

이 외에 CI 파이프라인용 dontAsk 모드도 있습니다.

터미널(CLI)에서 전환하기

대화 중에 Shift+Tab을 누르면 모드가 순환됩니다.

기본 상태 (default)
Shift+Tab 한 번: acceptEdits — 터미널 하단에 ⏵⏵ accept edits on 표시
Shift+Tab 한 번 더: Plan 모드 — 터미널 하단에 ⏸ plan mode on 표시 (다음 섹션에서 설명)
Shift+Tab 한 번 더: auto 모드 — 터미널 하단에 ⏵⏵ auto mode on 표시

별도의 실행 옵션이나 설정 없이 Shift+Tab만으로 바로 전환할 수 있습니다.

Antigravity에서 전환하기

프롬프트 입력창 하단에 모드 선택 버튼이 있습니다. 클릭하면 드롭다운으로 모드를 바꿀 수 있습니다.

단, auto 모드는 기본적으로 이 목록에 나타나지 않습니다. 활성화하려면 설정에서 한 가지를 켜야 합니다.

Cmd+Shift+P(macOS) 또는 Ctrl+Shift+P(Windows)를 누릅니다
"Settings"를 검색해서 Settings를 엽니다
검색창에 claude code를 입력합니다
Allow dangerously skip permissions 항목을 찾아 체크합니다

이 설정을 켜면 모드 선택 드롭다운에 auto가 추가됩니다. 역시 Team 플랜이 아니면 나타나지 않습니다.

기본 시작 모드를 바꾸고 싶으면 같은 설정 화면에서 Initial Permission Mode 항목을 원하는 모드로 변경합니다. acceptEdits로 바꿔두면 매번 Shift+Tab을 누를 필요 없이 시작할 때부터 적용됩니다.

Plan 모드

Plan 모드는 AI가 코드를 바로 작성하지 않고, 계획만 먼저 세우도록 하는 모드입니다. 복잡한 기능을 추가하기 전에, 또는 AI가 어떤 방향으로 접근할지 먼저 보고 싶을 때 유용합니다.

Plan 모드는 Shift+Tab을 눌러서 전환하거나, Antigravity에서 모드 선택 드롭다운으로 켤 수 있습니다.

Plan 모드 실제 사용 흐름

(Plan 모드에서)
이 프로젝트에 Google 소셜 로그인을 추가하려고 해.
어떤 파일을 만들고 어떤 순서로 작업해야 하는지 계획을 세워줘.

AI가 코드 없이 계획만 작성합니다. 예를 들면 이런 식으로:

1. Google OAuth 연동 설정
2. 로그인 성공 후 처리
3. 로그인 버튼 UI
4. 로그인 안 한 사용자 접근 차단
순서: 1 → 2 → 3 → 4

계획을 보고 괜찮으면 Shift+Tab으로 Normal 모드로 돌아와서 "좋아, 이대로 진행해줘"라고 말합니다.

Plan 모드는 복잡한 작업에 유용하지만, 작업 범위가 작고 명확할 때는 굳이 쓸 필요 없습니다. "버튼 색 바꿔줘" 같은 간단한 작업은 바로 시키는 게 빠릅니다.

ultrathink

프롬프트에 ultrathink를 포함하면 해당 요청에 한해서만 AI의 사고 깊이를 최대로 높입니다.

ultrathink. 이 인증 시스템의 보안 취약점을 찾아줘.

결제 로직에서 엣지 케이스가 뭐가 있을지 ultrathink해줘.

복잡한 아키텍처 결정, 잡기 어려운 버그, 트레이드오프 분석처럼 AI가 충분히 생각해야 하는 상황에서 씁니다. 그냥 쓰면 되고, 다음 요청부터는 다시 평소 수준으로 돌아옵니다.

세션 전체의 사고 깊이를 조정하고 싶으면 /effort를 입력합니다. low / medium / high 중 선택할 수 있습니다.

알아두면 좋은 슬래시 커맨드

Claude Code에는 /로 시작하는 명령어들이 있습니다. 대화 중 언제든 입력할 수 있습니다.

대화 관리:

/clear — 대화 내용을 전부 지우고 처음부터 시작합니다. 전혀 다른 작업을 시작할 때, 또는 AI가 같은 실수를 반복할 때 씁니다.

/compact — 지금까지의 대화를 요약해서 컨텍스트를 정리합니다. 같은 작업을 이어가는데 대화가 너무 길어졌을 때 씁니다. 요약 방향을 지정할 수도 있습니다.

/compact 인증 관련 변경 사항을 중심으로 요약해줘

/btw — 컨텍스트에 남기지 않고 잠깐 질문할 때 씁니다. 예를 들어 작업 중에 "아, 이 함수 이름이 뭐였더라" 같은 빠른 확인을 할 때 유용합니다. 답변이 대화 히스토리에 포함되지 않아 컨텍스트를 아낄 수 있습니다.

작업 관리:

/init — 프로젝트를 처음 시작할 때 씁니다. 프로젝트 구조를 분석하고 CLAUDE.md 파일을 자동으로 만들어줍니다. 5장에서 자세히 다룹니다.

/effort — thinking 깊이를 조정합니다. low / medium / high 선택.

되돌리기:

Esc — AI가 작업하는 도중에 멈춥니다. 맥락은 유지됩니다.

Esc 두 번 또는 /rewind — 되감기 메뉴가 열립니다. 이전 상태로 대화와 파일을 함께 되돌릴 수 있습니다. Claude Code는 작업할 때마다 체크포인트를 자동으로 저장하기 때문에, 여러 단계 전으로 돌아가는 것도 가능합니다.

정보 확인:

/cost — 현재 대화에서 사용한 토큰 수와 비용을 보여줍니다.

/help — 사용 가능한 모든 명령어 목록을 보여줍니다.

/model — 현재 사용 중인 모델을 바꿉니다.

AI가 틀렸을 때

AI는 틀립니다. 정상입니다. 중요한 건 어떻게 대응하느냐입니다.

에러 메시지가 나올 때

가장 간단한 방법은 에러 메시지를 그대로 붙여넣는 겁니다.

이런 에러가 나. 고쳐줘.

TypeError: Cannot read properties of undefined (reading 'map')
    at ProductList (/src/components/ProductList.jsx:12:20)

에러 메시지에는 어느 파일, 몇 번째 줄인지가 포함되어 있어서 AI가 정확하게 찾아서 수정할 수 있습니다.

결과가 원하는 것과 다를 때

화면을 캡처해서 붙여넣고 설명을 추가합니다.

[스크린샷 첨부]
버튼이 화면 오른쪽 끝에 붙어 있어. 가운데로 옮겨줘.

또는 구체적으로 어디가 다른지 말합니다.

메뉴가 모바일에서 겹쳐 보여.
화면 너비가 768px 이하일 때 햄버거 메뉴로 바뀌게 해줘.

같은 실수를 반복할 때

두 번 수정했는데도 같은 문제가 반복되면, 계속 요청을 추가하는 것보다 되돌리고 처음부터 다시 시작하는 게 나을 수 있습니다. 수정을 쌓을수록 코드가 복잡해지고, AI도 앞서 만든 것에 맞추려다 점점 꼬입니다.

1단계: Esc+Esc 또는 /rewind로 파일을 되돌립니다. 되감기 메뉴에서 작업을 시작하기 전 체크포인트를 선택하면 코드가 그 시점으로 돌아갑니다.

2단계: /clear로 대화를 초기화합니다. 오염된 맥락을 버리고 백지에서 시작합니다.

/clear

3단계: 이번에 파악한 것을 반영해서 더 구체적인 프롬프트로 다시 시작합니다.

상품 목록 페이지에서 상품이 없을 때 에러가 나.
데이터가 아직 안 불러와졌거나 비어있을 때도
에러 없이 빈 화면이 나오도록 처리해줘.

돌아가는 상태에서 다시 시작하는 것이 어설프게 고친 코드를 붙잡고 씨름하는 것보다 빠를 수 있습니다.

작업 중간에 멈추고 싶을 때

AI가 작업 중인데 방향이 잘못됐다 싶으면 Esc를 누릅니다. 대화 맥락은 유지되고 파일 수정만 멈춥니다.

"아, 이 방향이 아니었어"라고 생각했을 때 Esc+Esc 또는 /rewind로 되감기 메뉴를 열면 파일과 대화를 이전 상태로 되돌릴 수 있습니다.

컨텍스트 관리

컨텍스트란 AI가 현재 기억하고 있는 정보입니다. 지금까지 나눈 대화, AI가 읽은 파일, 실행한 명령어의 결과가 모두 포함됩니다.

AI는 코드는 읽지만 맥락은 모른다

Claude Code는 CLAUDE.md를 읽고, 필요하면 파일을 직접 열어서 프로젝트 구조를 파악합니다. 기술 스택이 뭔지, 어떤 파일이 있는지는 스스로 확인합니다.

하지만 이 작업을 왜 하는지, 어떤 제약이 있는지, 지금 어떤 상태인지는 코드를 읽어도 알 수 없습니다. 그건 여러분만 알고 있습니다.

"결제 버튼 추가해줘"라는 요청에서 AI가 코드를 아무리 읽어도 알 수 없는 것들이 있습니다. 이게 무료 플랜 사용자에게만 보여야 하는지, 특정 조건에서 비활성화돼야 하는지, 지금 있는 버튼을 교체하는 건지 새로 추가하는 건지. 이런 것들이 맥락입니다.

맥락이 결과의 질을 결정한다

같은 요청이라도 어떤 맥락을 주느냐에 따라 결과가 완전히 달라집니다.

에러 디버깅 예시를 보겠습니다.

맥락 없는 버전:

에러 고쳐줘.

맥락 있는 버전:

결제 완료 후 주문 내역 페이지로 리다이렉트가 안 돼.
결제 성공 콜백에서 router.push('/orders')를 호출하는데
아무 반응이 없어. 에러 메시지는 없고 그냥 결제 페이지에 머물러 있어.

첫 번째는 AI가 "어떤 에러인가요?"부터 되물어야 합니다. 두 번째는 바로 원인을 찾습니다.

기능 추가 예시도 비교해봅니다.

맥락 없는 버전:

검색 기능 만들어줘.

맥락 있는 버전:

일감 목록 페이지에 검색 기능을 추가하려고 해.
클라이언트명과 프로젝트명을 기준으로 실시간 필터링되게 해줘.
서버 요청 없이 이미 불러온 데이터 안에서 필터링하면 돼.

두 번째는 어느 페이지인지, 어떤 기준으로 검색하는지, 어떤 방식으로 동작해야 하는지를 알려줬습니다. AI가 코드를 확인한 뒤 바로 원하는 방향으로 만들 수 있습니다.

맥락으로 챙겨야 할 것은 세 가지입니다. 지금 어떤 상황인지(현재 상태), 왜 이걸 하는지(목적), 어떻게 동작해야 하는지(제약과 방향). 기술 스택이나 프로젝트 배경은 AI가 직접 파악합니다.

컨텍스트에는 한계가 있습니다. 대화가 너무 길어지면 처음에 한 말을 잊거나, 관련 없는 정보에 혼동을 일으키기 시작합니다.

한 대화에 하나의 작업

대화 하나에 기능 하나, 또는 버그 수정 하나를 담는 게 좋습니다.

대화가 길어질수록 AI의 성능이 떨어집니다. 로그인 기능을 만들고 나서 같은 대화에서 결제 기능까지 이어서 만들면, 앞쪽 대화와 맥락이 섞이면서 응답 품질이 낮아집니다.

다른 목적의 작업을 시작할 때는 /clear로 새 대화를 시작합니다.

현재 컨텍스트가 얼마나 찼는지는 /context로 확인할 수 있습니다. 전체 용량 대비 사용량을 보여주므로, 대화를 이어갈지 정리할지 판단할 때 유용합니다.

컨텍스트를 아끼는 방법

관계없는 작업 사이에 /clear를 씁니다. 투두 앱 작업을 마치고 이제 전혀 다른 랜딩 페이지를 만들 거라면, 이전 투두 앱 대화가 컨텍스트에 남아있을 이유가 없습니다.

같은 작업을 이어가는 중에 대화가 길어지면 /compact를 씁니다. AI가 지금까지의 대화를 요약해서 중요한 내용만 남기고 정리합니다.

잠깐 확인이 필요할 때 /btw를 씁니다. 컨텍스트에 기록을 남기지 않으므로, 단순 질문을 하더라도 컨텍스트가 커지지 않습니다.

에러 메시지는 텍스트로 붙여넣습니다. 스크린샷은 텍스트보다 컨텍스트를 훨씬 많이 차지합니다. 터미널 에러나 콘솔 로그는 복사해서 텍스트로 전달하는 게 낫습니다. 스크린샷은 UI 레이아웃 확인처럼 시각 정보가 꼭 필요할 때 씁니다.

매번 반복하는 맥락은 CLAUDE.md에 적어둡니다. 새 대화를 시작할 때마다 "이 프로젝트는 Supabase를 쓰고, 포트는 3000이고…"라고 매번 설명하면 그만큼 컨텍스트를 소모합니다. 적어두지 않으면 AI가 매번 스스로 파악해야 하는데, 이 과정에서도 컨텍스트를 사용합니다. CLAUDE.md에 한 번 적어두면 /clear 후에도 AI가 자동으로 읽습니다. 자세한 내용은 5장에서 다룹니다.

컨텍스트가 꽉 찼을 때

Claude Code가 자동으로 대화를 압축합니다. 이때 중요한 코드와 결정 사항을 우선 보존합니다. 압축 방식에 대해 직접 지시를 줄 수도 있습니다.

/compact 지금까지 만든 기능 목록과 데이터베이스 구조는 반드시 보존해줘

바이브코딩에서 사람의 역할

AI가 코드를 쓴다면, 사람은 무엇을 하는 걸까요?

방향을 정합니다. 무엇을 만들지, 어떤 기능이 필요한지, 어떤 순서로 만들지를 결정하는 건 여러분입니다. AI는 지시받은 걸 만들 뿐, 무엇을 만들어야 하는지는 모릅니다.

결과를 확인합니다. AI가 만든 것을 직접 써봅니다. 화면을 열어보고, 버튼을 클릭해보고, 엣지 케이스를 테스트해봅니다. AI는 코드를 만들고 나면 그게 실제로 잘 동작하는지 관심이 없습니다. 확인하는 건 여러분의 몫입니다.

판단합니다. "이 디자인이 사용자에게 직관적인가?", "이 기능이 정말 필요한가?", "이 에러가 지금 고쳐야 하는 건가?" 이 판단은 AI가 내릴 수 없습니다.

코드를 쓰는 능력이 AI로 대체되면서, 오히려 무엇을 만들지 결정하는 능력과 만들어진 것을 검증하는 능력이 더 중요해졌습니다. 바이브코딩은 코딩 능력이 없어도 된다는 게 아니라, 코딩 능력보다 제품을 보는 눈이 더 중요해졌다는 뜻입니다.

할루시네이션과 검증

AI는 가끔 틀린 정보를 자신 있게 말합니다. 이걸 할루시네이션이라고 합니다.

코딩에서 할루시네이션은 이런 식으로 나타납니다.

존재하지 않는 npm 패키지를 설치하려 합니다. (npm install react-magic-form 같은 것)
없는 API를 호출합니다. (함수 이름이나 파라미터가 실제와 다릅니다)
특정 버전에서 동작하지 않는 문법을 씁니다.
자신이 이미 만들었다고 생각하는 기능이 실제로는 없습니다.

AI가 "이렇게 하면 됩니다"라고 자신 있게 말해도, 실제로 에러가 나는 경우가 있습니다.

다행히 해결법은 단순합니다. 실행해보면 됩니다.

코드를 실행했을 때 에러가 나면 그걸 AI에게 보여주면 됩니다. 에러 메시지가 없는데 동작이 이상하면 그 증상을 설명합니다. Claude Code 환경에서는 AI가 직접 실행하고 에러를 보기 때문에, 할루시네이션이 생기면 AI 스스로 발견하고 수정하는 경우가 많습니다.

완전히 막는 방법은 없습니다. "AI가 만든 것도 직접 확인해봐야 한다"는 습관 하나면 충분합니다.

5장: CLAUDE.md — AI에게 나를 기억시키기

CLAUDE.md가 왜 중요한가

Claude Code는 새 대화를 시작할 때마다 아무것도 모릅니다. 어제 어떤 작업을 했는지, 이 프로젝트가 어떤 기술 스택을 쓰는지, 코드를 어떻게 작성하길 원하는지 — 전부 처음부터 알려줘야 합니다.

매번 같은 말을 반복하는 건 불편합니다.

이 프로젝트는 Next.js 15를 쓰고 있어.
Supabase를 데이터베이스로 써.
컴포넌트는 /components 폴더에 넣어.
주석은 한국어로 작성해.
외부 라이브러리는 추가하기 전에 먼저 물어봐.

CLAUDE.md는 이걸 한 번만 적어두면 해결됩니다. 프로젝트 폴더에 CLAUDE.md 파일을 만들어두면 Claude Code가 대화를 시작할 때 자동으로 읽습니다. 이후부터는 매번 설명하지 않아도 됩니다.

/init — 자동으로 만들기

프로젝트 폴더에서 Claude Code를 켜고 /init을 입력하면 자동으로 CLAUDE.md를 만들어줍니다.

/init

Claude Code가 프로젝트 구조를 분석해서 빌드 시스템, 테스트 프레임워크, 코드 패턴 등을 파악하고 초안을 작성합니다. 처음부터 직접 쓰는 것보다 이 초안을 수정하는 게 훨씬 빠릅니다.

좋은 CLAUDE.md의 구조

CLAUDE.md에 무엇을 적을지 막막하다면 이 항목들을 참고하세요.

넣어야 할 것들

프로젝트 개요 — 이 프로젝트가 무엇인지 한두 문장으로.

# 프로젝트 개요
온라인 독서 모임 플랫폼. 모임 개설, 책 선정, 참여자 관리 기능을 제공한다.

기술 스택 — 어떤 프레임워크와 라이브러리를 쓰는지. Claude Code가 파악하지 못할 수도 있는 것들을 명시합니다.

## 기술 스택
- Frontend: Next.js 15 (App Router), TypeScript, Tailwind CSS
- Backend: Supabase (PostgreSQL, Auth, Storage)
- 배포: Vercel

자주 쓰는 명령어 — 개발 서버 실행, 빌드, 테스트 명령어 등.

## 명령어
- 개발 서버: npm run dev (포트 3000)
- 빌드: npm run build
- DB 스키마 반영: npm run db:migrate

코딩 규칙 — 이 프로젝트에서만 통용되는 규칙들. Claude Code가 코드를 읽어도 알기 어려운 것들입니다.

## 코딩 규칙
- 주석은 한국어로 작성
- 외부 라이브러리 추가 전 반드시 먼저 물어볼 것

폴더 구조 — 어디에 무엇을 두는지 약속.

## 폴더 구조
- /app — 페이지 라우트
- /components — 재사용 컴포넌트
- /lib — 유틸리티, API 클라이언트
- /types — TypeScript 타입 정의

자주 실수하는 것들 — AI가 반복적으로 틀리는 부분을 발견할 때마다 추가.

## 주의사항
- Supabase 클라이언트는 /lib/supabase.ts에서 import할 것, 직접 초기화 금지
- 환경변수는 NEXT_PUBLIC_ 접두사 없이는 클라이언트에서 접근 불가
- useEffect 안에서 직접 fetch 하지 말고 React Query 사용

넣지 말아야 할 것들

파일 내용을 길게 설명하거나, Claude Code가 코드를 읽으면 알 수 있는 것들, "클린 코드를 작성해" 같은 당연한 말들은 빼는 게 낫습니다. CLAUDE.md가 너무 길어지면 Claude Code가 중요한 규칙을 놓칩니다.

공식 문서의 기준은 명확합니다. "이 항목을 지우면 Claude Code가 실수를 할까?" — 그렇지 않으면 지웁니다.

계속 다듬어가기

Claude Code를 만든 Boris Cherny는 이렇게 말합니다.

"AI를 교정할 때마다 마지막에 'CLAUDE.md를 업데이트해서 이 실수를 다시 하지 않게 해'라고 말하세요."

CLAUDE.md는 한 번 쓰고 끝내는 게 아닙니다. 프로젝트를 만들어가면서 계속 다듬습니다.

실제 흐름은 이렇습니다.

Claude Code가 컴포넌트를 엉뚱한 폴더에 만들었습니다.

그건 /components/ui 폴더에 넣어야 해.
이 규칙을 CLAUDE.md에도 추가해줘.

Claude Code가 영어 주석을 썼습니다.

주석은 항상 한국어로 써줘.
CLAUDE.md에 이 규칙 추가해줘.

이렇게 하면 같은 실수가 반복되지 않습니다. 시간이 지날수록 CLAUDE.md가 정제되고, AI가 점점 더 여러분의 방식대로 작업하게 됩니다.

CLAUDE.md 파일 위치

CLAUDE.md는 여러 위치에 둘 수 있습니다.

프로젝트 루트 (./CLAUDE.md) — 가장 일반적입니다. 해당 프로젝트에서만 적용됩니다. Git에 올려서 팀원과 공유할 수 있습니다.

홈 폴더 (~/.claude/CLAUDE.md) — 모든 프로젝트에 공통으로 적용됩니다. "항상 한국어로 답해", "코드 설명은 간결하게" 같은 개인 스타일을 적어두기 좋습니다.

하위 폴더에도 CLAUDE.md를 둘 수 있습니다. Claude Code가 그 폴더의 파일을 작업할 때 자동으로 읽습니다. 규모가 큰 프로젝트에서 특정 모듈만의 규칙을 따로 관리할 때 유용합니다.

✏️ 실습: 내 프로젝트용 CLAUDE.md 만들어보기

1단계: Antigravity에서 내장 터미널을 열고 새 폴더를 만듭니다.

mkdir my-project
cd my-project
claude

2단계: /init을 입력합니다.

/init

Claude Code가 폴더를 분석해서 CLAUDE.md 초안을 만들어줍니다. 지금은 빈 폴더라서 기본 구조만 나올 겁니다.

3단계: 만들어진 CLAUDE.md를 Antigravity에서 확인합니다. 왼쪽 파일 목록에서 CLAUDE.md를 클릭합니다.

4단계: Claude Code에게 내 프로젝트에 맞게 수정을 요청합니다.

CLAUDE.md를 수정해줘.
이 프로젝트는 Next.js + Supabase로 만드는 블로그야.
기술 스택, 폴더 구조, 코딩 규칙을 추가해줘.
주석은 한국어, 외부 라이브러리 추가 전에 먼저 물어볼 것도 넣어줘.

5단계: 결과를 확인하고, 빠진 게 있으면 직접 추가합니다. Antigravity에서 CLAUDE.md를 클릭하고 직접 수정해도 됩니다.

이렇게 만든 CLAUDE.md가 다음 장부터 시작할 실전 프로젝트의 기반이 됩니다.

6장: 아이디어를 설계로 바꾸는 방법

"이런 거 만들고 싶어"에서 시작하기

모든 프로젝트는 한 문장에서 시작합니다.

"우리 동네 맛집을 모아서 보여주는 사이트를 만들고 싶어." "프리랜서 일감 관리를 할 수 있는 대시보드가 있으면 좋겠어." "우리 동아리 일정을 공유하는 앱을 만들고 싶어."

완벽한 기획서가 없어도 됩니다. 막연한 아이디어도 됩니다. 이 한 문장을 가지고 AI와 대화하면서 구체화하면 됩니다.

아이디어를 AI가 이해할 수 있게 정리하는 방법

한 문장짜리 아이디어를 그대로 던지면 AI도 막막합니다. 아래 세 가지 질문에 답하면 AI가 구체적인 설계를 만들 수 있습니다.

누가 쓰는가? 나 혼자 쓸 건지, 소수의 지인이 쓸 건지, 불특정 다수가 쓸 건지. 이에 따라 로그인 기능이 필요한지, 관리자 페이지가 필요한지가 달라집니다.

핵심 기능은 뭔가? 이 서비스가 반드시 해야 하는 일 2~3가지. "없으면 이 서비스가 의미 없다"는 것들만 추려냅니다.

어떤 화면이 필요한가? 사용자가 어떤 순서로 이 서비스를 쓰는지 흐름을 생각해봅니다.

이걸 AI에게 이렇게 전달합니다.

나는 프리랜서 일감 관리 대시보드를 만들려고 해.

- 사용자: 나 혼자 씀
- 핵심 기능:
  - 일감을 등록하고 상태(진행중/완료/미수금)를 관리
  - 월별 수입을 차트로 보여주기
  - 클라이언트별 히스토리 조회

어떤 화면들이 필요할지 정리해줘.

완벽할 필요 없습니다. AI가 빠진 부분을 물어보기도 하고, 대화하면서 채워나가면 됩니다.

AI에게 인터뷰 시키기

뭘 만들지 아직 완전히 정리하지 못했다면, 4장에서 다룬 reverse prompting을 써봅니다. AI에게 먼저 질문하게 하는 방법입니다.

나는 [간단한 설명]을 만들려고 해.
내가 놓친 부분을 찾아내기 위해 질문해줘.
기술 구현, UI/UX, 엣지 케이스, 트레이드오프에 대해 물어봐.
당연한 질문 말고, 내가 미처 생각 못 했을 어려운 부분을 파고들어줘.

이렇게 하면 혼자 생각할 때 놓쳤던 것들 — 오프라인일 때는 어떻게 되는지, 사용자가 실수로 삭제하면 어떻게 할 건지, 여러 사람이 동시에 편집하면 어떻게 되는지 같은 것들 — 을 미리 발견할 수 있습니다.

MVP란 무엇인가

MVP는 Minimum Viable Product, 최소 기능 제품입니다. "핵심 기능만 있는 가장 단순한 버전"입니다.

프리랜서 대시보드라면 이렇게 나눌 수 있습니다.

MVP에 포함:

일감 등록하고 상태 바꾸기

나중에 추가:

월별 수입 차트
클라이언트별 히스토리
이메일 알림
모바일 앱

처음부터 모든 기능을 만들려고 하면 끝이 없습니다. 완성하지 못하고 지치는 경우가 많습니다. MVP를 먼저 만들고, 직접 써보면서 "이게 더 필요하다"고 느끼는 것을 하나씩 추가하는 게 훨씬 현실적입니다.

AI에게 MVP를 정해달라고 할 수 있습니다.

이 프로젝트의 MVP를 정해줘.
가장 핵심적인 기능만 남기고, 나머지는 '나중에 추가'로 분류해줘.
판단 기준은 "이게 없으면 이 서비스가 의미 없다"야.

프론트엔드, 서버, 데이터베이스

웹서비스는 크게 세 부분으로 나뉩니다.

프론트엔드는 브라우저에 보이는 화면입니다. 버튼, 텍스트, 이미지, 입력 폼 — 눈에 보이는 모든 것입니다.

서버는 화면 뒤에서 일하는 부분입니다. 로그인 처리, 데이터 저장, 이메일 발송 같은 작업을 합니다. 사용자 눈에는 보이지 않습니다.

데이터베이스는 데이터가 실제로 저장되는 곳입니다. 사용자 계정 정보, 게시글, 주문 내역 같은 것들이 여기에 저장됩니다.

인스타그램으로 예를 들면: 사진을 올리는 화면이 프론트엔드, "이 사진을 이 사용자의 계정에 저장해"라는 명령을 처리하는 게 서버, 사진 파일과 댓글이 실제로 저장되는 게 데이터베이스입니다.

AI에게 "일감 관리 대시보드 만들어줘"라고 하면 세 부분을 한꺼번에 만들어줍니다. "프론트엔드에 버튼을 추가했습니다" 같은 말을 할 때 무슨 뜻인지 이해하는 정도면 충분합니다.

AI의 산출물과 소프트웨어가 동작하는 방식

AI에게 "투두 앱 만들어줘"라고 하면 AI는 텍스트 파일들을 만듭니다. 사람이 읽을 수 있는 문자로 작성된 명령어 묶음입니다. 이걸 코드라고 합니다.

브라우저나 서버는 이 코드를 읽고 해석해서 실제로 동작시킵니다. 버튼을 클릭하면 무슨 일이 일어나는지, 데이터를 어디에 저장하는지, 화면을 어떻게 그리는지가 전부 이 파일들 안에 적혀 있습니다. 즉 AI가 만드는 산출물은 코드 파일이고, 그 파일을 컴퓨터가 실행하면 소프트웨어가 됩니다.

바이브코딩에서 이 파일들을 직접 읽거나 수정할 일은 거의 없습니다. AI가 작성하고, 브라우저에서 결과를 확인하면 됩니다.

기술 스택 추천받기

기술 스택이란 프로젝트를 만드는 데 쓰는 도구들의 조합입니다. 어떤 프레임워크를 쓰고, 데이터베이스는 뭘 쓰고, 어디에 배포할지.

이걸 직접 고를 필요 없습니다. AI에게 시키면 됩니다.

프리랜서 일감 관리 대시보드를 만들려고 해.
나는 코딩 경험이 없어.
가장 간단하게 만들 수 있는 기술 스택을 추천해줘.
이유도 설명해줘.

이 가이드에서는 아래 조합을 기준으로 합니다. AI가 가장 잘 알고, 바이브코딩에서 가장 많이 쓰이는 검증된 조합입니다.

Next.js — 프론트엔드와 서버를 한 프로젝트에서 만들 수 있습니다. 페이지를 만들고, API도 만들고, 다 됩니다.

Supabase — 데이터베이스와 로그인 기능을 제공합니다. 별도의 서버를 직접 구축하고 관리할 필요가 없습니다. 대시보드에서 클릭 몇 번으로 세팅할 수 있습니다.

Vercel — 완성한 프로젝트를 인터넷에 올리는 서비스입니다. GitHub에 코드를 올리면 자동으로 배포해줍니다. 무료 플랜으로 시작할 수 있습니다.

✏️ 실습: 내 아이디어를 AI에게 설명하고 설계까지 정하기

1단계: 만들고 싶은 것을 한 문장으로 적어봅니다. 뭐든 좋습니다. 없으면 "프리랜서 일감 관리 대시보드"를 써도 됩니다.

2단계: Antigravity에서 내장 터미널을 열고 Claude Code를 실행합니다.

mkdir my-project
cd my-project
claude

3단계: 아래 형식으로 아이디어를 전달합니다. 대괄호 안의 내용을 여러분 것으로 바꾸세요.

나는 [만들고 싶은 것]을 만들려고 해.
코딩 경험이 없어서 Claude Code로 바이브코딩 방식으로 만들 거야.

- 사용자: [누가 쓰는지]
- 핵심 기능:
  - [기능 1]
  - [기능 2]
  - [기능 3]

이 프로젝트의 MVP를 정해주고,
어떤 화면들이 필요한지, 어떤 순서로 만들면 좋을지 정리해줘.

4단계: 설계가 나오면 기술 스택도 물어봅니다.

이 프로젝트에 어떤 기술 스택을 쓰면 좋을지 추천해줘.
최대한 단순하게 빠르게 만들 수 있는 조합으로.

5단계: AI가 만든 설계를 읽고, 마음에 안 드는 부분을 수정합니다.

세 번째 화면은 빼줘. 나중에 추가할게.
대신 클라이언트 메모 기능을 MVP에 넣어줘.

이 설계와 기술 스택이 다음 장에서 실제 프로젝트를 초기화하는 기반이 됩니다.

7장: 프로젝트 초기화와 Git

프로젝트 초기화

6장에서 아이디어와 기술 스택을 정했습니다. 이제 실제 코드를 만들 차례입니다.

프로젝트 초기화란 빈 폴더에서 시작해서 필요한 도구들을 설치하고 기본 구조를 잡는 것입니다. 전통적으로는 개발자가 직접 명령어를 입력하며 몇 시간이 걸리던 작업이지만, Claude Code에게 시키면 됩니다.

Next.js와 Supabase를 사용하는 프로젝트를 초기화해줘.
프로젝트 이름은 [이름]이야.
TypeScript를 사용하고, Tailwind CSS도 포함해줘.
바로 개발을 시작할 수 있게 세팅해줘.

Claude Code가 작업하는 동안 이런 것들이 자동으로 처리됩니다.

package.json — 이 프로젝트가 어떤 라이브러리를 쓰는지 기록하는 파일
node_modules/ — 실제 라이브러리 파일들이 설치되는 폴더
next.config.js — Next.js 설정 파일
src/ 또는 app/ — 실제 코드가 들어가는 폴더들

중간중간 "이 명령어를 실행해도 될까요?"라고 물어봅니다. 허용하면 됩니다. 매번 묻는 게 귀찮으면 "Always allow"를 선택합니다.

초기화가 끝나면 Antigravity 왼쪽 파일 목록에 여러 폴더와 파일이 생긴 걸 볼 수 있습니다. 이 파일들이 뭔지 하나하나 이해할 필요 없습니다. AI가 관리합니다.

CLAUDE.md 작성

5장에서 배운 CLAUDE.md를 이 프로젝트에 만들 차례입니다.

/init

Claude Code가 방금 만든 프로젝트 구조를 분석해서 CLAUDE.md 초안을 작성합니다. 만들어진 파일을 Antigravity에서 열어 확인하고, 빠진 규칙이 있으면 추가 요청합니다.

CLAUDE.md에 아래 내용도 추가해줘.
- 주석은 한국어로 작성
- 외부 라이브러리 추가 전 먼저 물어볼 것
- 컴포넌트 파일은 /components 폴더에

이제부터 새 대화를 시작할 때마다 Claude Code가 이 파일을 자동으로 읽습니다.

린트 — 코드 맞춤법 검사기

글을 쓸 때 맞춤법 검사기가 빨간 밑줄로 오타를 알려주듯, 코드에도 비슷한 도구가 있습니다. 린트(lint)라고 부릅니다.

린트는 코드를 실행하기 전에 문제를 잡아줍니다. 예를 들어:

만들어놓고 안 쓰는 변수
빠뜨린 설정
나중에 버그가 될 수 있는 위험한 패턴

Next.js로 프로젝트를 초기화하면 ESLint라는 린트 도구가 자동으로 포함됩니다. 별도로 설치할 필요 없습니다.

Antigravity에서 보이는 밑줄

Antigravity(VS Code)에서 코드를 열면 노란색이나 빨간색 밑줄이 보일 때가 있습니다. 이것도 린트가 표시하는 것입니다. 밑줄 위에 마우스를 올리면 무엇이 문제인지 설명이 나옵니다. 역시 그대로 캡처하거나 복사해서 AI에게 주면 됩니다.

CLAUDE.md에 린트 규칙 추가하기

커밋하기 전에 린트를 항상 통과시키고 싶다면 CLAUDE.md에 규칙을 넣어둡니다.

CLAUDE.md에 아래 규칙을 추가해줘.
- 코드를 수정한 뒤에는 npm run lint를 실행해서 경고가 없는지 확인할 것

이렇게 하면 Claude Code가 코드를 고친 뒤 스스로 린트를 돌려서 문제를 잡아줍니다.

개발 서버 실행하기

코드를 만들기 전에 개발 서버를 먼저 이해해야 합니다.

개발 서버는 내 컴퓨터에서만 돌아가는 임시 웹서버입니다. 인터넷에 올리지 않아도 브라우저에서 프로젝트를 볼 수 있게 해줍니다. 코드를 수정하면 브라우저가 자동으로 새로고침됩니다.

Antigravity 하단 터미널에서 + 버튼을 눌러 새 터미널 탭을 열고:

npm run dev

터미널에 아래처럼 나옵니다.

▲ Next.js 15.0.0
- Local:    http://localhost:3000
- Network:  http://192.168.0.10:3000

✓ Ready in 1.2s

http://localhost:3000을 브라우저 주소창에 입력하면 프로젝트 화면이 열립니다. localhost는 "내 컴퓨터"라는 뜻입니다.

개발 서버는 작업하는 동안 계속 켜두면 됩니다. Claude Code 대화는 다른 터미널 탭에서 진행합니다. 서버를 끄려면 해당 탭에서 Ctrl+C를 누릅니다.

첫 페이지 만들기

개발 서버가 켜진 상태에서 Claude Code 탭으로 이동해 첫 화면을 만듭니다.

메인 페이지를 만들어줘.
- 상단에 네비게이션 바 (로고, 메뉴)
- 가운데에 서비스 이름과 한 줄 설명
- 깔끔하고 모던한 디자인으로

코드가 수정되면 브라우저가 자동으로 새로고침됩니다. 직접 새로고침 버튼을 누르지 않아도 됩니다.

화면을 보고 수정하고 싶은 부분이 있으면 그대로 말합니다.

헤더 배경색을 짙은 남색으로 바꿔줘.
메뉴 항목이 너무 붙어 있어. 간격 넓혀줘.

화면을 캡처해서 붙여넣고 말하면 더 정확합니다.

[스크린샷 첨부]
이 레이아웃에서 버튼을 오른쪽 위로 옮겨줘.

Git과 GitHub

코드를 만들다 보면 실수가 납니다. AI가 코드를 잘못 수정해서 잘 되던 기능이 갑자기 안 될 때, "어제 잘 되던 버전으로 돌아가고 싶다"는 생각이 듭니다.

Git이 이걸 해줍니다. 게임의 세이브 포인트라고 생각하면 됩니다. 중요한 시점마다 저장해두면 언제든 그 시점으로 돌아갈 수 있습니다. 이 저장 행위를 커밋(commit)이라고 합니다.

GitHub는 이 커밋들을 인터넷에 올려두는 서비스입니다. 내 컴퓨터가 고장 나도 코드가 사라지지 않고, 나중에 배포할 때도 GitHub에서 가져다 씁니다.

GitHub 계정 만들기

아직 GitHub 계정이 없다면 https://github.com 에서 먼저 만들어야 합니다. 이메일 주소로 무료로 가입할 수 있습니다.

Git 명령어는 외울 필요 없음

Claude Code에게 시키면 됩니다.

지금까지 만든 코드를 Git으로 저장하고 GitHub에 올려줘.
커밋 메시지는 "프로젝트 초기화 및 메인 페이지 생성"으로 해줘.

Claude Code가 변경 사항을 확인하고 커밋 후 GitHub에 올려줍니다.

언제 커밋할까

기능 하나를 완성했을 때, 배포하기 직전, 하루 작업을 마칠 때 커밋합니다. 자주 할수록 좋습니다. 세이브 포인트가 촘촘할수록 되돌아갈 지점이 많아집니다.

처음 GitHub에 올릴 때는 GitHub 계정 인증이 필요합니다. Claude Code가 단계별로 안내하는 대로 따라하면 됩니다.

.gitignore — 올리면 안 되는 파일

Git으로 코드를 저장할 때 올리면 절대 안 되는 파일이 있습니다.

.env 파일입니다. 이 파일에는 데이터베이스 비밀번호, API 키 같은 민감한 정보가 들어갑니다. GitHub에 올리는 순간 전 세계 누구나 볼 수 있게 됩니다. 실제로 이 실수로 해킹을 당하거나 엄청난 서비스 요금이 청구되는 사고가 매우 자주 일어납니다.

.gitignore 파일이 이 문제를 막아줍니다. 여기에 적힌 파일과 폴더는 Git이 무시해서 GitHub에 올라가지 않습니다.

프로젝트를 초기화할 때 AI가 .gitignore를 자동으로 만들어주지만, .env가 포함되어 있는지 반드시 확인하세요.

.gitignore에 .env 파일이 포함되어 있는지 확인해줘.
없으면 추가해줘.

이미 실수로 GitHub에 올렸다면 즉시 해당 API 키를 만료시키고 새로 발급해야 합니다. 올라간 것을 지운다고 해결되지 않습니다. GitHub 히스토리에 남기 때문입니다.

✏️ 실습: 프로젝트를 초기화하고 첫 페이지를 만들어 GitHub에 올리기

1단계: 새 폴더를 만들고 Claude Code를 실행합니다.

mkdir my-project
cd my-project
claude

2단계: 프로젝트를 초기화합니다.

Next.js와 Supabase를 사용하는 프로젝트를 초기화해줘.
TypeScript와 Tailwind CSS를 포함하고, 바로 개발 시작할 수 있게 세팅해줘.

작업이 끝나면 Antigravity 왼쪽에 파일들이 생긴 것을 확인합니다.

3단계: CLAUDE.md를 만듭니다.

/init

4단계: .gitignore에 .env가 포함되어 있는지 확인합니다.

.gitignore에 .env가 포함되어 있는지 확인해줘.

5단계: 개발 서버를 켭니다. 새 터미널 탭을 열고:

npm run dev

브라우저에서 http://localhost:3000을 엽니다. 기본 Next.js 화면이 보이면 성공입니다.

6단계: 다른 터미널 탭에서 Claude Code로 메인 페이지를 만듭니다.

메인 페이지를 만들어줘.
내 프로젝트 이름과 간단한 소개, 시작하기 버튼이 있게.
깔끔한 디자인으로.

브라우저에서 변경된 화면을 확인합니다.

7단계: Git으로 저장하고 GitHub에 올립니다.

지금까지 작업한 내용을 커밋하고 GitHub에 올려줘.

이제 프로젝트의 기반이 완성됐습니다. 다음 장에서 핵심 기능을 하나씩 붙여나갑니다.

8장: 핵심 기능 구현

데이터베이스 연결: Supabase로 데이터 저장하기

7장에서 만든 프로젝트는 아직 껍데기입니다. 화면은 있지만 데이터를 저장하거나 불러오는 기능이 없습니다. 브라우저를 닫으면 입력한 내용이 사라집니다.

데이터를 영구적으로 저장하려면 데이터베이스가 필요합니다. 이 가이드에서는 Supabase를 씁니다.

Supabase 계정 및 프로젝트 만들기

1단계: https://supabase.com 에 접속해서 무료 계정을 만듭니다. GitHub 계정으로 가입하면 빠릅니다.

2단계: 로그인 후 "New Project"를 클릭합니다. 프로젝트 이름을 입력하고, Database Password를 설정합니다. 이 비밀번호는 나중에 필요하니 어딘가에 적어두세요. Region은 Northeast Asia (Seoul)을 선택합니다. 한국에서 접속할 때 속도가 빠릅니다.

프로젝트 생성에 1~2분 걸립니다.

3단계: 프로젝트 대시보드에서 두 가지 정보를 복사합니다.

Project URL — Project Overview 화면에 있는 https://xxxxxxxx.supabase.co 형태의 주소. 복사합니다.
Publishable key — 왼쪽 메뉴 하단 "Project Settings" > "API Keys" 페이지에서 sb_publishable_로 시작하는 긴 문자열을 복사합니다.

이 두 가지가 여러분의 프로젝트와 Supabase를 연결하는 열쇠입니다. Publishable key는 브라우저에서 볼 수 있어도 괜찮은 키입니다. sb_secret_으로 시작하는 Secret key는 절대 코드에 넣으면 안 됩니다.

4단계: Claude Code에게 연결을 시킵니다.

Supabase를 이 프로젝트에 연결해줘.
Project URL: [복사한 URL]
Publishable key: [복사한 키]
.env 파일에 저장하고, Supabase 클라이언트 초기화 코드를 만들어줘.

AI가 .env 파일에 키를 저장하고 연결 코드를 세팅합니다.

⚠️ RLS — 데이터베이스 보안 설정

Supabase를 연결하고 바로 쓰기 시작하면 큰 문제가 생길 수 있습니다.

Publishable key는 프론트엔드 코드에 포함되어 누구나 볼 수 있습니다. RLS(Row Level Security)가 없으면 이 키를 가진 사람이 다른 사용자의 데이터까지 읽고 수정할 수 있습니다. 즉 A 사용자가 B 사용자의 일감 데이터를 마음대로 읽고 수정할 수 있는 상황이 됩니다.

RLS는 "이 데이터는 이 사용자만 볼 수 있다"는 규칙을 데이터베이스 단에서 설정하는 기능입니다.

Claude Code에게 맡기면 됩니다.

Supabase 테이블에 RLS 정책을 만들어줘.
로그인한 사용자는 자기 데이터만 읽고, 수정하고, 삭제할 수 있게 해줘.
SQL 코드로 알려줘.

AI가 SQL 코드를 알려주면 Supabase 대시보드에서 적용합니다.

Supabase 대시보드 왼쪽 메뉴에서 "SQL Editor"를 클릭합니다.
AI가 준 SQL 코드를 붙여넣고 "Run"을 클릭합니다.

테이블을 새로 만들 때마다 RLS 설정을 잊지 마세요.

사용자 인증: 로그인/회원가입

대부분의 서비스는 로그인이 필요합니다. 누가 이 데이터의 주인인지 구분해야 하고, RLS도 로그인된 사용자를 기준으로 작동합니다.

Supabase에 인증 기능이 내장되어 있어서 따로 만들 필요 없습니다.

이메일/비밀번호로 회원가입하고 로그인하는 기능을 만들어줘.
- 회원가입 페이지: 이메일, 비밀번호 입력
- 로그인 페이지: 이메일, 비밀번호 입력
- 로그인하면 /dashboard로 이동
- 로그인하지 않은 사용자가 /dashboard에 접근하면 로그인 페이지로 보내줘

완성되면 개발 서버를 켜고 직접 회원가입, 로그인을 테스트합니다. Supabase 대시보드 왼쪽 메뉴 "Authentication" > "Users"에서 가입된 사용자 목록을 확인할 수 있습니다.

소셜 로그인(Google, Kakao 등)을 원하면 추가로 요청할 수 있습니다.

Google 소셜 로그인도 추가해줘.

Supabase 대시보드에서 Google OAuth 설정이 추가로 필요합니다. AI가 단계별로 안내해줄 겁니다.

테이블 만들기

데이터를 저장하려면 Supabase에 테이블을 만들어야 합니다. 스프레드시트의 시트와 비슷합니다. 일감 목록이면 일감 테이블, 게시글이면 게시글 테이블.

Claude Code에게 시키면 됩니다.

프리랜서 일감을 저장할 테이블을 Supabase에 만들어줘.
클라이언트 이름, 금액, 상태(진행중/완료/미수금)를 저장할 수 있어야 해.
필요한 필드는 네가 설계해줘.
SQL 코드로 알려줘. RLS 정책도 같이.

AI가 SQL 코드를 주면 Supabase SQL Editor에서 실행합니다.

CRUD — 생성, 읽기, 수정, 삭제

테이블이 만들어졌으면 이제 데이터를 다루는 기능을 붙입니다. 웹서비스는 결국 아래 네 가지 동작을 합니다.

Create(생성) — 새 데이터를 등록합니다. 일감 등록, 게시글 작성 등.

Read(읽기) — 저장된 데이터를 화면에 보여줍니다. 일감 목록, 게시글 목록 등.

Update(수정) — 기존 데이터를 수정합니다. 일감 상태 변경, 게시글 편집 등.

Delete(삭제) — 데이터를 삭제합니다.

이 네 가지를 합쳐서 CRUD라고 합니다. AI에게 기능을 시킬 때 이 네 가지를 빠짐없이 요청합니다.

일감 관리 기능을 만들어줘.
- 새 일감을 등록하는 폼 (클라이언트 이름, 금액, 상태)
- 등록된 일감을 목록으로 표시
- 목록에서 상태를 변경할 수 있는 드롭다운
- 각 항목에 삭제 버튼
모든 데이터는 Supabase에 저장하고, 페이지를 새로고침해도 유지되게 해줘.

바이브코딩 워크플로우: 계획 → 구현 → 확인 → 수정

기능 하나를 만들 때마다 이 흐름을 반복합니다.

계획: AI에게 뭘 만들지 구체적으로 설명합니다. 필요한 UI 요소, 동작 방식, 데이터 구조를 함께 말합니다.

구현: AI가 코드를 작성합니다. 작업 중에 허락을 요청하면 허용합니다.

확인: 브라우저에서 실제로 동작하는지 확인합니다. 버튼을 클릭하고, 폼을 제출하고, 데이터가 저장됐는지 Supabase 대시보드에서 확인합니다.

수정: 문제가 있으면 구체적으로 말합니다.

일감 등록 버튼을 눌렀는데 아무 반응이 없어.
브라우저 콘솔에는 이런 에러가 나와.
[에러 메시지 붙여넣기]

한 번에 완벽하게 되는 일은 드뭅니다. 2~3번 수정하는 게 정상입니다. 5번 이상 같은 문제를 반복하면 접근 방식을 바꾸거나 /clear 후 새로 시작합니다.

기능 하나가 완성되면 커밋하기 전에 AI에게 리뷰를 시키는 습관을 들이면 좋습니다.

방금 만든 코드를 리뷰해줘.
불필요한 코드, 빠뜨린 에러 처리, 개선할 점이 있으면 알려줘.

AI가 코드를 만들 때는 "동작하게 만드는 것"에 집중합니다. 리뷰를 따로 시키면 한 발 물러서서 전체를 다시 살펴봅니다. 이때 지금은 안 쓰는 코드, 빠뜨린 에러 처리, 보안 허점, 느려질 수 있는 부분, 여러 곳에 반복되는 중복 코드 같은 것들을 잡아냅니다. 문제를 발견하면 바로 고쳐달라고 하면 됩니다.

리뷰까지 끝나면 커밋합니다.

일감 CRUD 기능 완성됐어. 커밋하고 GitHub에 올려줘.

✏️ 실습: 핵심 기능 2~3개를 AI와 함께 구현하기

7장에서 만든 프로젝트에 기능을 추가합니다.

1단계: Supabase 계정을 만들고 프로젝트를 생성합니다. Project URL과 Publishable key를 복사합니다.

2단계: Claude Code에게 Supabase를 연결하도록 시킵니다.

Supabase를 연결해줘.
Project URL: [복사한 URL]
Publishable key: [복사한 키]

3단계: 데이터 테이블을 만들고 RLS를 설정합니다.

[프로젝트에 맞는 테이블]을 만들어줘.
필드는 [필드 목록]이야.
SQL 코드와 RLS 정책도 같이 줘.

Supabase SQL Editor에서 실행합니다.

4단계: 로그인/회원가입 기능을 만듭니다.

이메일/비밀번호로 회원가입하고 로그인하는 기능을 만들어줘.

직접 회원가입을 해보고, Supabase 대시보드 Authentication > Users에서 계정이 생성됐는지 확인합니다.

5단계: 핵심 기능(CRUD)을 요청합니다.

[핵심 기능]을 만들어줘.
데이터는 Supabase에 저장해줘.

브라우저에서 데이터를 입력하고, 새로고침 후에도 남아있는지 확인합니다.

6단계: 기능을 완성하면 커밋합니다.

기능이 2~3개 붙으면 벌써 꽤 쓸 만한 프로젝트가 됩니다. 다음 장에서는 외부 API를 연결해서 직접 만들기 어려운 기능을 가져다 쓰는 방법을 다룹니다.

9장: API 활용하기 — 외부 서비스 연결

API가 뭔가

8장에서 Supabase로 데이터를 저장하고 불러오는 기능을 만들었습니다. 그런데 서비스를 만들다 보면 직접 만들 수 없는 기능이 필요해집니다. 날씨 정보, 결제 처리, AI 텍스트 생성, 지도 표시, 이메일 발송. 이런 기능을 처음부터 만들려면 몇 달이 걸립니다. 하지만 이미 만들어둔 회사들이 있고, 그 기능을 가져다 쓸 수 있습니다.

이때 쓰는 것이 API입니다.

API(Application Programming Interface)는 프로그램끼리 대화하는 방법입니다. 비유하자면 음식점의 주문 창구입니다. 주방에서 어떻게 요리하는지 몰라도, 창구에서 "비빔밥 하나요"라고 말하면 비빔밥이 나옵니다. 주방의 레시피, 재료, 조리 도구를 알 필요 없습니다. 메뉴에 있는 것만 주문하면 됩니다.

API도 같습니다. 날씨 API에 "서울 날씨 알려줘"라고 요청하면 기온, 습도, 날씨 상태가 담긴 데이터가 돌아옵니다. 날씨 데이터를 어디서 수집하고 어떻게 분석하는지 몰라도 됩니다.

요청과 응답

API의 동작 방식은 단순합니다. 요청(request)을 보내면 응답(response)이 돌아옵니다.

요청은 보통 이런 형태입니다.

GET https://api.weather.com/current?city=seoul

GET은 "데이터를 달라"는 뜻이고, 뒤에 오는 주소가 어디에 요청할지를 나타냅니다. ?city=seoul은 "서울 날씨를 달라"는 조건입니다.

응답은 이런 형태로 돌아옵니다.

{
  "city": "Seoul",
  "temperature": 22,
  "condition": "맑음"
}

이 형식을 JSON이라고 합니다. 사람이 읽을 수도 있고 프로그램이 처리할 수도 있는 데이터 형식입니다. { } 안에 이름과 값이 쌍으로 들어갑니다.

요청 방식은 크게 두 가지입니다.

GET — 데이터를 가져올 때 씁니다. 날씨 조회, 뉴스 목록 조회 등.

POST — 데이터를 보낼 때 씁니다. 결제 요청, 이메일 발송, AI에게 질문 보내기 등.

이 두 가지만 알면 대부분의 API를 쓸 수 있습니다. 직접 GET이나 POST를 입력할 일은 없습니다. Claude Code에게 "이 API를 연결해줘"라고 말하면 알아서 코드를 작성합니다.

API 키 — 누가 쓰는지 확인하는 열쇠

대부분의 API는 아무나 쓸 수 없습니다. 회원가입을 하고 API 키를 발급받아야 합니다. API 키는 "이 요청은 이 사람이 보냈다"는 것을 증명하는 고유한 문자열입니다.

sk-abc123def456ghi789...

이런 긴 문자열을 API를 호출할 때마다 함께 보냅니다. API 제공자는 이 키를 보고 누가 얼마나 사용했는지 추적하고, 요금을 부과합니다.

API 키를 다루는 규칙

첫째, .env 파일에 저장합니다. 코드 안에 직접 넣지 않습니다.

# .env
WEATHER_API_KEY=sk-abc123def456ghi789

둘째, GitHub에 올리지 않습니다. 7장에서 배운 .gitignore에 .env가 포함되어 있는지 다시 확인하세요. API 키가 GitHub에 올라가면 다른 사람이 여러분의 키로 API를 마음대로 쓸 수 있고, 여러분에게 요금을 청구합니다.

셋째, 프론트엔드 코드에 넣지 않습니다. 브라우저가 실행하는 코드에 API 키를 넣으면 누구나 개발자 도구로 볼 수 있습니다. API 호출은 서버 쪽 코드(Next.js의 API Route나 Server Action)에서 하고, 브라우저는 서버를 거쳐 결과만 받습니다.

이 규칙이 복잡해 보여도 걱정하지 마세요. Claude Code에게 "API 키를 안전하게 관리해줘"라고 말하면 서버 쪽에서 호출하고 환경변수로 관리하는 코드를 알아서 만듭니다.

API 문서 읽기

API를 쓰려면 그 API의 문서(documentation)를 봐야 합니다. 어떤 주소로 요청해야 하는지, 어떤 값을 보내야 하는지, 어떤 값이 돌아오는지 나와 있습니다. 음식점의 메뉴판과 같습니다. 메뉴판 없이 "아무거나 주세요"라고 하면 안 되듯이, API도 문서에 정의한 대로 요청해야 합니다.

하지만 API 문서는 개발자를 위해 작성한 것이라 처음 보면 어렵게 느낄 수 있습니다. 이때도 Claude Code가 도와줍니다.

[API 문서 URL]
이 API를 사용해서 [원하는 기능]을 만들어줘.

Claude Code가 문서를 읽고 필요한 코드를 작성합니다.

API 문서를 찾지 못하겠으면 먼저 물어볼 수도 있습니다.

날씨 정보를 무료로 가져올 수 있는 API를 추천해줘.
가입 방법과 API 키 발급 방법도 알려줘.

Claude Code로 외부 API 연결하기

실제로 API를 연결하는 과정을 보겠습니다.

예시 1: AI 기능 추가하기

프로젝트에 AI 텍스트 생성 기능을 넣고 싶다면 이렇게 합니다.

1단계: API 키를 발급받습니다. https://console.anthropic.com 에서 Claude API 키를 만들 수 있습니다.

2단계: Claude Code에게 시킵니다.

Claude API를 사용해서 텍스트 요약 기능을 만들어줘.
API 키: [발급받은 키]
- 사용자가 긴 글을 입력하면 3줄로 요약해서 보여줘
- API 키는 .env에 저장하고 서버 쪽에서 호출해줘

Claude Code가 API Route를 만들고, 프론트엔드에서 그 Route를 호출하는 구조로 코드를 작성합니다.

예시 2: 이메일 발송

사용자에게 이메일을 보내는 기능을 추가하고 싶다면:

Resend API로 이메일 발송 기능을 만들어줘.
회원가입하면 환영 이메일을 보내는 기능이야.
API 키: [발급받은 키]

예시 3: 결제 연동

Toss Payments API로 결제 기능을 만들어줘.
테스트 모드로 먼저 구현해줘.

결제처럼 돈이 오가는 API는 대부분 테스트 모드를 제공합니다. 실제 돈이 나가지 않는 가상 환경에서 먼저 개발하고, 완성한 후에 실제 모드로 전환합니다.

자주 쓰는 API 유형

바이브코딩 프로젝트에서 자주 쓰는 API를 유형별로 정리합니다. 직접 찾아 가입하고 API 키를 발급받으면 됩니다.

유형	대표 서비스	용도
AI/텍스트	Claude API, OpenAI API	텍스트 생성, 요약, 번역
이메일	Resend, SendGrid	이메일 발송
결제	Toss Payments, Stripe	결제 처리
지도	Google Maps, Kakao Maps	지도 표시, 주소 검색
파일 저장	Supabase Storage, AWS S3	이미지, 파일 업로드
알림	Slack API, Discord Webhook	메시지 알림
인증	Google OAuth, Kakao Login	소셜 로그인

이 중에서 이미 쓰고 있는 것도 있습니다. 8장에서 연결한 Supabase도 API입니다. Supabase 클라이언트 라이브러리가 API 호출을 대신 해주고 있을 뿐, 내부적으로는 Supabase 서버에 요청을 보내고 응답을 받는 구조입니다.

API 연동이 안 될 때

API를 연결하다 보면 에러를 자주 만납니다. 대부분 몇 가지 패턴에 해당합니다.

401 Unauthorized

API 키가 잘못됐거나 빠졌을 때 나옵니다.

API 호출에서 401 에러가 나.
API 키가 제대로 설정됐는지 확인해줘.

.env 파일에 키가 있는지, 변수 이름이 코드에서 쓰는 이름과 일치하는지 확인합니다. .env 파일을 수정한 뒤에는 개발 서버를 다시 시작해야 합니다(Ctrl+C 후 npm run dev).

403 Forbidden

API 키는 맞지만 해당 기능을 쓸 권한이 없을 때 나옵니다. 무료 요금제에서 유료 기능을 호출하면 이 에러가 날 수 있습니다.

429 Too Many Requests

짧은 시간에 너무 많은 요청을 보냈을 때 나옵니다. 대부분의 API에는 분당 또는 일당 요청 횟수 제한이 있습니다. 잠시 기다렸다가 다시 시도하면 됩니다.

500 Internal Server Error

API 제공자 쪽 서버에 문제가 생긴 것입니다. 내 코드의 문제가 아닙니다. 시간을 두고 다시 시도합니다.

에러 코드를 외울 필요 없습니다. 브라우저 개발자 도구 Network 탭에서 빨간 요청을 클릭하면 상태 코드와 에러 메시지가 보입니다. 그대로 Claude Code에게 붙여넣으면 됩니다.

API 호출하면 이런 에러가 나.
[Network 탭 에러 내용 붙여넣기]
고쳐줘.

서버 vs 클라이언트 — API는 어디서 호출하나

API를 연결할 때 가장 중요한 판단이 하나 있습니다. 이 API를 브라우저에서 직접 호출할지, 서버를 거쳐서 호출할지입니다.

브라우저에서 직접 호출해도 되는 경우:

API 키가 필요 없는 공개 API
Supabase처럼 Publishable key를 쓰는 서비스 (RLS 적용)

서버를 거쳐야 하는 경우:

Secret key가 필요한 API (Claude API, 결제 API 등)
요청 내용을 사용자가 볼 수 없어야 하는 경우

Next.js에서는 서버 쪽 코드를 쉽게 만들 수 있습니다. API Route(app/api/ 폴더)나 Server Action을 쓰면 됩니다. Claude Code에게 "서버 쪽에서 호출해줘"라고 말하면 적절한 방식으로 코드를 만듭니다.

이 구분이 어려워 보여도 괜찮습니다. Claude Code에게 API 연동을 시키면 대부분 알아서 올바른 위치에 코드를 만듭니다. 다만 한 가지는 기억하세요. Secret이 들어간 API 키는 절대 브라우저 코드에 넣으면 안 됩니다.

✏️ 실습: 외부 API를 하나 연결해보기

8장에서 만든 프로젝트에 외부 API를 연결합니다. 아래 중 하나를 골라서 해봅니다.

선택지 A — AI 텍스트 기능:

Claude API를 연결해서, 사용자가 입력한 글을 3줄로 요약하는 기능을 만들어줘.
API 키는 .env에 저장하고, 서버 쪽에서 호출해줘.

선택지 B — 이메일 알림:

Resend API를 연결해서, 버튼을 누르면 내 이메일로 테스트 메일을 보내는 기능을 만들어줘.

선택지 C — 자기 프로젝트에 필요한 API:

프로젝트에 필요한 외부 서비스가 있다면 직접 연결해봅니다.

[API 이름]을 연결해줘.
[원하는 기능]을 만들어줘.
API 키: [발급받은 키]

확인할 것:

기능이 동작하는지 브라우저에서 확인합니다
.env에 API 키를 저장했는지 확인합니다
.gitignore에 .env가 들어 있는지 확인합니다
동작하면 커밋합니다

API 연동을 완료했어. 커밋하고 GitHub에 올려줘.

다음 장에서는 개발 중에 만나는 에러에 대처하는 방법을 다룹니다.

10장: 에러와 친해지기 — AI와 함께 디버깅하기

에러가 나면 어떻게 하나

기능을 만들다 보면 반드시 에러를 만납니다. 화면이 하얗게 뜨거나, 버튼을 눌러도 아무 일이 안 일어나거나, 빨간 글씨가 나타납니다.

당황하지 마세요. 에러는 정상입니다. 전문 개발자도 에러를 매일 만납니다. 바이브코딩에서 에러 대처 방법은 단순합니다. AI에게 보여주면 됩니다.

에러 메시지가 보일 때

브라우저 화면에 빨간 에러 메시지가 보이거나, 터미널에 에러가 나오면 그대로 복사해서 Claude Code에게 붙여넣습니다.

이런 에러가 나. 고쳐줘.

TypeError: Cannot read properties of undefined (reading 'map')
    at Dashboard (src/components/Dashboard.tsx:24:18)

에러 메시지를 이해할 필요 없습니다. AI가 읽고 원인을 파악합니다.

화면은 정상인데 뭔가 안 될 때

화면에 에러가 보이지 않더라도 브라우저 내부에 에러가 기록되어 있을 수 있습니다. 이걸 보려면 브라우저 개발자 도구를 엽니다.

macOS Chrome: Cmd + Option + J
Windows Chrome: F12 → 상단 탭에서 "Console" 클릭

빨간 글씨로 에러가 보이면 복사해서 Claude Code에 붙여넣습니다.

API 호출 문제(데이터가 저장이 안 되거나 불러와지지 않을 때)는 "Network" 탭이 유용합니다. 빨간색으로 표시된 요청을 클릭하면 어떤 API가 어떤 이유로 실패했는지 보입니다. 이 내용도 그대로 캡처하거나 복사해서 AI에게 주면 됩니다.

증상만 있을 때

에러 메시지가 전혀 없는데 뭔가 안 된다면 증상을 최대한 구체적으로 설명합니다.

일감 등록 버튼을 클릭하면 아무 반응이 없어.
화면에 에러도 안 뜨고, 브라우저 콘솔에도 아무것도 없어.
Supabase 대시보드를 확인해보니 데이터가 저장되지 않았어.

언제, 어디서, 무엇을 했을 때, 어떤 일이 일어났는지(또는 안 일어났는지)를 말합니다. 정보가 많을수록 AI가 빠르게 원인을 찾습니다.

자주 만나는 에러 패턴 5가지

1. 화면이 하얗게 뜸

코드에 문법 오류가 있을 때 자주 발생합니다. React에서는 컴포넌트 하나에 오류가 생기면 전체 페이지가 흰 화면이 되는 경우가 있습니다.

이런 에러가 나. 고쳐줘.

SyntaxError: Unexpected token, expected "," (12:8)

또는 에러 메시지가 없다면:

화면이 하얗게 떠. 브라우저 콘솔 에러를 확인하고 고쳐줘.

2. Module not found

필요한 라이브러리가 설치되지 않았을 때 나옵니다.

Error: Cannot find module 'react-datepicker'
Require stack: ...

에러 메시지를 그대로 주면 AI가 빠진 라이브러리를 설치해줍니다.

3. 환경변수가 없음

.env 파일 설정이 빠졌거나 변수 이름이 틀렸을 때 나옵니다.

Error: supabaseUrl is required.

TypeError: Cannot read properties of undefined (reading 'from')

이런 에러가 나오면 대부분 Supabase 연결 설정 문제입니다.

Supabase 연결 에러가 나. .env 파일과 Supabase 초기화 코드를 확인해줘.

[에러 메시지]

4. 로그인/인증 문제

회원가입은 됐는데 로그인이 안 되거나, 로그인 후 화면이 이상하게 동작할 때입니다.

로그인 버튼을 클릭하면 아무 반응이 없어.
Supabase 대시보드 Authentication에서 사용자는 확인했어.
브라우저 콘솔에 이 에러가 나와.

[에러 메시지]

5. 스타일이 깨짐

기능은 동작하는데 화면이 이상하게 보이는 경우입니다. 스크린샷을 찍어서 붙여넣는 게 가장 효과적입니다.

[스크린샷 첨부]
모바일에서 보면 메뉴가 화면 밖으로 삐져나와. 고쳐줘.

[스크린샷 첨부]
카드가 세로로 늘어나야 하는데 가로로 쌓이고 있어.

AI가 같은 실수를 반복할 때

같은 에러를 고쳤다고 하는데 계속 반복되는 경우가 있습니다. 이때는 순서대로 시도합니다.

첫 번째, 다른 방법을 요청합니다.

같은 에러가 계속 나. 지금 방식 말고 완전히 다른 방법으로 접근해봐.

두 번째, 문제 있는 부분을 처음부터 다시 만들라고 합니다.

이 컴포넌트를 수정하지 말고 처음부터 새로 만들어줘.

세 번째, /rewind로 되돌립니다. AI가 수정하기 전 상태로 돌아간 뒤, 다른 접근을 시도할 수 있습니다. Esc를 두 번 눌러도 됩니다.

네 번째, 대화를 새로 시작합니다. /clear를 입력합니다. 대화가 길어지면 AI가 이전 맥락에 갇혀 같은 접근을 반복하는 경우가 있습니다. 새 대화에서는 문제를 더 명확하게 설명하면서 다시 시도합니다.

두 번 이상 같은 문제를 수정했는데도 안 된다면, /clear 후 새로 시작하는 게 대부분 빠릅니다.

할루시네이션 감지하기

AI가 "고쳤습니다"라고 했는데 실제로는 안 되는 경우가 있습니다. 존재하지 않는 함수를 쓰거나, 잘못된 API 사용법을 알려주는 경우입니다.

감지 방법은 단순합니다. 직접 실행해보면 됩니다.

AI가 수정했다고 하면 반드시 브라우저에서 확인합니다. 버튼을 클릭하고, 데이터를 입력하고, Supabase 대시보드에서 실제로 저장됐는지 봅니다. 동작하면 맞는 거고, 안 되면 틀린 겁니다.

AI의 말을 의심하라는 뜻이 아닙니다. 대부분은 맞습니다. 다만 "AI가 됐다고 했으니 됐겠지"라고 확인 없이 넘어가지 마세요. 이 습관 하나가 나중에 발견하기 어려운 버그를 미리 막아줍니다.

✏️ 실습: 일부러 에러를 만들고 AI에게 고치게 시켜보기

에러에 익숙해지는 가장 좋은 방법은 직접 만들어보는 겁니다.

1단계: 8장에서 만든 프로젝트에서 Claude Code를 실행합니다.

2단계: AI에게 일부러 에러를 만들라고 합니다.

이 프로젝트에서 일부러 에러가 나도록 코드를 하나 수정해줘.
어떤 파일의 어떤 부분을 바꿨는지는 알려줘.
에러의 원인은 알려주지 마.

3단계: 브라우저를 열고 에러를 확인합니다. 화면에 에러가 보이면 복사합니다. 안 보이면 개발자 도구(Cmd+Option+J 또는 F12)를 열어서 Console 탭을 확인합니다.

4단계: /clear로 대화를 초기화합니다.

5단계: 에러 메시지만 가지고 원인을 찾아달라고 합니다.

이런 에러가 나. 원인을 찾아서 고쳐줘.

[에러 메시지 붙여넣기]

AI가 에러를 분석하고 수정하는 과정을 지켜보세요. 에러 메시지를 보고 어느 파일 몇 번째 줄에 문제가 있는지 찾아내는 걸 보면, 에러가 생각보다 무섭지 않다는 걸 느낄 수 있습니다.

11장: UI/UX 다듬기

기능이 되면 화면을 다듬을 차례

기능이 동작하기 시작하면, 이제 화면을 다듬을 차례입니다. 기능은 되는데 보기가 불편하거나, 버튼 위치가 어색하거나, 전체적으로 허전한 느낌이 들 수 있습니다. 이건 정상입니다. 기능을 먼저 만들고 디자인을 나중에 다듬는 게 올바른 순서입니다.

AI에게 디자인 시키기

AI에게 디자인 개선을 시키는 가장 효과적인 방법은 구체적으로 뭐가 마음에 안 드는지 말하는 것입니다. "예쁘게 해줘"처럼 추상적으로 말하면 AI도 막막합니다.

메인 페이지가 너무 허전해.
- 상단 로고와 메뉴를 더 눈에 띄게 해줘
- 일감 목록을 카드 형태로, 한 줄에 3개씩 배치해줘
- 전체적으로 여백을 넉넉하게 늘려줘
- 카드 배경은 흰색, 그림자를 살짝 줘서 입체감 있게

마음에 드는 웹사이트를 발견했다면, 스크린샷을 찍어서 AI에게 보여주는 방법도 있습니다.

[스크린샷 첨부]
이 사이트 디자인 분위기가 마음에 들어.
특히 카드 디자인과 색상 조합을 참고해서 내 프로젝트 메인 페이지를 비슷하게 바꿔줘.

frontend-design 플러그인 활용하기

AI에게 디자인을 맡기면 기능은 되지만 어딘가 "AI가 만든 것 같은" 밋밋한 느낌이 날 수 있습니다. Anthropic이 만든 frontend-design 플러그인을 설치하면 더 세련되고 완성도 높은 디자인을 만들 수 있습니다.

Claude Code 안에서 아래 두 명령어를 순서대로 입력합니다.

/plugin marketplace add anthropics/claude-code
/plugin install frontend-design@anthropics-claude-code

설치가 끝나면 /reload-plugins를 입력해 플러그인을 활성화합니다. 이후 디자인 작업을 할 때 이렇게 사용합니다.

/frontend-design:frontend-design
이 프로젝트의 메인 페이지를 세련되게 다시 디자인해줘.

색상을 직접 지정하고 싶을 때는 색상 코드를 함께 주면 됩니다.

버튼 색상을 #2563EB (파란색)로 바꿔줘.
배경은 #F8FAFC (아주 연한 회색)으로.

색상 코드를 모르면 색상 선택 도구를 검색하면 나옵니다. "color picker"를 구글에 검색하면 바로 사용할 수 있습니다.

반응형 디자인: 모바일에서도 잘 보이게

요즘 웹사이트는 컴퓨터뿐 아니라 스마트폰에서도 잘 보여야 합니다. 컴퓨터 화면에서는 예쁜데 스마트폰으로 열면 글자가 잘리거나, 버튼이 너무 작거나, 레이아웃이 어그러지는 경우가 흔합니다.

모바일 화면 확인하는 방법

브라우저 개발자 도구에서 모바일 화면을 시뮬레이션할 수 있습니다.

macOS: Cmd + Option + I로 개발자 도구를 열고, 왼쪽 위의 📱 아이콘을 클릭합니다.

Windows: F12로 개발자 도구를 열고, 같은 📱 아이콘을 클릭합니다.

상단에서 기기를 선택하면 그 기기의 화면 크기로 미리 볼 수 있습니다.

iPhone SE — 작은 화면 (375px)
iPhone 14 Pro — 일반 아이폰 크기 (393px)
Galaxy S20 Ultra — 큰 안드로이드 화면 (412px)

가장 작은 iPhone SE 기준으로 확인하는 걸 권장합니다. 이 화면에서 잘 보이면 대부분의 기기에서 잘 보입니다.

깨지는 부분을 발견하면 스크린샷을 찍어서 AI에게 보여줍니다.

[스크린샷 첨부]
모바일(iPhone SE)에서 보면 이렇게 깨져.
- 일감 카드가 화면 밖으로 삐져나와
- 등록 버튼이 너무 작아서 누르기 어려워
고쳐줘.

스크린샷 없이 말로만 설명해도 됩니다.

모바일에서 보면 네비게이션 메뉴가 화면 밖으로 나가.
모바일에서는 메뉴를 숨기고 햄버거 아이콘으로 펼치는 방식으로 바꿔줘.

사용자 흐름(User Flow) 점검하기

디자인만큼 중요한 게 "사용하기 편한가"입니다. 코드를 볼 줄 몰라도, 직접 사용해보면서 불편한 부분을 찾을 수 있습니다.

체크할 것들

처음 들어왔을 때: 뭘 해야 하는지 바로 알 수 있는가? 새로운 사람이 이 페이지를 처음 봤을 때 다음 행동이 명확한가?

등록/입력 흐름: 일감이나 데이터를 등록하고 나면 어떻게 되는가? 성공 메시지가 나오는가? 목록으로 돌아가는가? 아니면 폼이 그대로 남아 있는가?

피드백: 버튼을 눌렀을 때 반응이 바로 보이는가? 저장 중이라는 표시가 있는가? 성공/실패 여부를 알 수 있는가?

이동: 다른 페이지로 가는 방법이 직관적인가? 뒤로 가거나 메인으로 돌아가기 쉬운가?

빈 상태: 데이터가 하나도 없을 때 화면이 어떻게 보이는가? 빈 목록 화면이 "뭘 해야 하는지" 안내를 해주는가?

불편한 부분을 발견하면 그대로 AI에게 전달합니다.

일감을 등록하고 나면 폼이 초기화되지 않고 그대로 남아 있어.
등록이 성공하면 폼을 비우고 목록 페이지로 이동하게 바꿔줘.

일감이 하나도 없을 때 빈 화면이 그냥 비어있어.
"아직 등록된 일감이 없습니다. 첫 일감을 등록해보세요!"라는 메시지와 등록 버튼을 보여줘.

저장 버튼을 눌렀을 때 성공했는지 실패했는지 모르겠어.
성공하면 "저장됐습니다" 토스트 메시지를 잠깐 보여줘.
실패하면 에러 메시지를 표시해줘.

핵심은 직접 사용해보는 것입니다. AI는 여러분이 불편하다고 말해야 고칩니다. "이거 불편한데?"라는 판단은 여러분만 할 수 있습니다.

로딩과 에러 상태 처리하기

완성도를 높이는 디테일이 있습니다. 데이터를 불러오는 동안, 또는 오류가 생겼을 때 화면이 어떻게 보이는가입니다.

데이터를 불러오는 동안 빈 화면이 그냥 뜨는데,
로딩 스피너나 스켈레톤 UI를 추가해줘.

일감 삭제 버튼을 눌렀을 때 확인 없이 바로 삭제돼.
"정말 삭제하시겠습니까?" 확인 팝업을 추가해줘.

이런 디테일들이 완성된 서비스처럼 보이게 만듭니다.

✏️ 실습: 전체 화면 UI를 개선하기

8장에서 만든 기능이 동작하는 프로젝트를 다듬어봅시다.

1단계: npm run dev로 개발 서버를 켜고 브라우저에서 프로젝트를 엽니다.

2단계: 화면을 하나씩 돌아다니면서 마음에 안 드는 부분을 메모합니다. 최소 3가지를 찾아보세요. 디자인이 아니어도 됩니다. 흐름이 어색한 것, 피드백이 없는 것도 포함합니다.

3단계: Claude Code에게 하나씩 개선을 요청합니다. 여러 가지를 한 번에 보내도 됩니다.

지금 프로젝트 디자인을 개선해줘.
1. 전체적으로 여백을 넉넉하게
2. 일감 목록을 카드 형태로 (배경 흰색, 그림자 살짝)
3. 등록 성공하면 목록 페이지로 자동 이동
4. 일감이 없을 때 "등록된 일감이 없습니다" 메시지 표시

4단계: 개발자 도구에서 📱 아이콘을 켜고 iPhone SE 크기로 확인합니다. 깨지는 부분을 스크린샷으로 캡처해서 AI에게 보내세요.

5단계: 개선이 완료되면 커밋합니다.

UI 개선 완료됐어. 커밋하고 GitHub에 올려줘.

디자인은 한 번에 완성되지 않습니다. 써보고, 불편한 점을 발견하고, 개선하는 과정을 반복하면 점점 좋아집니다.

12장: 보안 점검

왜 바이브코더에게 보안이 더 중요한가

전통적인 개발자는 보안에 대해 교육을 받습니다. 하지만 바이브코더는 그런 배경 없이 바로 서비스를 만듭니다. AI도 보안을 알아서 챙겨주지 않습니다. 여러분이 "보안 점검해줘"라고 말하지 않으면, AI는 기능 구현에만 집중합니다.

배포하기 전에 아래 항목들을 꼭 확인하세요.

API 키 노출 사고

가장 흔하고 치명적인 실수입니다. Supabase의 Secret key나 다른 서비스의 비밀 키가 코드에 직접 들어가 있으면, GitHub에 올리는 순간 전 세계 누구나 볼 수 있게 됩니다.

실제로 이런 일이 매우 자주 일어납니다. 비밀 키가 노출되면 누군가 여러분의 데이터베이스에 접근하거나, 유료 서비스를 여러분 계정으로 사용할 수 있습니다.

방지하는 방법은 간단합니다. 비밀 키는 반드시 .env 파일에 넣고, .env 파일은 반드시 .gitignore에 포함시키세요. 7장에서 이미 이 설정을 했지만, 배포 전에 한 번 더 확인합니다.

.env 파일이 .gitignore에 포함되어 있는지 확인해줘.
그리고 코드 안에 직접 API 키나 비밀번호가 하드코딩된 곳이 없는지 전체 검사해줘.

만약 이미 GitHub에 올라가 버렸다면, 단순히 파일을 삭제해서는 안 됩니다. Git 히스토리에 내용이 남기 때문입니다. 이 경우엔 즉시 해당 서비스에서 키를 무효화(revoke)하고 새 키를 발급받는 게 먼저입니다.

.env 파일이 실수로 GitHub에 올라간 것 같아.
Git 히스토리에서도 완전히 지우는 방법을 알려줘.

환경변수(.env) 완전 정복

.env 파일은 비밀 정보를 저장하는 파일입니다. Supabase URL, 비밀 키, 다른 서비스의 비밀번호 같은 것들이 여기에 들어갑니다.

중요한 건, .env 파일은 여러분의 컴퓨터에만 존재해야 한다는 겁니다. GitHub에 올라가면 안 됩니다.

그러면 배포할 때는 어떻게 할까요? Vercel 같은 배포 서비스에는 환경변수를 따로 등록하는 기능이 있습니다. 이건 13장에서 다룹니다.

.env 파일 형식은 이렇습니다.

NEXT_PUBLIC_SUPABASE_URL=https://xxxxx.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=sb_publishable_xxxx...
SUPABASE_SECRET_KEY=sb_secret_xxxx...

NEXT_PUBLIC_으로 시작하는 변수는 브라우저에서도 읽을 수 있는 공개용입니다. 그 외의 변수는 서버에서만 읽힙니다. Supabase의 Publishable key(sb_publishable_)는 NEXT_PUBLIC_을 붙여도 되지만, Secret key(sb_secret_)는 절대 붙이면 안 됩니다.

AI가 생성한 코드의 보안 점검

배포 전에 AI에게 전체적인 보안 점검을 맡깁니다.

이 프로젝트를 배포하기 전에 보안 점검을 해줘.
아래 항목들을 확인해줘.

1. .env 파일이 .gitignore에 포함되어 있는가
2. 코드에 API 키나 비밀번호가 하드코딩되어 있지 않은가
3. NEXT_PUBLIC_ 변수에 Secret key가 들어가 있지 않은가
4. Supabase RLS가 모든 테이블에 설정되어 있는가
5. 사용자 입력을 받는 곳에 기본적인 검증이 있는가

문제가 있으면 알려주고 고쳐줘.

AI가 점검 결과를 알려주면 하나씩 확인하고 수정합니다. 점검 완료 후 커밋까지 부탁합니다.

보안 점검 결과를 반영해서 커밋하고 GitHub에 올려줘.

✏️ 실습: 배포 전 보안 점검하기

1단계: Claude Code에게 보안 점검을 요청합니다.

이 프로젝트를 배포하기 전에 보안 점검을 해줘.

2단계: 문제가 있으면 수정하고, 커밋합니다.

수정 완료됐어. 커밋하고 GitHub에 올려줘.

보안 점검이 끝났으면 13장에서 배포를 진행합니다.

13장: 배포하기

배포란 무엇인가

지금까지 만든 프로젝트는 여러분의 컴퓨터에서만 동작합니다. localhost:3000은 여러분 컴퓨터 안에서만 열리는 주소입니다. 다른 사람에게 링크를 보내도 아무것도 보이지 않습니다.

배포(deploy)란 여러분의 코드를 인터넷 어딘가의 서버에 올려서, 누구나 접속할 수 있는 주소를 만드는 과정입니다. 배포가 끝나면 스마트폰으로도, 다른 나라에서도 접속할 수 있습니다.

Vercel 배포

Next.js 프로젝트를 배포하는 가장 쉬운 방법은 Vercel입니다. GitHub에 코드가 올라가 있으면 몇 분 안에 배포할 수 있습니다.

1단계: https://vercel.com 에 접속해서 계정을 만듭니다. "Continue with GitHub"를 클릭하면 GitHub 계정으로 바로 가입할 수 있습니다.

2단계: 로그인 후 "Add New Project"를 클릭합니다.

3단계: GitHub 저장소 목록에서 여러분의 프로젝트를 선택합니다. 7장에서 GitHub에 올린 프로젝트가 보입니다. "Import"를 클릭합니다.

4단계: 환경변수를 등록합니다. 배포 설정 화면에서 "Environment Variables" 섹션을 찾아, .env 파일의 내용을 통째로 복사해서 붙여넣으면 Vercel이 자동으로 파싱해서 등록합니다. 하나씩 추가할 수도 있습니다. 왼쪽에 변수 이름(예: NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY), 오른쪽에 값을 입력하고 "Add"를 클릭합니다.

어떤 환경변수를 등록해야 하는지 모르겠으면 Claude Code에게 물어보세요.

이 프로젝트를 Vercel에 배포하려고 해.
.env 파일에 있는 환경변수 중 Vercel에 등록해야 하는 것들을 목록으로 알려줘.

5단계: 배포 설정 화면에서 리전(Region)을 확인합니다. 기본값이 미국 서버로 되어 있는 경우가 많습니다. Supabase 프로젝트를 Seoul 리전으로 만들었다면, Vercel도 가장 가까운 리전인 icn1 (Seoul, South Korea) 로 맞춰야 빠릅니다. 리전이 어긋나면 데이터베이스 응답 속도가 눈에 띄게 느려집니다.

6단계: "Deploy"를 클릭합니다. 빌드 로그가 흘러가고, 몇 분 후에 https://프로젝트이름.vercel.app 주소가 생깁니다.

빌드 실패 시

배포 로그에서 빨간 에러 메시지를 찾아 복사합니다. Claude Code에게 붙여넣으면 됩니다.

Vercel 배포 중에 이런 에러가 났어.
[에러 메시지 붙여넣기]
어떻게 고쳐야 해?

수정 후 GitHub에 다시 올리면 Vercel이 자동으로 재배포합니다.

배포 후 확인

배포가 완료되면 브라우저에서 주소를 열어 동작을 확인합니다.

개발 환경(localhost:3000)에서는 잘 됐는데 배포 후에 안 되는 경우가 있습니다. 대부분 환경변수가 누락됐거나, Supabase에서 해당 도메인을 허용하지 않아서입니다.

Supabase 도메인 허용 설정

로그인 기능이 배포 후에 동작하지 않는다면 이 설정을 확인하세요.

1단계: Supabase 대시보드 → Authentication → URL Configuration

2단계: "Site URL"에 Vercel 주소 입력 (예: https://myproject.vercel.app)

3단계: "Redirect URLs"에 같은 주소 추가

이 설정을 하지 않으면 로그인 후 리다이렉트가 실패합니다.

이후 코드 수정과 재배포

Vercel의 가장 편리한 점은 GitHub에 push하면 자동으로 재배포된다는 겁니다. Claude Code에게 수정을 요청하고 GitHub에 올리기만 하면, 몇 분 후에 배포 주소에 반영됩니다.

버튼 색상을 파란색으로 바꿔줘.
수정하고 GitHub에 올려줘.

이 작업 흐름이 앞으로 계속 반복됩니다. 수정 → GitHub push → 자동 재배포.

도메인 연결하기

Vercel이 만들어준 xxxx.vercel.app 주소 대신 자기만의 도메인(예: myproject.com)을 쓰고 싶다면 도메인을 구매해서 연결할 수 있습니다.

도메인은 Namecheap, GoDaddy, 가비아 같은 사이트에서 구매합니다. 구매 후 Vercel 대시보드 → 프로젝트 → Settings → Domains에서 도메인을 추가합니다. Vercel이 DNS 설정 방법을 단계별로 안내해 줍니다.

지금 당장 필요한 건 아닙니다. xxxx.vercel.app 주소만으로도 충분히 공유할 수 있습니다.

✏️ 실습: 배포하고 링크 공유하기

1단계: 12장에서 보안 점검과 커밋을 완료했는지 확인합니다.

2단계: Vercel에서 프로젝트를 배포합니다. 위의 1~5단계를 따라하세요.

3단계: 배포가 완료되면 주소를 브라우저에서 열어 확인합니다. 로그인, 데이터 등록, 조회가 모두 잘 되는지 확인합니다.

4단계: Supabase URL Configuration에서 Vercel 주소를 추가합니다.

5단계: 링크를 주변 사람에게 공유해봅니다.

축하합니다. 여러분의 프로젝트가 인터넷에 올라갔습니다.

14장: SEO

만든 것을 찾을 수 있어야 한다

배포를 마치고 구글에 서비스 이름을 검색했는데 아무것도 안 나옵니다. 코드는 잘 돌아가는데, 세상이 이 서비스의 존재를 모릅니다.

이게 SEO를 챙겨야 하는 이유입니다.

SEO란 무엇인가

SEO는 Search Engine Optimization, 검색 엔진 최적화입니다. 구글 같은 검색 엔진이 여러분의 사이트를 잘 이해하고, 관련 검색어에 높은 순위로 노출하도록 만드는 작업입니다.

광고는 돈을 내는 동안만 노출됩니다. SEO는 한 번 올라간 순위가 꾸준히 방문자를 데려옵니다. 장기적으로는 광고보다 SEO가 훨씬 효율적인 유입 수단입니다.

검색 엔진이 사이트를 읽는 방식

구글은 크롤러(crawler)라는 봇을 보내서 웹사이트를 순회합니다. 페이지의 HTML을 읽고, 링크를 따라 다른 페이지로 이동하면서 내용을 수집합니다. 수집한 내용을 분석해서 색인(index)에 저장하고, 사용자가 검색하면 가장 적합한 페이지를 순위에 따라 보여줍니다.

이 과정에서 구글은 세 가지 질문에 답하려 합니다.

이 페이지는 무엇에 관한 것인가? — 제목, 설명, 본문 내용으로 판단합니다.

이 페이지는 믿을 만한가? — 다른 사이트에서 얼마나 많이 링크가 달렸는지로 판단합니다.

이 페이지는 쓰기 편한가? — 로딩 속도, 모바일 대응 여부 등으로 판단합니다.

바이브코딩으로 만든 프로젝트에서 당장 챙길 수 있는 것은 첫 번째, "무엇에 관한 페이지인지 명확하게 알려주는 것"입니다.

타이틀과 메타 디스크립션

검색 결과에서 가장 먼저 보이는 것이 제목과 설명입니다. 이걸 타이틀(title)과 메타 디스크립션(meta description)이라고 합니다.

구글 검색 결과 한 줄을 보면 파란 굵은 글씨가 타이틀, 그 아래 회색 두 줄이 메타 디스크립션입니다. 사람이 클릭할지 결정하는 게 이 두 가지입니다.

바이브코딩으로 만든 프로젝트는 기본적으로 Next.js App이라는 제목이 그대로 나오는 경우가 흔합니다. 이걸 바꾸는 것이 SEO의 첫걸음입니다.

좋은 타이틀의 조건:

페이지가 무엇인지 명확하게
30~60자 이내
서비스 이름 포함

좋은 메타 디스크립션의 조건:

이 페이지에서 무엇을 할 수 있는지 설명
70~155자 이내
검색자가 원하는 것을 담기

Next.js에서는 metadata 객체로 설정합니다.

이 프로젝트에 타이틀과 메타 디스크립션을 설정해줘.

서비스 이름: [서비스 이름]
설명: [이 서비스에서 무엇을 할 수 있는지 한두 문장]
배포 주소: [Vercel 주소]

app/layout.tsx의 metadata에 title과 description을 추가해줘.
title은 template 패턴으로 각 페이지 제목이 "페이지명 | 서비스명" 형태가 되게 해줘.

AI가 만들어주는 코드는 이런 형태입니다.

// app/layout.tsx
export const metadata: Metadata = {
  title: {
    default: '프리랜서 일감 관리',
    template: '%s | 프리랜서 일감 관리',
  },
  description: '프리랜서 일감을 등록하고 수입을 한눈에 관리하세요. 클라이언트별 히스토리와 미수금 현황을 쉽게 파악할 수 있습니다.',
}

title.template의 %s는 각 페이지에서 설정한 제목으로 대체됩니다. 대시보드 페이지에 "대시보드"를 설정하면 탭과 검색 결과에 "대시보드 | 프리랜서 일감 관리"라고 나옵니다.

페이지마다 고유한 제목과 설명 달기

기본값만 설정하면 모든 페이지가 같은 제목으로 나옵니다. 각 페이지마다 고유한 제목을 주는 것이 중요합니다. 검색 엔진은 페이지마다 다른 내용이라는 걸 명확히 알 수 있어야 하고, 사람도 검색 결과에서 어느 페이지인지 구분할 수 있어야 합니다.

각 페이지에 개별 메타데이터를 추가해줘.
- 로그인: "로그인", 설명: "이메일로 로그인해서 일감을 관리하세요."
- 대시보드: "대시보드", 설명: "등록된 일감과 수입 현황을 한눈에 확인하세요."
- 일감 등록: "일감 등록", 설명: "새 일감을 등록하고 클라이언트 정보를 저장하세요."

로그인이 필요한 페이지(대시보드 등)는 검색 결과에 나올 필요가 없습니다. 하지만 타이틀은 브라우저 탭 제목이기도 합니다. 검색 노출이 목적이 아니더라도 탭 제목이 명확한 것만으로 사용성이 좋아지니 설정해두는 게 낫습니다.

URL 구조

URL도 SEO에 영향을 줍니다. 구글은 URL만 봐도 "이 페이지가 무엇에 관한 것인지" 짐작합니다.

/p/123보다 /products/123이 낫고, /products/123보다 /products/running-shoes가 낫습니다. 사람이 읽을 수 있는 URL이 검색 엔진도 이해하기 쉽습니다.

Next.js App Router는 폴더 구조가 그대로 URL이 됩니다. 처음 프로젝트 구조를 잡을 때 AI에게 SEO를 고려한 URL 구조를 요청할 수 있습니다.

이 프로젝트의 URL 구조를 SEO에 유리하게 설계해줘.
사람이 읽을 수 있는 URL이 되도록,
숫자 ID 대신 의미 있는 경로를 쓰는 방향으로.

이미 만들어진 프로젝트라면 무리하게 바꿀 필요는 없습니다. 초기 설계 때 반영하는 게 가장 좋습니다.

링크 미리보기: Open Graph

카카오톡이나 슬랙에 링크를 붙여넣으면 제목, 설명, 이미지가 카드 형태로 나옵니다. 이걸 링크 미리보기라고 하고, Open Graph(OG) 태그가 이 정보를 제공합니다.

OG 태그가 없으면 링크를 공유해도 URL만 덩그러니 나옵니다. 제목과 설명이 보여야 사람들이 클릭합니다.

이 프로젝트에 Open Graph 메타 태그를 설정해줘.

서비스 이름: [서비스 이름]
설명: [한두 문장]
배포 주소: [Vercel 주소]

og:title, og:description, og:url을 설정하고,
og:image는 1200x630 크기의 기본 이미지를 만들어줘.
카카오톡, 슬랙, 트위터에서 미리보기가 잘 나오도록 해줘.

Next.js에서는 metadata 객체에 openGraph 필드를 추가하면 됩니다.

export const metadata: Metadata = {
  title: '프리랜서 일감 관리',
  description: '프리랜서 일감을 등록하고 수입을 한눈에 관리하세요.',
  openGraph: {
    title: '프리랜서 일감 관리',
    description: '프리랜서 일감을 등록하고 수입을 한눈에 관리하세요.',
    url: 'https://myproject.vercel.app',
    images: [{ url: '/og-image.png', width: 1200, height: 630 }],
  },
}

설정 후 확인하는 방법은 카카오톡에 링크를 직접 붙여넣는 것이 가장 빠릅니다.

이미지 alt 텍스트

이미지는 검색 엔진이 직접 "볼" 수 없습니다. 대신 alt 속성에 적힌 텍스트를 읽습니다. alt 텍스트가 없으면 그 이미지는 검색 엔진에게 투명합니다.

이미지 검색에도 영향을 줍니다. 적절한 alt 텍스트가 있으면 이미지 검색에서도 노출될 수 있습니다.

이 프로젝트의 모든 이미지에
적절한 alt 텍스트가 없는 것을 찾아서 추가해줘.
단순히 파일명이나 "image"라고 쓰지 말고,
이미지가 무엇을 보여주는지 구체적으로 설명하는 텍스트로.

robots.txt와 sitemap.xml

robots.txt는 검색 엔진 봇에게 "어느 페이지는 크롤링해도 되고, 어느 페이지는 하지 말아라"를 알려주는 파일입니다. 로그인이 필요한 관리자 페이지는 크롤링할 필요가 없습니다.

sitemap.xml은 사이트의 모든 페이지 목록을 알려주는 파일입니다. 구글이 빠짐없이 모든 페이지를 색인하도록 도와줍니다. 페이지가 많을수록 중요합니다.

robots.txt와 sitemap.xml을 자동 생성하는 코드를 만들어줘.
배포 주소는 https://myproject.vercel.app 이야.
- robots.txt: /admin 하위 페이지는 크롤링 차단, 나머지는 허용
- sitemap.xml: 공개 페이지 목록 포함, 업데이트 주기는 weekly

Google Search Console에 등록하기

메타데이터를 아무리 잘 설정해도 구글이 크롤링하기 전까지는 검색 결과에 나오지 않습니다. 신규 사이트는 수일에서 수주가 걸립니다.

Google Search Console에 등록하면 두 가지를 할 수 있습니다. 첫째, sitemap을 직접 제출해서 크롤링을 요청할 수 있습니다. 신규 사이트가 빠르게 색인되도록 앞당겨줍니다. 둘째, 사이트가 어떤 검색어에 노출되는지, 클릭률은 얼마인지, 어떤 페이지가 색인되지 않았는지 확인할 수 있습니다.

Google Search Console에 이 사이트를 등록하는 방법을 단계별로 알려줘.
배포 주소는 https://myproject.vercel.app 이야.
도메인 소유권 인증은 HTML 태그 방식으로 해줘.

소유권 인증 방법은 여러 가지인데, HTML 태그 방식이 Next.js에서 가장 간단합니다. AI가 안내하는 대로 따라가면 됩니다.

등록 후 sitemap을 제출하는 방법:

Google Search Console 왼쪽 메뉴에서 "Sitemaps" 클릭
https://myproject.vercel.app/sitemap.xml 입력 후 제출

SEO는 콘텐츠가 전부다

기술적인 설정을 다 갖춰도, 결국 검색 순위를 올리는 건 콘텐츠입니다. 구글은 사람들이 실제로 찾고 있는 내용을 잘 담은 페이지를 높이 평가합니다.

바이브코딩으로 만든 서비스에서 콘텐츠 SEO를 챙기는 가장 실용적인 방법은 AI에게 묻는 것입니다.

우리 서비스는 [서비스 설명]이야.
이 서비스의 잠재 사용자들이 구글에서 어떤 검색어를 쓸 것 같아?
검색량이 있을 만한 키워드를 뽑아줘.
그 키워드가 자연스럽게 들어가도록 메인 페이지 텍스트를 다시 써줘.

과도하게 키워드를 반복하면 오히려 구글 페널티를 받습니다. 사람이 읽기 자연스러운 수준을 유지하면 됩니다.

✏️ 실습: SEO 기본 설정하기

1단계: 타이틀과 메타 디스크립션을 설정합니다.

이 프로젝트에 타이틀과 메타 디스크립션을 설정해줘.

서비스 이름: [서비스 이름]
설명: [한두 문장]
배포 주소: [Vercel 주소]

app/layout.tsx에 title template과 description을 추가하고,
주요 페이지마다 개별 타이틀도 추가해줘.

2단계: robots.txt와 sitemap.xml을 만듭니다.

robots.txt와 sitemap.xml을 자동 생성하는 코드를 만들어줘.
배포 주소: [Vercel 주소]
관리자 페이지(/admin)는 크롤링 차단해줘.

3단계: Open Graph 태그를 설정합니다.

이 프로젝트에 Open Graph 메타 태그를 설정해줘.

서비스 이름: [서비스 이름]
설명: [한두 문장]
배포 주소: [Vercel 주소]

og:title, og:description, og:url, og:image를 설정해줘.

4단계: 이미지 alt 텍스트를 점검합니다.

이 프로젝트에서 alt 텍스트가 없거나 부적절한 이미지를 찾아서 수정해줘.

5단계: 커밋하고 GitHub에 올립니다.

SEO 설정 완료됐어. 커밋하고 GitHub에 올려줘.

6단계: Vercel 재배포가 완료되면 직접 Google Search Console에 접속해서 사이트를 등록하고 sitemap을 제출합니다. 이 단계는 AI가 대신할 수 없으니 위의 "Google Search Console에 등록하기" 섹션을 참고해서 직접 진행합니다.

SEO는 단번에 효과가 나타나지 않습니다. 설정하고 나서 Google Search Console을 주기적으로 확인하면, 시간이 지나면서 어떤 검색어에 노출되기 시작하는지 보이기 시작합니다. 다음 장에서는 방문자 데이터를 수집하고 에러를 감지하는 분석과 모니터링을 다룹니다.

15장: 분석과 모니터링

배포 후에도 할 일이 있다

배포하고 링크를 공유했습니다. 그런데 사람들이 실제로 들어오는지, 어디서 막히는지, 에러가 나고 있는지 — 아무것도 모릅니다. 코드가 돌아가고 있다는 건 알지만, 그 안에서 무슨 일이 벌어지는지는 모릅니다.

이 장에서는 두 가지를 다룹니다. 첫째, 사람들이 어떻게 서비스를 쓰는지 파악하는 분석(Analytics). 둘째, 에러가 났을 때 알아차리는 모니터링(Monitoring).

Vercel Analytics: 가장 빠른 시작

Vercel로 배포했다면 분석 도구를 바로 쓸 수 있습니다. Vercel Analytics는 별도 서비스 가입 없이, 코드 몇 줄만 추가하면 됩니다.

확인할 수 있는 것들:

방문자 수: 오늘, 이번 주, 이번 달 방문자
페이지뷰: 어느 페이지를 많이 보는지
유입 경로: 어디서 들어왔는지 (구글 검색, 직접 입력, 링크 클릭 등)
기기와 브라우저: 모바일/PC 비율, 어떤 브라우저를 쓰는지
국가: 어느 나라에서 접속하는지

무료 플랜으로 최근 30일치 데이터를 볼 수 있습니다.

설치하기

Vercel Analytics를 이 프로젝트에 추가해줘.

AI가 해주는 작업은 두 가지입니다. @vercel/analytics 패키지를 설치하고, app/layout.tsx에 <Analytics /> 컴포넌트를 추가합니다. 코드 한 줄이 전부입니다.

// app/layout.tsx
import { Analytics } from '@vercel/analytics/react'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Analytics />
      </body>
    </html>
  )
}

GitHub에 올리면 Vercel이 재배포하고, 이후 방문자부터 데이터가 쌓이기 시작합니다. Vercel 대시보드 → 프로젝트 → Analytics 탭에서 확인할 수 있습니다.

Vercel Speed Insights: 페이지 속도 측정

앞 장에서 검색 엔진이 "이 페이지는 쓰기 편한가?"를 로딩 속도로 판단한다고 했습니다. Speed Insights는 실제 방문자의 페이지 로딩 속도를 측정합니다. 어떤 페이지가 느린지, 얼마나 느린지를 Vercel 대시보드에서 바로 확인할 수 있습니다.

설치 방법은 Analytics와 동일합니다.

Vercel Speed Insights를 이 프로젝트에 추가해줘.

@vercel/speed-insights 패키지를 설치하고 <SpeedInsights /> 컴포넌트를 추가하면 됩니다. Analytics와 나란히 넣으면 됩니다.

import { Analytics } from '@vercel/analytics/react'
import { SpeedInsights } from '@vercel/speed-insights/next'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Analytics />
        <SpeedInsights />
      </body>
    </html>
  )
}

배포 후 Vercel 대시보드 → Speed Insights 탭에서 확인할 수 있습니다. 속도가 느린 페이지가 보이면 AI에게 최적화를 요청하면 됩니다.

Speed Insights에서 /products 페이지의 LCP가 4초로 나와.
이 페이지 로딩 속도를 개선해줘.

더 필요할 때: 다른 분석 도구들

Vercel Analytics는 방문자 수와 페이지뷰 같은 기본 지표를 빠르게 파악하기 좋습니다. 하지만 "회원가입 버튼을 몇 명이 클릭했는지", "가입 폼 어느 단계에서 이탈하는지" 같은 상세한 행동 데이터가 필요해지면 전문 분석 도구를 추가할 수 있습니다.

대표적인 선택지입니다.

Google Analytics — 가장 널리 쓰이는 분석 도구입니다. 데이터를 수년간 무료로 보관하고, 구글 광고와 연동됩니다. 앞 장에서 설정한 Google Search Console과 연결하면 검색 유입부터 사용자 행동까지 한눈에 볼 수 있습니다.

PostHog — 이벤트 추적, 세션 녹화, 기능 플래그, A/B 테스트를 한 도구에서 제공합니다. 오픈소스이고 무료 플랜이 넉넉해서 개인 프로젝트에 추천하는 도구입니다.

어느 도구든 Claude Code에게 설치를 맡기면 됩니다.

에러 모니터링: 문제를 사용자보다 먼저 알기

분석 도구는 "얼마나 많이 쓰는지"를 알려줍니다. 에러 모니터링은 "뭔가 잘못되고 있는지"를 알려줍니다.

배포된 서비스에서 에러가 나도 여러분은 모릅니다. 개발자 도구를 직접 열어보지 않는 이상, 에러는 조용히 쌓입니다. 사용자가 포기하고 나가거나, 불편하다는 피드백을 남길 때야 비로소 알게 됩니다.

앞서 소개한 PostHog도 에러 추적 기능을 포함하고 있어서, 분석과 모니터링을 한 도구로 해결하고 싶다면 PostHog 하나만 써도 됩니다. 별도 에러 모니터링 도구가 필요하다면 Sentry(sentry.io)를 가장 많이 씁니다. 에러가 발생하는 즉시 어느 파일 몇 번째 줄에서, 어떤 사용자 환경에서, 얼마나 자주 일어나는지를 기록하고 이메일로 알려줍니다.

분석 데이터로 뭘 해야 하나

데이터를 수집하기 시작하면, 무엇을 봐야 할지 막막할 수 있습니다.

처음 2주: 데이터가 쌓이는 걸 지켜봅니다. 판단하기에는 데이터가 너무 적습니다. 대신 기준선을 파악합니다. 하루 평균 방문자가 몇 명인지, 어느 페이지를 가장 많이 보는지.

질문 하나씩 답을 찾습니다. "사람들이 가입 후에 실제로 기능을 쓰는가?" "모바일 사용자가 데스크톱보다 이탈률이 높은가?" 이런 질문에 답하는 데 집중합니다.

에러가 나오면 바로 처리합니다. Sentry에 에러가 쌓이기 시작하면 하나씩 확인합니다. 자주 발생하는 에러부터 처리합니다.

AI에게 데이터를 해석해달라고 할 수도 있습니다.

Vercel Analytics를 보니까 아래처럼 나와.

- 전체 방문자: 320명 (최근 7일)
- /register 페이지뷰: 180회
- /dashboard 페이지뷰: 40회

회원가입 페이지는 많이 보는데 대시보드는 적게 봐.
어떻게 해석할 수 있고, 뭘 확인해봐야 할까?

✏️ 실습: Vercel Analytics 연결하고 데이터 확인하기

1단계: Vercel Analytics를 설치합니다.

Vercel Analytics를 이 프로젝트에 추가해줘.

2단계: 변경사항을 GitHub에 올립니다.

커밋하고 GitHub에 올려줘.

3단계: 배포가 완료되면 배포 주소를 직접 몇 번 방문합니다. 여러 페이지를 돌아다닙니다. Vercel 대시보드 → Analytics 탭에서 방금 방문한 데이터가 들어오는지 확인합니다.

분석과 모니터링은 설정해두면 알아서 데이터를 쌓습니다. 처음에는 숫자가 작아서 의미없어 보일 수 있습니다. 하지만 서비스를 쓰는 사람이 생기면서 패턴이 보이기 시작합니다. 무엇이 잘 되고, 무엇이 안 되는지. 이 데이터가 다음에 무엇을 만들지 결정하는 기준이 됩니다. 다음 장에서는 AI의 능력을 더 확장하는 MCP와 스킬을 다룹니다.

16장: MCP와 CLI

MCP란 무엇인가

Claude Code는 코드를 작성하고 파일을 다루는 일은 잘 합니다. 하지만 기본 상태에서 직접 할 수 없는 것들이 있습니다. Supabase 데이터베이스에 접속해서 데이터를 조회하거나, 브라우저를 열어서 화면을 클릭하는 것입니다.

MCP(Model Context Protocol)는 Claude Code에 새로운 도구를 연결하는 방법입니다. 스마트폰에 앱을 설치하듯이, MCP를 추가하면 AI가 쓸 수 있는 도구가 늘어납니다.

MCP를 연결하면 Claude Code가 대화 중에 직접 도구를 호출합니다. 예를 들어 Supabase MCP를 연결하면 "일감 테이블 보여줘"라고 했을 때 Claude가 직접 데이터베이스에 쿼리를 날리고 결과를 가져옵니다. SQL을 쓰거나 대시보드를 열 필요가 없습니다.

Supabase MCP: 데이터베이스를 대화로 다루기

Supabase MCP를 연결하면 SQL 없이도 AI가 데이터베이스에 접속해서 테이블 구조를 보고, 데이터를 조회하고, 스키마를 수정할 수 있습니다.

새 터미널 창에서 아래 명령어를 입력합니다.

claude mcp add --transport http supabase https://mcp.supabase.com/mcp

명령어를 실행하면 브라우저가 열리면서 Supabase 로그인을 요청합니다. 기존 Supabase 계정으로 로그인하면 Claude Code가 바로 연결을 마칩니다.

다시 claude를 입력해서 Claude Code를 실행합니다. 이제 이렇게 쓸 수 있습니다.

Supabase에 있는 테이블 목록을 보여줘.

일감 테이블에서 상태가 "미수금"인 항목만 보여줘.

일감 테이블에 "마감일" 컬럼을 추가해줘.

Playwright MCP: AI가 브라우저를 열어 테스트하기

Playwright MCP를 설치하면 AI가 직접 브라우저를 열어서 웹사이트를 테스트합니다. 버튼 클릭, 폼 입력, 결과 확인까지 직접 합니다.

claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest

설치 후 이렇게 씁니다.

브라우저를 열어서 http://localhost:3000 에 접속하고,
회원가입 → 로그인 → 일감 등록 순서로 테스트해줘.
문제가 있으면 알려줘.

MCP의 함정 — 컨텍스트를 먹는다

MCP는 편리하지만 대가가 있습니다. 컨텍스트 창을 빠르게 소모합니다.

컨텍스트 창은 Claude가 한 번의 대화에서 기억할 수 있는 내용의 총량입니다. 대화 내역, 코드, 파일 내용이 모두 여기 쌓이고, 꽉 차면 Claude가 오래된 내용을 밀어내고 앞에서 한 얘기를 잊기 시작합니다.

MCP를 켜두면 두 가지 방식으로 컨텍스트를 소모합니다.

첫째, 도구 목록 자체가 컨텍스트를 차지합니다. MCP를 연결하면 Claude는 매 대화마다 "이런 도구들을 쓸 수 있어"라는 목록을 읽어야 합니다. Supabase MCP만 해도 수십 가지 함수 정의를 끌고 옵니다. 대화를 시작하기도 전에 이미 컨텍스트가 줄어드는 겁니다.

둘째, 도구 호출 결과가 통째로 컨텍스트에 쌓입니다. MCP는 외부 서비스의 API 응답 전체를 컨텍스트에 추가합니다. 반면 CLI는 명령어 실행 결과만 올라옵니다. 같은 데이터를 조회해도 MCP 쪽이 훨씬 무겁습니다.

CLI를 쓰면 이 두 문제가 없습니다. Claude는 도구 목록을 따로 읽지 않고, 명령어 출력값만 컨텍스트에 씁니다.

그래서 요즘 추세는 MCP를 항상 켜두지 않고, 꼭 필요한 작업에만 쓰는 것입니다. 평소엔 CLI로 처리하는 쪽이 더 효율적입니다.

CLI로 같은 일 하기

CLI 방식도 사용자 입장에서는 MCP와 다르지 않습니다. 말로 시키면 Claude Code가 알아서 합니다. 차이는 내부 동작입니다. MCP는 프로토콜로 외부 서비스에 직접 연결하지만, CLI는 Claude Code가 터미널 명령어를 실행해서 같은 결과를 얻습니다. 컨텍스트에 올라가는 건 명령어 출력값뿐이라 훨씬 가볍습니다.

Supabase CLI

처음 한 번만 로그인해두면 됩니다.

npx supabase login

이후엔 요청 방식이 MCP 때와 같습니다. Claude Code가 CLI 명령어를 직접 실행합니다. 예를 들어 "테이블 목록 보여줘"라고 하면 내부적으로 이런 명령어를 실행합니다.

npx supabase db execute --project-ref <ref> \
  --sql "SELECT table_name FROM information_schema.tables WHERE table_schema = 'public' ORDER BY table_name;"

데이터 조회나 스키마 변경도 같습니다. 요청하면 Claude Code가 적절한 SQL을 만들어 실행합니다.

일감 테이블에서 상태가 "미수금"인 항목만 보여줘.

일감 테이블에 "마감일" 컬럼을 추가해줘.

Playwright CLI

Playwright도 말로 시키면 됩니다.

브라우저를 열어서 http://localhost:3000 에 접속하고,
회원가입 → 로그인 → 일감 등록 순서로 테스트해줘.
문제가 있으면 알려줘.

MCP는 AI가 브라우저를 직접 조종하지만, CLI 방식에서는 Claude Code가 Playwright 테스트 스크립트를 작성하고 npx playwright test를 실행합니다. 테스트가 실패하면 결과를 읽고 스스로 원인을 찾아 수정합니다. 결과는 같습니다.

언제 MCP, 언제 CLI

판단 기준은 하나입니다. CLI가 있느냐 없느냐.

CLI를 쓸 때가 대부분입니다. git, GitHub CLI, AWS CLI, Supabase CLI처럼 잘 알려진 CLI가 있다면 거의 항상 CLI가 낫습니다. Claude는 이런 도구들의 사용법을 이미 학습했기 때문에 MCP처럼 도구 목록을 컨텍스트에 올릴 필요가 없습니다. 컨텍스트 비용이 거의 0에 가깝습니다.

MCP가 필요한 경우는 세 가지입니다.

CLI 자체가 없는 도구. SSH로 접근할 수 없는 원격 시스템이나 사내 전용 서비스처럼 명령어 도구 자체가 없는 경우입니다.

세션 상태를 유지해야 할 때. MCP는 연결을 끊지 않고 상태를 유지하는 반면, CLI는 명령어를 실행할 때마다 새로 시작합니다.

복잡한 인증 흐름을 중앙에서 관리해야 할 때. OAuth나 SAML처럼 복잡한 인증을 매번 CLI에서 처리하기 어려운 경우입니다.

Supabase나 GitHub처럼 CLI가 잘 갖춰진 서비스라면 MCP보다 CLI 쪽이 더 효율적입니다.

✏️ 실습: Supabase MCP와 CLI 각각 써보기

1단계: Supabase MCP를 연결합니다.

claude mcp add --transport http supabase https://mcp.supabase.com/mcp

Claude Code를 실행하고 테이블 목록을 물어봅니다. 대화가 길어질수록 컨텍스트가 차는 걸 체감해보세요.

2단계: MCP 없이 CLI로 같은 작업을 해봅니다.

npx supabase login

로그인 후 테이블 목록을 다시 요청합니다. Claude Code가 어떤 명령어를 실행하는지 확인해보세요.

CLI를 쓰다 보면 자주 반복하는 명령 패턴이 생깁니다. 다음 장에서는 그걸 스킬로 만드는 방법을 다룹니다.

17장: 스킬 — AI에게 작업 방식 가르치기

스킬이란 무엇인가

스킬은 AI에게 특정 작업을 하는 방법을 가르치는 것입니다. 코드 리뷰를 할 때마다 "보안 문제가 있는지 확인해줘, 에러 처리도 봐줘, 가독성도 체크해줘"라고 말하는 건 번거롭습니다. 이걸 스킬로 만들어두면 /code-review처럼 한 번에 실행할 수 있습니다.

스킬을 만들 때는 Claude Code에게 시키면 됩니다. Claude Code가 .claude/skills/ 폴더 안에 SKILL.md 파일을 직접 만들어줍니다.

스킬이 좋은 또 다른 이유는 컨텍스트를 거의 소모하지 않는다는 점입니다. 스킬은 내용을 한꺼번에 올리지 않습니다. Claude Code가 시작할 때는 각 스킬의 description만 읽습니다. 스킬 하나당 한두 문장 분량입니다. 실제 지시 내용은 그 스킬을 호출할 때 컨텍스트에 올라옵니다. MCP가 연결하는 순간 수십 가지 함수 정의를 통째로 올리는 것과 다릅니다. 스킬을 여러 개 만들어둬도 컨텍스트는 거의 늘지 않습니다.

스킬 파일은 어떻게 생겼나

스킬은 두 부분으로 이루어집니다. 상단의 frontmatter와 그 아래 지시 내용입니다.

---
name: code-review
description: 코드 리뷰를 요청할 때 사용. 보안, 에러 처리, 가독성, 개선점을 순서대로 체크한다.
---

코드 리뷰 시 아래 순서로 진행한다.

1. SQL 인젝션, XSS 등 보안 취약점 확인
2. 예외 처리와 에러 응답이 적절한지 확인
3. 변수명, 함수 길이, 중복 코드 등 가독성 확인
4. 리팩토링이나 성능 개선 여지 제안

frontmatter는 ---으로 감싼 설정 영역입니다. name은 슬래시 커맨드 이름이 되고, description은 Claude Code가 읽는 설명입니다. 설명이 구체적일수록 스킬이 정확한 타이밍에 작동합니다.

자동 실행과 수동 실행

스킬은 두 가지 방식으로 실행됩니다. /code-review처럼 슬래시 커맨드로 직접 부르거나, Claude Code가 대화 흐름을 보고 스스로 불러오는 방식입니다. "이 코드 리뷰해줘"라고 하면 description을 읽고 code-review 스킬을 자동으로 적용합니다.

좋은 스킬의 조건

좋은 스킬의 핵심은 구체적인 단계입니다. 아래 두 스킬을 비교해보면 차이가 명확합니다.

나쁜 스킬

---
name: code-review
description: 코드 리뷰를 한다.
---

코드를 잘 리뷰해줘.

좋은 스킬

---
name: code-review
description: 코드 리뷰를 요청할 때 사용. 보안, 에러 처리, 가독성, 개선점을 순서대로 체크한다.
---

코드 리뷰 시 아래 순서로 진행한다.

1. SQL 인젝션, XSS 등 보안 취약점 확인
2. 예외 처리와 에러 응답이 적절한지 확인
3. 변수명, 함수 길이, 중복 코드 등 가독성 확인
4. 리팩토링이나 성능 개선 여지 제안

"잘 해줘"는 실행할 때마다 다른 결과를 냅니다. "이 4가지를 이 순서로"는 항상 같은 방식으로 작동합니다. 쓰다 보면 "이 작업은 항상 이 방식으로 해야 해"라는 패턴이 보이기 시작합니다. 그게 스킬로 만들 타이밍입니다.

팀과 함께 쓰기

스킬 파일은 프로젝트 폴더 안에 있기 때문에 git에 커밋하면 팀 전체가 쓸 수 있습니다.

git add .claude/skills/
git commit -m "add code-review skill"

팀원이 git pull하면 바로 같은 스킬을 쓸 수 있습니다. 팀이 합의한 코드 리뷰 기준, 커밋 컨벤션, 배포 절차 등을 스킬로 정의해두면 새 팀원도 처음부터 같은 방식으로 일합니다.

저장 위치에 따라 적용 범위가 달라집니다. .claude/skills/에 저장하면 해당 프로젝트에서만 작동하고, ~/.claude/skills/에 저장하면 내 모든 프로젝트에서 쓸 수 있습니다.

스킬 아이디어

기준은 하나입니다. Claude Code에게 같은 말을 반복하고 있다면 스킬로 만들 때가 된 겁니다.

커밋 메시지 작성이 대표적입니다. 팀마다 컨벤션이 다른데, "우리 팀은 feat:, fix: 형식으로 써줘"라고 설명하는 대신 스킬로 만들어두면 됩니다. 배포 전 체크리스트도 스킬로 만들 수 있습니다. "환경변수 확인했어? 마이그레이션 돌렸어?"처럼 실수하기 쉬운 항목을 스킬로 정의해두면 빠뜨리지 않습니다. 새 API 엔드포인트를 만들 때 설계 원칙, 에러 코드, 응답 형식 일관성을 체크하는 스킬도 유용합니다.

앞 장에서 다룬 Supabase 데이터 조회처럼 자주 반복하는 CLI 패턴도 스킬로 만들 수 있습니다. "미수금 항목 뽑아줘"라고만 해도 어떤 테이블에서 어떤 조건으로 조회할지 Claude Code가 알아서 처리합니다.

✏️ 실습: 코드 리뷰 스킬 만들기

1단계: 코드 리뷰 스킬을 만듭니다.

코드 리뷰 스킬을 만들어줘.
보안, 에러 처리, 가독성, 개선점 네 가지를 순서대로 체크하는 스킬이야.

2단계: Claude Code가 만든 .claude/skills/code-review/SKILL.md 파일을 직접 열어봅니다. frontmatter와 지시 내용이 어떻게 구성됐는지 확인하고, 마음에 안 드는 부분이 있으면 직접 수정해보세요.

3단계: 스킬을 실행해봅니다.

/code-review

4단계: 내 프로젝트에 맞는 스킬을 하나 더 만들어봅니다. 커밋 메시지 컨벤션이나 배포 전 체크리스트 중 더 필요한 걸 골라보세요.

18장: 고급 활용 — 서브에이전트, 훅

서브에이전트: AI가 다른 AI에게 작업을 나눠 시키는 방법

지금까지는 Claude Code와 1:1로 대화하면서 작업했습니다. 서브에이전트는 Claude Code가 다른 AI 인스턴스를 만들어서 작업을 나눠 시키는 기능입니다.

예를 들어 "코드 리뷰하고 동시에 테스트도 작성해줘"라고 하면, Claude Code가 코드 리뷰 담당 AI와 테스트 작성 담당 AI를 각각 만들어서 동시에 작업하게 할 수 있습니다.

이 프로젝트에서 두 가지 작업을 동시에 해줘.
서브에이전트를 활용해도 좋아.
1. 코드 리뷰: 보안 문제와 에러 처리를 점검
2. 테스트 작성: 핵심 기능의 테스트 코드 작성

서브에이전트가 유용한 경우는 두 가지입니다.

독립적인 작업을 동시에 할 때. 코드 리뷰와 문서 작성처럼 서로 영향을 주지 않는 작업을 병렬로 처리합니다.

전문 역할을 나눌 때. "보안 전문가 관점에서 봐줘", "UI 전문가 관점에서 봐줘"처럼 각각 다른 시각으로 코드를 검토하게 할 수 있습니다.

단, 단순한 작업에 서브에이전트를 쓰면 오히려 느려질 수 있습니다. 작업이 복잡하지 않을 땐 그냥 Claude Code에게 직접 요청하는 게 빠릅니다. 처음에는 쓸 일이 많지 않습니다. 프로젝트가 커지고 작업이 복잡해지면 그때 활용하면 됩니다.

훅(Hooks): 특정 이벤트에 자동으로 반응하게 만들기

훅은 Claude Code가 특정 행동을 할 때 자동으로 무언가를 실행하는 기능입니다.

예를 들어 Claude Code가 파일을 수정할 때마다 코드 포맷을 자동으로 맞추거나, 작업이 끝났을 때 알림음을 울리는 것들을 설정할 수 있습니다.

훅의 작동 방식

훅은 이벤트 → 조건 → 실행의 구조입니다.

Claude Code에서 특정 이벤트가 발생합니다 (파일 수정, 작업 완료, 권한 요청 등)
설정한 조건(matcher)에 맞는지 확인합니다
조건이 맞으면 지정한 명령어를 자동으로 실행합니다

주요 이벤트

이벤트	언제 발생하는가
`Stop`	Claude Code가 응답을 마치고 멈출 때
`PermissionRequest`	권한 승인이 필요할 때
`PreToolUse`	도구(파일 수정, 명령 실행 등)를 사용하기 직전
`PostToolUse`	도구를 사용한 직후
`Notification`	알림을 보낼 때

실전 예시 1: 작업 완료 알림음

Claude Code가 긴 작업을 하는 동안 다른 일을 하고 있다면, 작업이 끝났을 때 소리로 알려주면 편합니다.

훅을 만들어줘.
Claude Code가 작업을 끝내면 알림음을 재생하는 훅이야.
내가 다른 앱을 보고 있을 때만 소리가 나면 돼.

실전 예시 2: 파일 수정 후 자동 포맷팅

훅을 만들어줘.
Claude Code가 코드 파일을 수정할 때마다 자동으로 prettier를 실행하는 훅이야.

실전 예시 3: 커밋 전 린트 체크

훅을 만들어줘.
Claude Code가 bash로 git commit을 실행하기 직전에
자동으로 린트를 먼저 실행하는 훅이야.

훅 관리하기

설정된 훅은 Claude Code에서 /hooks를 입력하면 확인하고 수정할 수 있습니다. 훅 설정은 ~/.claude/settings.json(전체 프로젝트 공통) 또는 .claude/settings.local.json(현재 프로젝트만)에 저장됩니다.

훅은 편리하지만, 잘못 설정하면 매번 쓸데없는 작업을 실행합니다. 처음에는 없어도 충분하니, 같은 불편을 자꾸 겪을 때 하나씩 추가하세요.

여기까지 왔다면

2장부터 여기까지 따라왔다면, 여러분은 이미 다음을 할 수 있습니다.

Claude Code로 아이디어를 실제 웹 서비스로 만들기
Supabase로 데이터를 저장하고 로그인 기능 구현하기
에러가 나도 AI와 함께 해결하기
Vercel로 인터넷에 배포하고 링크 공유하기
MCP와 CLI로 AI의 능력을 확장하기
스킬로 반복 작업을 자동화하기
훅으로 개발 흐름을 자동화하기

남은 건 하나입니다. 여러분만의 프로젝트를 만드는 것. AI가 코드를 짜는 시대에, 아이디어와 실행력을 가진 사람이 가장 빠릅니다.

✏️ 실습: 작업 완료 알림 훅 만들기

1단계: 작업 완료 알림 훅을 만들어달라고 요청합니다.

훅을 만들어줘.
Claude Code가 작업을 끝내면 알림음을 재생하는 훅이야.
내가 다른 앱을 보고 있을 때만 소리가 나면 돼.

2단계: 긴 작업을 하나 시켜보고 소리가 나는지 확인합니다.

이 프로젝트의 모든 파일을 훑어보고 코드 품질 리포트를 작성해줘.

작업이 끝나는 순간 알림음이 울리면 성공입니다.

3단계: /hooks를 입력해 등록된 훅을 확인하고, 필요 없으면 삭제해봅니다.

에필로그

첫 번째 프로젝트 이후

처음 만든 프로젝트를 배포하고 나면 이상한 감정이 듭니다. 뿌듯하면서도 "이게 맞나?" 하는 느낌. 코드가 왜 동작하는지 완전히 이해하지 못한 채로 뭔가를 만들어냈다는 어색함.

그 감정은 정상입니다.

첫 번째 프로젝트의 목적은 완성도가 아닙니다. "나도 만들 수 있다"는 경험입니다. 코드를 모르는 상태에서 아이디어를 실제로 인터넷에 올리는 경험. 그게 됐으면 이 과정은 성공입니다.

두 번째 프로젝트는 다릅니다. 처음보다 훨씬 빠르고, 훨씬 덜 막힙니다. 이미 흐름을 한 번 경험했기 때문입니다. 세 번째는 더 빠릅니다. 이 속도의 축적이 바이브코딩의 진짜 힘입니다.

첫 번째 프로젝트를 실제로 쓰다 보면 세 가지 일이 생깁니다.

불편한 게 보입니다. 만들 때는 몰랐는데 직접 쓰다 보면 "이게 왜 이렇게 불편하지?"가 나옵니다. 그걸 고치면서 프로젝트가 좋아집니다. 코드를 이해하는 것보다 사용자로서 불편함을 발견하는 능력이 더 중요합니다. 그 능력은 이미 갖고 있습니다.

없는 기능이 보입니다. MVP에 넣지 않았던 것들이 실제로 필요하다는 게 느껴집니다. "이것만 되면 진짜 쓸 만하겠는데"라는 생각이 다음 작업의 시작점입니다.

한계가 보입니다. AI가 잘하지 못하는 것, 복잡해질수록 버거워지는 것들이 보이기 시작합니다. 그 한계를 아는 것 자체가 실력입니다.

코딩을 할 줄 아는 것과 만들 줄 아는 것

오랫동안 "뭔가를 만들려면 코딩을 배워야 한다"는 말이 당연하게 받아들여졌습니다. 코딩은 진입장벽이었습니다. 아이디어가 있어도, 실행할 기술이 없으면 누군가에게 의뢰하거나 포기해야 했습니다.

그런데 사실 개발자들도 모르는 게 있으면 검색하고 AI에게 물어봅니다. 10년 경력의 개발자도 처음 써보는 라이브러리 앞에서는 공식 문서를 찾아보고, 에러 메시지를 구글에 붙여넣습니다. "코드를 안다"는 건 모든 걸 외우고 있다는 뜻이 아닙니다. 어디서 찾아야 하는지 알고, 찾은 걸 맥락에 맞게 판단하는 능력입니다. 그리고 그 능력의 상당 부분은 이제 AI가 담당합니다.

지금은 다릅니다. 코딩을 할 줄 아는 것과 무언가를 만들 줄 아는 것이 분리되기 시작했습니다. AI가 코드를 쓰는 부분을 담당하면서, 사람에게 남은 역할이 바뀌었습니다.

무엇을 만들지 결정하는 것. 만들어진 것이 제대로 된 건지 판단하는 것. 사용자가 어떤 경험을 해야 하는지 설계하는 것. 이것들은 코드를 얼마나 잘 짜느냐와 상관없습니다.

그러니까 지금 이 시대에 유리한 사람은 코드를 잘 짜는 사람이 아닙니다. 뭔가를 만들고 싶다는 아이디어가 있고, 그걸 실제로 실행하는 사람입니다. 기술보다 실행력과 방향이 먼저입니다.

남은 건 만드는 것뿐

이 가이드를 끝까지 읽었다면 도구는 갖춰졌습니다.

남은 건 하나입니다. 만드는 것.

머릿속에 "언젠가 만들어봐야지" 하고 미뤄둔 것이 있다면 지금이 그 언젠가입니다. 완벽한 아이디어를 기다릴 필요 없습니다. 작게 시작하면 됩니다. 나 혼자 쓸 것도 괜찮습니다. 다섯 명이 쓰면 충분합니다.

만들다 보면 더 잘 만드는 방법을 자연스럽게 배웁니다.

부록 1: 슬래시 커맨드 모음

Claude Code 대화 중 언제든 입력할 수 있는 명령어들입니다.

기본 명령어

커맨드	설명
`/login`	첫 실행 시 Anthropic 계정 로그인
`/init`	프로젝트 구조를 분석해서 CLAUDE.md 자동 생성
`/help`	사용 가능한 모든 명령어 목록 보기
`/model`	사용 중인 AI 모델 확인 및 변경
`/exit`	Claude Code 종료

대화 관리

커맨드	설명
`/clear`	대화 내용 전부 초기화. 전혀 다른 작업을 시작하거나 AI가 같은 실수를 반복할 때
`/compact`	지금까지의 대화를 요약해서 컨텍스트 정리. 같은 작업을 이어가는데 대화가 너무 길어졌을 때
`/context`	현재 컨텍스트 윈도우 사용량 확인. 얼마나 여유가 있는지 볼 때
`/btw`	컨텍스트에 기록을 남기지 않고 잠깐 질문할 때

작업 제어

커맨드	설명
`/effort`	AI의 thinking 깊이 조정. `low` / `medium` / `high` 중 선택
`/rewind`	되감기 메뉴 열기. 이전 상태로 대화와 파일을 함께 되돌림
`Esc`	작업 중인 AI를 멈춤. 맥락은 유지
`Esc Esc`	되감기 메뉴 열기 (`/rewind`와 동일)

플러그인

커맨드	설명
`/plugin marketplace add anthropics/claude-code`	Anthropic 데모 마켓플레이스 추가
`/plugin install [이름]@[마켓플레이스]`	플러그인 설치
`/reload-plugins`	설치한 플러그인 활성화
`/frontend-design:frontend-design`	frontend-design 플러그인 실행

프롬프트에서 쓰는 키워드

키워드	설명
`ultrathink`	해당 요청 한 번에 한해 AI의 사고 깊이를 최대로 높임

부록 2: 용어 사전 — 개발편

Git: 코드의 변경 이력을 기록하는 버전 관리 시스템. 게임의 세이브 포인트처럼 원하는 시점으로 돌아갈 수 있다.
GitHub: Git으로 관리하는 코드를 인터넷에 올려두는 서비스. 내 컴퓨터가 고장 나도 코드가 사라지지 않고, 배포할 때도 여기서 가져다 쓴다.
커밋 (commit): 현재 상태를 저장하는 행위. "이 시점의 코드를 저장해둔다"는 뜻.
푸시 (push): 커밋한 내용을 GitHub(원격 저장소)에 올리는 것.
브랜치 (Branch): 코드의 분기. 기존 코드를 건드리지 않고 새 기능을 실험하거나 개발할 때 별도의 브랜치를 만들어 작업한다.
.gitignore: Git이 무시할 파일과 폴더를 지정하는 파일. .env 같은 민감한 파일이 GitHub에 올라가지 않게 막는다.
.env: 환경변수를 저장하는 파일. API 키, 데이터베이스 비밀번호 같은 민감한 정보를 코드와 분리해서 보관한다. GitHub에 올라가면 안 된다.
환경변수 (Environment Variable): .env 파일에 저장하는 비밀 정보. NEXT_PUBLIC_으로 시작하면 브라우저에서도 읽을 수 있고, 그렇지 않으면 서버에서만 읽힌다.
localhost: 내 컴퓨터를 가리키는 주소. localhost:3000은 "내 컴퓨터의 3000번 포트에서 돌아가는 서버"를 뜻한다. 개발 서버를 켜야만 접속된다.
포트 (Port): 같은 컴퓨터 안에서 서비스를 구분하는 번호. localhost:3000의 3000이 포트 번호다. 여러 개발 서버를 동시에 켤 때 각각 다른 포트를 쓴다.
HTTP / HTTPS: 웹에서 데이터를 주고받는 통신 규약. 브라우저가 서버에 "이 페이지 줘"라고 요청하고, 서버가 응답하는 방식을 정의한다. HTTPS는 HTTP에 암호화를 더한 것으로, 주소창에 자물쇠 아이콘이 붙는다. 요즘은 HTTPS가 기본이고, Vercel 배포 시 자동으로 적용된다.
도메인 (Domain): 사람이 읽을 수 있는 웹 주소. naver.com, github.com처럼 숫자로 된 IP 주소 대신 외우기 쉬운 이름으로 서버를 찾아가게 해준다. 기본 배포 주소(myproject.vercel.app)를 내가 산 도메인(myproject.com)으로 바꾸려면 도메인 구매 후 DNS 설정이 필요하다.
npm: Node.js 패키지 매니저. 라이브러리를 설치하고 프로젝트 명령어를 실행하는 도구. npm run dev, npm install 같은 명령어를 입력할 때 쓴다.
package.json: 이 프로젝트가 어떤 라이브러리를 쓰는지, 어떤 명령어가 있는지 기록하는 파일. npm이 이 파일을 읽어서 라이브러리를 설치한다.
라우팅 (Routing): URL 경로와 페이지를 연결하는 것. /는 메인 페이지, /login은 로그인 페이지처럼 URL마다 다른 화면을 보여주는 구조.
API (Application Programming Interface): 프로그램끼리 대화하는 방법. 음식점 주문 창구처럼 정해진 형식으로 요청하면 결과가 돌아온다. 프론트엔드가 서버에 데이터를 요청하거나, 외부 서비스(결제, 지도, AI 등)를 연결할 때 API를 사용한다.
API 키 (API Key): API를 사용할 때 "나"를 증명하는 고유한 문자열. .env 파일에 저장하고, GitHub에 올리거나 프론트엔드 코드에 넣으면 안 된다.
API Route: Next.js에서 서버 쪽 코드를 만드는 방법 중 하나. app/api/ 폴더에 파일을 만들면 브라우저가 아닌 서버에서 실행되는 코드가 된다. Secret key가 필요한 API를 안전하게 호출할 때 쓴다.
JSON (JavaScript Object Notation): 데이터를 주고받을 때 쓰는 텍스트 형식. { "name": "홍길동", "age": 25 } 같은 형태로 이름과 값이 쌍으로 들어간다. API 응답의 대부분이 이 형식이다.
GET / POST: API 요청의 두 가지 기본 방식. GET은 데이터를 가져올 때(조회), POST는 데이터를 보낼 때(등록, 결제, 이메일 발송 등) 쓴다.
상태 코드 (Status Code): API 응답에 포함되는 숫자. 200은 성공, 401은 인증 실패(API 키 문제), 403은 권한 없음, 429는 요청 횟수 초과, 500은 서버 오류를 뜻한다.
콘솔 (Console): 브라우저 개발자 도구의 탭 중 하나. 에러 메시지, 경고, 코드에서 출력한 로그가 여기에 나온다. 에러가 났을 때 가장 먼저 확인하는 곳.
RLS (Row Level Security): Supabase 데이터베이스의 행 단위 접근 제어 기능. "이 데이터는 이 사용자만 읽을 수 있다"는 규칙을 데이터베이스 단에서 설정한다.
MCP (Model Context Protocol): Claude Code에 외부 도구를 연결하는 방법. Supabase, Playwright, Slack 같은 서비스를 AI가 직접 다룰 수 있게 해준다.
빌드 (build): 개발용 코드를 배포에 적합한 형태로 변환하는 과정. Vercel 배포 시 자동으로 실행된다.
배포 (deploy): 만든 서비스를 인터넷에 올려서 누구나 접속할 수 있게 하는 것.
프레임워크 (Framework): 개발의 기반이 되는 도구 모음. Next.js는 웹 프레임워크로, 페이지, 라우팅, 서버 기능을 통합 제공한다.
라이브러리 (Library): 특정 기능을 쉽게 쓸 수 있도록 미리 만들어둔 코드 모음. 프레임워크보다 범위가 좁고 특화되어 있다.
스키마 (Schema): 데이터베이스의 구조 정의. 어떤 테이블이 있고, 각 테이블에 어떤 컬럼이 있는지를 나타낸다.
CRUD: 데이터 조작의 네 가지 기본 동작. 생성(Create) / 읽기(Read) / 수정(Update) / 삭제(Delete).
디버깅 (Debugging): 코드의 오류를 찾아서 고치는 과정. 에러 메시지를 읽고, 원인을 파악하고, 수정하는 것 전체를 말한다.
할루시네이션 (Hallucination): AI가 틀린 정보를 마치 사실인 것처럼 자신 있게 말하는 현상. 존재하지 않는 라이브러리를 설치하려 하거나, 없는 API를 호출하는 식으로 나타난다. 실행해서 에러가 나면 그걸 AI에게 보여주면 된다.

부록 3: 용어 사전 — UI편

프론트엔드 (Frontend): 브라우저에 보이는 화면 전체. 버튼, 텍스트, 이미지, 입력 폼 등 사용자가 눈으로 보고 직접 조작하는 부분.
컴포넌트 (Component): 화면을 이루는 독립적인 단위. 버튼, 카드, 네비게이션 바처럼 여러 페이지에서 반복해서 쓰는 UI 요소를 재사용 가능하게 만든 것.
레이아웃 (Layout): 화면 요소들을 어떻게 배치할지에 대한 구조. 어느 쪽에 사이드바가 오고, 헤더와 푸터는 어떻게 생겼는지 등.
반응형 디자인 (Responsive Design): 화면 크기에 따라 레이아웃이 자동으로 조정되는 디자인. 컴퓨터에서는 3열로 보이던 카드가 스마트폰에서는 1열로 바뀌는 것.
브레이크포인트 (Breakpoint): 반응형 디자인이 전환되는 기준 화면 너비. 예를 들어 768px 이하면 모바일 레이아웃으로 바뀌는 식.
뷰포트 (Viewport): 브라우저에서 실제로 보이는 화면 영역. 개발자 도구에서 모바일 화면을 시뮬레이션할 때 뷰포트 크기를 조정한다.
헤더 (Header): 페이지 상단에 고정되는 영역. 보통 로고와 네비게이션 메뉴가 들어간다.
네비게이션 바 (Navigation Bar): 페이지 간 이동을 위한 메뉴. 주로 헤더 안에 위치한다.
햄버거 메뉴: 모바일에서 네비게이션 메뉴를 숨기고 ≡ 아이콘으로 표시하는 방식. 아이콘 모양이 햄버거처럼 생겼다고 해서 붙여진 이름.
탭 (Tab): 콘텐츠를 여러 탭으로 나눠 전환하는 UI. "전체 / 진행중 / 완료"처럼 같은 공간에서 다른 내용을 보여줄 때 쓴다.
아코디언 (Accordion): 제목을 클릭하면 내용이 펼쳐지고, 다시 클릭하면 접히는 UI. FAQ 페이지에서 질문을 클릭하면 답변이 나타나는 방식이 대표적인 예.
드롭다운 (Dropdown): 클릭하면 선택 목록이 아래로 펼쳐지는 UI. 카테고리 선택, 정렬 기준 선택 등에 쓰인다.
사이드바 (Sidebar): 화면 왼쪽이나 오른쪽에 위치하는 패널. 보통 메뉴나 필터, 추가 정보를 담는다.
드로어 (Drawer): 버튼을 누르면 화면 옆에서 슬라이드로 나타나는 패널. 사이드바와 비슷하지만 평소에는 숨겨져 있다가 필요할 때만 열린다. 모바일 메뉴에 자주 쓰인다.
바텀 시트 (Bottom Sheet): 모바일에서 화면 하단에서 위로 올라오는 패널. 추가 옵션, 상세 정보, 간단한 폼을 띄울 때 모달 대신 많이 쓴다. 손가락으로 아래로 쓸어내리면 닫힌다.
오버레이 (Overlay): 모달이나 드로어가 열릴 때 배경에 깔리는 반투명한 어두운 레이어. 현재 포커스가 팝업에 있음을 시각적으로 알려주고, 클릭하면 닫히는 경우가 많다.
카드 (Card): 정보를 박스 형태로 묶어서 보여주는 UI 요소. 배경색, 테두리, 그림자를 주어 시각적으로 구분한다.
그리드 (Grid): 격자 형태로 요소를 배치하는 레이아웃. "카드를 한 줄에 3개씩 배치해줘"가 그리드 레이아웃.
모달 (Modal): 현재 페이지 위에 뜨는 팝업 창. 삭제 확인, 로그인 폼, 상세 정보 표시 등에 쓰인다. 배경에 오버레이가 깔린다.
툴팁 (Tooltip): 마우스를 요소 위에 올렸을 때 나타나는 짧은 설명 텍스트. 아이콘 버튼처럼 기능이 직관적으로 보이지 않는 요소에 달아둔다.
배지 (Badge): 숫자나 상태를 표시하는 작은 레이블. 알림 아이콘 위에 붙는 빨간 숫자, "NEW" 태그, "완료" 상태 표시 등이 배지다.
토스트 메시지 (Toast Message): 화면 한쪽에 잠깐 나타났다 자동으로 사라지는 알림. "저장됐습니다", "오류가 발생했습니다" 같은 피드백을 줄 때 쓴다.
스피너 (Spinner): 로딩 중임을 나타내는 회전하는 원형 아이콘. 데이터를 불러오거나 저장하는 동안 버튼이나 화면 중앙에 표시한다.
스켈레톤 UI (Skeleton UI): 데이터를 불러오는 동안 실제 콘텐츠 자리에 보여주는 회색 자리 표시자. 스피너보다 레이아웃 변화 없이 자연스럽게 로딩을 표현할 수 있다.
프로그레스 바 (Progress Bar): 작업 진행 상태를 가로 막대로 보여주는 UI. 파일 업로드, 단계별 폼, 프로필 완성도 등에 쓰인다.
페이지네이션 (Pagination): 긴 목록을 여러 페이지로 나눠 1, 2, 3... 버튼으로 이동하는 방식. 인피니트 스크롤과 반대 개념.
인피니트 스크롤 (Infinite Scroll): 페이지 맨 아래까지 스크롤하면 다음 데이터가 자동으로 이어서 로드되는 방식. 인스타그램, 트위터 피드 같은 형태.
플로팅 버튼 (Floating Action Button): 화면 오른쪽 하단 등에 고정되어 떠 있는 버튼. 가장 핵심적인 행동(글쓰기, 추가 등)을 항상 접근 가능하게 배치할 때 쓴다.
빈 상태 (Empty State): 데이터가 하나도 없을 때 보여주는 화면. "아직 등록된 항목이 없습니다"처럼 안내 메시지와 행동 유도 버튼을 함께 보여주는 것이 좋다.
CTA (Call to Action): 사용자에게 특정 행동을 유도하는 버튼이나 링크. "시작하기", "지금 신청", "무료로 만들기" 같은 것들.
피드백 (Feedback): 사용자 행동에 대한 시스템의 반응. 버튼을 눌렀을 때 로딩 스피너가 도는 것, 저장 성공 시 토스트가 뜨는 것, 입력 오류 시 빨간 테두리가 생기는 것 모두 피드백이다.
폼 (Form): 사용자 입력을 받는 요소들의 묶음. 이름, 이메일, 비밀번호 입력 필드와 제출 버튼이 모여 있는 것이 폼이다.
인풋 (Input): 텍스트를 입력하는 필드. 한 줄짜리 텍스트 입력, 비밀번호 입력, 검색창 등이 모두 인풋이다.
사용자 흐름 (User Flow): 사용자가 서비스를 이용하는 순서와 경로. "메인 → 로그인 → 대시보드 → 항목 등록 → 목록 확인"처럼 각 화면의 연결을 설계하는 것.
다크 모드 (Dark Mode): 어두운 배경에 밝은 텍스트를 쓰는 색상 테마. 눈의 피로를 줄이고 배터리를 아끼는 효과가 있어 많은 서비스가 라이트/다크 모드 전환 기능을 제공한다.
색상 코드 (HEX Code): 색상을 # 뒤에 6자리 영문+숫자로 표현하는 방식. #ffffff는 흰색, #000000은 검정, #2563EB는 파란색. 구글에 "color picker"를 검색하면 원하는 색의 코드를 바로 찾을 수 있다.
z-index: 화면에서 요소가 쌓이는 순서. 숫자가 높을수록 앞에 표시된다. 모달이 다른 요소 위에 나타나는 것이 z-index 덕분이다.

프롤로그

1장: 코딩의 규칙이 바뀌었다

바이브코딩이란 무엇인가

전통적 코딩 vs 바이브코딩

용어를 둘러싼 논쟁

바이브코딩으로 할 수 있는 것들

2장: 도구와 환경 설정

AI 모델 vs 하네스

Claude Code와 Antigravity

터미널 기본 명령어 5개

Claude Code 대화 중 알아두면 좋은 것들

Claude Code 설치하기

macOS에 설치

Windows에 설치

설치 후 첫 실행

Antigravity 설치 및 Claude Code 연동

✏️ 실습: Claude Code에게 자기소개 페이지를 만들게 하고 브라우저에서 열어보기

3장: 프롬프트 — 바이브코딩의 핵심 스킬

프롬프트란 무엇인가

나쁜 프롬프트 vs 좋은 프롬프트

예시 1: 투두 앱

예시 2: 에러 수정

예시 3: 디자인 수정

5가지 프롬프트 패턴

패턴 1. 구체적 지시

패턴 2. 역할 부여

패턴 3. 단계 분리

패턴 4. 예시 제공

패턴 5. 제약 조건

프롬프트를 점진적으로 발전시키기

AI가 엉뚱한 방향으로 갔을 때

바이브코딩 프롬프트 실전 팁

✏️ 실습: 같은 앱을 3가지 다른 프롬프트로 만들어보고 차이 비교하기

4장: AI와 대화 전략

한 번에 다 시키기 vs 단계별로 시키기

Reverse Prompting — AI에게 먼저 질문하게 하기

언제 쓰면 좋은가

권한 모드 — AI에게 얼마나 맡길 것인가

바이브코더가 쓰는 세 가지 모드

터미널(CLI)에서 전환하기

Antigravity에서 전환하기

추천 흐름

Plan 모드

Plan 모드 실제 사용 흐름

ultrathink

알아두면 좋은 슬래시 커맨드

AI가 틀렸을 때

에러 메시지가 나올 때

결과가 원하는 것과 다를 때

같은 실수를 반복할 때

작업 중간에 멈추고 싶을 때

컨텍스트 관리

AI는 코드는 읽지만 맥락은 모른다

맥락이 결과의 질을 결정한다

한 대화에 하나의 작업

컨텍스트를 아끼는 방법

컨텍스트가 꽉 찼을 때

바이브코딩에서 사람의 역할

할루시네이션과 검증

5장: CLAUDE.md — AI에게 나를 기억시키기

CLAUDE.md가 왜 중요한가

/init — 자동으로 만들기

좋은 CLAUDE.md의 구조

넣어야 할 것들

넣지 말아야 할 것들

계속 다듬어가기

CLAUDE.md 파일 위치

✏️ 실습: 내 프로젝트용 CLAUDE.md 만들어보기

6장: 아이디어를 설계로 바꾸는 방법

"이런 거 만들고 싶어"에서 시작하기

아이디어를 AI가 이해할 수 있게 정리하는 방법

AI에게 인터뷰 시키기

MVP란 무엇인가

프론트엔드, 서버, 데이터베이스

AI의 산출물과 소프트웨어가 동작하는 방식

기술 스택 추천받기

✏️ 실습: 내 아이디어를 AI에게 설명하고 설계까지 정하기

7장: 프로젝트 초기화와 Git

프로젝트 초기화

CLAUDE.md 작성