본문으로 건너뛰기
오토프로그 홈

8강: 첫 프로젝트

v4
작성 2026-04-13읽는 시간 9분

오늘 안에 내 URL을 갖게 됩니다

드디어 만들 시간이에요​

7강에서 프롬프트의 3요소(목표와 기준, 상황 설명, 울타리)를 배웠어요. "맛있는 거 주세요"와 "매운 건 빼고, 된장찌개에 밥 따로"의 차이를 느끼셨죠? 7강 마지막에 이렇게 말씀드렸어요. "다음 강에서는 오늘 배운 프롬프트 기술을 총동원해서, 진짜 내 URL을 가진 웹페이지를 만들어볼 거예요."

바로 오늘이에요.

집을 짓는 것에 비유하면, 6강에서 설계도(PRD)를 그렸고, 7강에서 벽돌공에게 말하는 법(프롬프트)을 배웠어요. 이제 진짜로 벽돌을 쌓을 차례예요. 그런데 걱정 마세요. 오늘 지을 건 초고층 빌딩이 아니라, 예쁜 명함 카드 한 장이에요. 파일 2개면 끝나요.

오늘이 끝나면 여러분은 인터넷 주소창에 내 이름이 적힌 URL을 입력하고, 전 세계 누구에게나 "이거 내 페이지야!" 하고 보여줄 수 있어요.

기술 선택, 어렵게 생각하지 마세요​

뭔가를 만들기 전에 "어떤 도구로 만들지?" 를 정해야 해요. 레고로 만들지, 찰흙으로 만들지 고르는 거예요. 바이브 코더가 기술을 고를 때는 딱 3가지만 따지면 돼요.

질문 1: 배포가 쉬워?​

만든 걸 인터넷에 올리는 걸 배포(Deploy) 라고 해요. 식당으로 치면 "가게 문을 여는 것"이에요. 아무리 맛있는 음식을 만들어도 가게 문을 못 열면 아무도 못 먹잖아요. 배포가 쉬운 도구를 골라야 해요.

질문 2: AI가 에러 고치기 쉬워?​

모든 코드에는 에러가 생겨요. 중요한 건 에러 자체가 아니라, AI가 에러를 빨리 고칠 수 있는 환경인지예요. 많은 사람이 쓰는 기술일수록 AI가 잘 알아요. 희귀한 기술을 쓰면 AI도 헤매요.

질문 3: 나중에 키울 수 있어?​

처음엔 작게 시작하지만, 나중에 기능을 추가할 수 있어야 해요. "이 도구로는 여기까지밖에 못 해요"라는 한계가 빨리 오면 처음부터 다시 만들어야 해요.

그래서 첫 프로젝트 정답은?​

HTML(웹페이지의 뼈대를 잡는 언어) + CSS(웹페이지를 꾸미는 디자인 언어) 예요.

기준HTML + CSS
배포GitHub Pages에 파일만 올리면 끝
에러 해결AI가 가장 잘 아는 기술 1위
확장성JavaScript(웹페이지에 동작을 넣는 언어)를 더하면 기능 추가 가능
파일 수1~2개면 충분

참고로, 지금 여러분이 읽고 있는 이 오토프로그 랩스 사이트는 Docusaurus(문서 사이트 생성 프레임워크)로 만들어져 있어요. 프레임워크(React, Next.js 같은 도구 묶음)는 11강에서 다뤄요. 지금은 가장 간단한 방법으로 첫 성공을 맛보는 게 중요해요.

실습: 나를 소개하는 웹페이지 만들기​

여기서부터가 오늘의 본 게임이에요. 5단계로 나눠서 하나씩 따라가 볼게요.

1단계: 프로젝트 폴더 만들기​

먼저 작업할 폴더를 만들어야 해요. 3강에서 터미널 명령어를 배웠죠? 잊어도 괜찮아요. 일반 터미널(Windows는 명령 프롬프트, Mac은 터미널 앱)을 열고 그대로 따라하세요.

# 홈 폴더로 이동
cd ~

# 프로젝트 폴더 만들기
mkdir my-page

# 폴더 안으로 이동
cd my-page

그 다음, 이 폴더에서 Claude Code를 시작하세요.

# Claude Code 시작
claude

2단계: 뼈대 만들기 — "구조부터 잡아줘"​

7강에서 배운 프롬프트 기술을 써볼 시간이에요. Claude Code 대화창에 아래 프롬프트를 그대로 복사해서 붙여넣으세요.

나는 코딩을 1줄도 모르는 바이브 코더야.
나중에 내가 코드를 열어봐도 알아볼 수 있게, 초보자 기준으로 쉽게 만들어줘.

나를 소개하는 웹페이지를 만들어줘.
HTML 파일 1개, CSS 파일 1개, 총 2개 파일로 만들어.

구조 (위에서 아래 순서):
1. 히어로 섹션(페이지 맨 위 대문 영역) — 내 이름 "홍길동", 한 줄 소개 "AI와 함께 만드는 사람"
2. 자기소개 섹션 — "안녕하세요! 바이브 코딩으로 새로운 가능성을 탐험하고 있습니다." 2~3문장
3. 관심 분야 섹션 — 카드 3개 (바이브 코딩 / AI 활용 / 웹 제작)
4. 연락처 섹션 — 이메일, GitHub 링크

안 할 것:
- JavaScript 사용하지 마
- 외부 라이브러리 사용하지 마
- 이미지 파일 사용하지 마
- 복잡한 애니메이션 넣지 마

디자인:
- 다크 배경(#0a0a0a), 밝은 글씨(#e0e0e0), 시안 포인트(#00e5ff)
- 모바일에서도 깨지지 않게 반응형(화면 크기에 맞춰 자동 조절)으로
- 깔끔하고 미니멀한 느낌

파일명: index.html, style.css
코드에 한글 주석으로 각 부분이 뭘 하는지 설명 달아줘.

목표와 기준(나를 소개하는 웹페이지를 파일 2개로, 초보자 기준 · 한글 주석까지), 상황(코딩 모르는 바이브 코더), 울타리(안 할 것 4가지)가 다 들어있죠? 7강에서 배운 대로예요.

"너는 10년차 개발자야" 같은 역할 부여가 없다는 점도 눈여겨보세요. 7강에서 말씀드렸듯이 클로드 코드는 이미 코딩 전문 도구라서, 역할을 매번 붙여줄 필요가 없어요. 그 자리에 "어떤 품질로 만들지" 를 적는 게 훨씬 효과가 좋아요.

Claude가 index.html과 style.css 파일을 만들어줄 거예요.

3단계: 브라우저에서 확인하기​

Claude가 파일을 만들었으면, 바로 눈으로 확인해 볼게요.

클로드 코드 대화창에서 !를 맨 앞에 붙이면 터미널 명령어를 바로 실행할 수 있어요. 결과가 나오면 클로드가 한마디 덧붙여 주기도 해요. 단, !는 터미널에서 연 클로드 코드에서만 되고, VS Code 확장 프로그램의 채팅 창에서는 안 돼요.

# 만들어진 파일 목록 확인
! ls

# 브라우저에서 열기 (Windows)
! start index.html

# 브라우저에서 열기 (Mac)
! open index.html

브라우저에 내 이름과 소개가 보이나요? 축하해요. 방금 여러분이 첫 웹페이지를 만든 거예요.

4단계: 내용 바꾸기 — "이름이랑 소개를 수정해줘"​

"홍길동"은 예시 이름이에요. 내 정보로 바꿔야겠죠? Claude Code 대화창에 이렇게 말하세요.

방금 만든 웹페이지에서 내용을 수정해줘.

1. 이름: "홍길동" → "내 실제 이름"으로 변경
2. 한 줄 소개: "AI와 함께 만드는 사람" → 내가 원하는 문구로 변경
3. 자기소개 문장: 내 상황에 맞게 수정
4. 관심 분야 카드 3개: 내 관심사로 변경
5. 연락처: 내 이메일과 GitHub 주소로 변경

index.html 파일만 수정해. style.css는 건드리지 마.

여기서 중요한 포인트 2가지가 있어요.

  • "내 실제 이름" 부분에 진짜 여러분의 이름을 넣으세요
  • "style.css는 건드리지 마" — 7강에서 배운 수정 범위 제한이에요

수정 후 브라우저를 새로고침(F5)하면 바뀐 내용이 보여요.

5단계: 스타일 다듬기 — "디자인을 조금 바꿔줘"​

내용이 들어갔으면, 이제 디자인을 미세 조정할 차례예요. 7강에서 배운 레퍼런스 기법을 써볼게요.

style.css만 수정해줘. index.html은 건드리지 마.

수정할 것:
- 히어로 섹션 이름 글씨를 더 크게 (48px)
- 카드에 마우스를 올리면 시안색 테두리가 나타나게
- 섹션과 섹션 사이 간격을 넉넉하게 (80px)
- 전체적으로 Apple 사이트처럼 넓은 여백 느낌으로

"Apple 사이트처럼"이 바로 레퍼런스예요. "여백 넓게"보다 훨씬 정확한 지시가 돼요.

완성된 페이지가 마음에 들 때까지 Claude에게 디자인 수정을 요청하세요. 색상, 글씨 크기, 간격 등 뭐든 말로 시키면 돼요. 이게 바이브 코딩이에요.

GitHub Pages로 배포하기 — 내 URL 완성​

지금까지 만든 페이지는 내 컴퓨터에서만 보여요. 이걸 인터넷에 올려서 누구나 볼 수 있게 만들어 볼게요. 이 과정이 배포(Deploy) 예요.

GitHub Pages는 GitHub(3강에서 가입한 코드 저장소 서비스)가 제공하는 무료 웹사이트 호스팅 서비스예요. 호스팅(Hosting)이란 "내 파일을 인터넷에 올려두는 것"이에요. 식당으로 치면, 가게 자리를 무료로 빌려주는 거예요.

한 가지만 미리 알아두세요. 무료 계정에서는 저장소를 Public(공개)으로 만들어야 GitHub Pages를 쓸 수 있어요. 저장소를 비공개로 두고 페이지를 열려면 유료 플랜(Pro 이상)이 필요해요. 우리는 어차피 남들에게 보여줄 소개 페이지니까 Public으로 만들면 돼요.

1단계: GitHub 저장소 만들기​

3강에서 GitHub에 가입했죠? 이제 내 웹페이지를 올릴 저장소(코드를 보관하는 창고)를 만들 거예요.

Claude Code 대화창에서 이렇게 하세요.

# 현재 폴더를 Git 저장소로 만들기 (갈래 이름을 main 으로)
! git init -b main

# 모든 파일을 세이브 목록에 담기
! git add .

# 첫 번째 세이브 (커밋)
! git commit -m "첫 번째 커밋: 내 소개 페이지"

5강에서 배운 add → commit → push의 처음 두 단계예요. 5강에서 배웠듯이 -b main 은 작업 갈래 이름을 main 으로 맞추는 부분이에요. 깃허브가 main 을 쓰는데 깃은 아직 master 라는 옛날 이름을 붙이기 때문에, 이걸 빼먹으면 잠시 뒤 push 단계에서 막혀요.

2단계: GitHub에 저장소 만들고 연결하기​

이제 GitHub 웹사이트에서 저장소를 만들어야 해요. 여기만 웹 브라우저에서 직접 해주세요.

  1. github.com 에 로그인
  2. 오른쪽 위 + 버튼 → New repository 클릭
  3. Repository name에 내깃허브아이디.github.io 입력 (예: honggildong.github.io)
  4. Public(공개)으로 선택
  5. 나머지는 건드리지 말고 Create repository 클릭

저장소 이름이 내깃허브아이디.github.io 형식이어야 해요. 이 이름 규칙이 GitHub Pages의 핵심이에요.

여기서 초보자가 가장 많이 걸리는 지점이 하나 있어요. 아이디에 대문자가 섞여 있어도, 저장소 이름은 전부 소문자로 적어야 해요. 예를 들어 아이디가 HongGilDong이면 저장소 이름은 honggildong.github.io 예요. 대문자를 그대로 쓰면 페이지가 안 열려요.

3단계: 코드 올리기 (push)​

저장소가 만들어졌으면, Claude Code 대화창에서 코드를 올려주세요.

# GitHub 저장소와 내 폴더를 연결
! git remote add origin https://github.com/내깃허브아이디/내깃허브아이디.github.io.git

# 코드를 GitHub에 올리기
! git push -u origin main

내깃허브아이디 부분에 여러분의 실제 GitHub 아이디를 넣으세요. 예를 들어 GitHub 아이디가 honggildong이면 https://github.com/honggildong/honggildong.github.io.git 이 돼요.

4단계: GitHub Pages 켜기 (이 단계를 빼먹으면 페이지가 안 열려요)​

파일을 올렸다고 해서 사이트가 저절로 켜지지는 않아요. "이 저장소를 웹사이트로 써라"고 GitHub에 한 번 알려줘야 해요. 여기만 다시 웹 브라우저에서 해주세요.

  1. 내 저장소 페이지에서 위쪽 Settings(설정) 클릭
  2. 왼쪽 메뉴에서 Pages 클릭
  3. "Build and deployment" 아래 Source에서 Deploy from a branch 선택
  4. 그 아래 Branch에서 main 을 고르고, 폴더는 /(root) 로 두기
  5. Save(저장) 클릭

가게로 치면 지금까지는 가게 안에 물건을 채운 거고, 이 단계가 간판을 달고 문을 여는 것이에요. 한 번만 해두면, 다음부터는 git push만 해도 알아서 반영돼요.

5단계: 내 URL 확인하기​

Save를 누르면 GitHub가 사이트를 만들기 시작해요. 보통 1~2분이면 뜨지만, 공식적으로는 최대 10분까지 걸릴 수 있어요. 잠시 기다린 후 브라우저 주소창에 이렇게 입력하세요.

https://내깃허브아이디.github.io

내 웹페이지가 보이나요? 이 URL을 카카오톡으로 친구에게 보내보세요. 친구 휴대폰에서도 내 페이지가 보일 거예요.

축하합니다. 여러분은 방금 인터넷에 내 웹사이트를 배포한 거예요. 코드 한 줄 직접 치지 않고, AI에게 말로 시켜서요. 이게 바이브 코딩이에요.

페이지 수정 후 업데이트하기​

배포한 뒤에 "아, 이 부분 고치고 싶다" 하면 어떻게 할까요? 간단해요.

  1. Claude Code에서 수정을 요청해요 ("히어로 섹션 배경색을 남색으로 바꿔줘")
  2. 브라우저에서 로컬 파일로 확인해요 (! start index.html)
  3. 마음에 들면 다시 올려요
# 수정한 파일을 세이브 목록에 담기
! git add .

# 수정 내용 세이브
! git commit -m "디자인 수정: 히어로 배경색 변경"

# GitHub에 올리기
! git push

push 하고 잠시(보통 1~2분, 길면 10분) 기다리면 수정한 내용이 자동으로 반영돼요. 처음 한 번 Settings에서 Pages를 켜뒀으니, 이제는 다시 설정하거나 배포 버튼을 누를 필요가 없어요. 이게 GitHub Pages의 장점이에요.

클로드 코드 터미널에서는 이렇게​

지금까지의 전체 과정을 명령어만 뽑아서 정리해 드릴게요. 프롬프트는 위 2단계의 것을 그대로 쓰시면 돼요.

# ── 1. 프로젝트 폴더 만들고 클로드 코드 켜기 (일반 터미널에서) ──
cd ~
mkdir my-page
cd my-page
claude

여기서 2단계 프롬프트를 입력해 파일을 만든 뒤, 클로드 코드 대화창에서 이어서 진행하세요.

# ── 2. 브라우저에서 확인 (Windows는 start, Mac은 open) ──
! start index.html

# ── 3. Git 세이브 ──
! git init -b main
! git add .
! git commit -m "첫 번째 커밋: 내 소개 페이지"

# ── 4. GitHub에 올리기 (저장소를 먼저 만든 후) ──
! git remote add origin https://github.com/내아이디/내아이디.github.io.git
! git push -u origin main

마지막으로 브라우저에서 Settings → Pages → Source: Deploy from a branch → Branch: main / (root) → Save 를 한 번 해주세요. 이 단계까지 마쳐야 사이트가 켜져요.

잠시(보통 1~2분, 길면 10분) 후 https://내아이디.github.io 에 접속하면 내 페이지가 보여요.

잘 안 될 때 — 자주 묻는 질문​

"push 했는데 페이지가 안 보여요"​

먼저 4단계(Settings → Pages)를 했는지 확인하세요. 이걸 건너뛰면 아무리 기다려도 페이지가 안 열려요. 가장 흔한 원인이에요.

설정을 했다면 GitHub Pages가 빌드(파일을 웹사이트로 변환하는 작업)하는 시간이 필요해요. 보통 1~2분, 공식적으로는 최대 10분까지 걸려요. 그래도 안 되면 저장소가 Public인지, 저장소 이름이 전부 소문자인지 다시 확인해 보세요.

"src refspec main does not match any 에러가 나요"​

깃 초기화를 할 때 -b main 을 빼먹어서, 지금 갈래 이름이 main 이 아니라 master 인 거예요. 올릴 main 이 없다는 뜻의 에러예요. 이름만 바꿔주면 됩니다.

# 지금 갈래 이름을 main 으로 바꾸고 다시 올리기
! git branch -M main
! git push -u origin main

Settings → Pages의 Branch 목록에 main 이 안 보일 때도 원인은 같아요. 위 명령을 실행하고 새로고침하면 나타나요.

"git push가 안 돼요"​

GitHub는 이제 비밀번호로는 인증이 안 돼요. (예전에는 아이디·비밀번호를 입력했지만 지금은 막혔어요.) 가장 쉬운 해결책은 GitHub가 만든 gh 명령어로 브라우저에서 한 번 로그인해두는 거예요.

# GitHub CLI 로그인 (브라우저가 열리면 로그인 후 승인)
! gh auth login

gh 가 설치되어 있지 않다는 메시지가 나오거나 다른 에러가 뜨면, Claude Code 대화창에 그 에러를 그대로 붙여넣고 물어보세요.

git push를 하려는데 이런 에러가 나. 어떻게 해결해?
(여기에 에러 메시지를 붙여넣기)

7강에서 배웠죠? 에러 메시지를 그대로 보여주는 게 가장 좋은 프롬프트예요.

"디자인이 마음에 안 들어요"​

Claude에게 계속 수정을 요청하면 돼요. 바이브 코딩의 장점이 바로 이거예요. "카드 모서리를 더 둥글게 해줘", "글씨 크기를 좀 더 키워줘" 처럼 말로 시키세요. 한 번에 완벽할 필요 없어요. 고치고, 확인하고, 또 고치고. 이 과정 자체가 개발이에요.

이번 강에서 기억할 것​

핵심만 정리해 볼게요.

  1. 기술 선택은 3가지만 따지세요. 배포가 쉬운가, AI가 잘 아는가, 나중에 키울 수 있는가. 첫 프로젝트는 HTML + CSS가 정답이에요.

  2. Claude에게 단계별로 시키세요. 구조 먼저 → 내용 채우기 → 스타일 입히기. 한 번에 "완벽하게 만들어줘"가 아니라 하나씩, 하나씩요.

  3. 프롬프트에 "안 할 것"을 꼭 넣으세요. "JavaScript 쓰지 마", "다른 파일 건드리지 마" 한 줄이 결과물의 품질을 크게 바꿔요.

  4. GitHub Pages 배포는 "세이브 3단계 + 스위치 1번"이에요. git init -b main 으로 시작해서 git add → git commit → git push 로 파일을 올리고, 처음 한 번만 Settings → Pages 에서 Branch를 main으로 지정해 사이트를 켜세요. 그 뒤로는 push만 하면 자동으로 반영돼요. 초보자가 가장 많이 막히는 두 지점이 -b main 빼먹기와 Settings → Pages 건너뛰기예요.

  5. 한 번에 완벽하지 않아도 괜찮아요. 만들고, 보고, 고치고, 다시 올리고. 이 반복이 바이브 코딩의 핵심이에요.

오늘 프로젝트를 만들면서 느끼셨을 거예요. Claude에게 매번 "한국어로 해", "JavaScript 쓰지 마" 같은 규칙을 반복해서 말하는 게 꽤 번거롭다는 걸요. 다음 강에서는 이 문제를 해결하는 CLAUDE.md를 다뤄요. 규칙을 한 번만 적어두면 AI가 매번 알아서 따라요. 프로젝트마다 AI에게 주는 설명서를 만드는 거예요.

이런 분께 추천해요​

첫 프로젝트는 "내가 진짜 뭔가를 만들 수 있구나!" 하는 자신감을 주는 경험이에요.

  • 바이브 코딩을 배우고 있는데 아직 아무것도 만들어본 적 없는 분 — 오늘이 첫 번째예요. HTML 2개 파일로 시작하니까 부담 없어요.
  • 개인 웹사이트가 갖고 싶었지만 "개발자만 가능한 거 아냐?" 하고 포기한 분 — GitHub Pages 무료 배포로 오늘 안에 내 URL을 가질 수 있어요.
  • 6~7강에서 PRD와 프롬프트를 배웠는데, 실전에 써보고 싶은 분 — 오늘 배운 프롬프트 기술을 총동원하는 첫 실전이에요. 배운 건 써먹어야 내 것이 돼요.

참고 링크​

▸개정 이력4건
  • v42026-07-191~20강 공통으로 반복되던 `!` 셸 모드 안내 문구를 하나로 통일 — 실행 결과에 클로드가 한마디 덧붙인다는 현행 동작과, 터미널에서 연 클로드 코드에서만 되고 VS Code 확장 채팅 창에서는 안 된다는 조건을 추가
  • v32026-07-19git init → git init -b main 으로 정정(깃 기본 갈래가 master라 git push -u origin main 과 Pages Branch 지정이 모두 실패하던 문제) + refspec 에러 FAQ 추가, 7강과 모순되던 '너는 10년차 개발자야' 역할 부여 프롬프트 삭제, 마무리 요약에서 프롬프트 중복 제거
  • v22026-07-19GitHub Pages 배포 절차 보강(Settings→Pages 소스 지정 단계를 본문 필수 단계로 승격), 반영 시간을 공식 표기(보통 1~2분 · 최대 10분)로 정정, 무료 계정은 Public 저장소 조건 · 저장소 이름 소문자 규칙 추가, push 인증 FAQ를 gh auth login으로 갱신, 선행 강 번호 정정(터미널 · 깃허브 가입=3강), 7강 3요소 명칭 정합, MDN 링크 2개 최신 주소로 교체
  • v12026-04-13초판