Vibe Coding 가이드 v1.0: AI 보조 개발을 위한 완벽 매뉴얼

이 문서는 바이브 코드로 앱/서비스를 개발할 때, 코딩 경험자 뿐만 아니라, 코딩 무경험자도 따라하실 수 있도록 만든 가이드입니다. 코딩 경험이 적은 주니어 개발자와 기획자도 이 순서대로 진행하면 안정적으로 결과물을 만들 수 있습니다.

핵심 원칙: 코드를 바로 작성시키지 말고, 문서(Design.md, ToDo.md)를 먼저 만들게 한 후 개발을 시작하는게 좋습니다.

0. 전체 흐름 요약

[1] Concept.md 작성 요청

↓

[2] Design.md 작성 (UI/UX 기준 문서)

↓

[3] 기술 스택 결정 (아래 결정 트리 참고)

↓

[4] ToDo.md 작성 (모듈 단위 기술 명세 + 개발 계획)

↓

[5] GitHub Repository 생성 및 초기 커밋

↓

[6] 앱 서술 + Design.md + ToDo.md 를 Claude Code, Grok Build 에 전달하여 개발 시작

↓

[7] 모듈 단위로 구현 → 테스트 → commit/push 반복

1. Concept.md — 단순한 아이디어로 바로 시작하기 프롬프트

만들고 싶은 앱이나, 서비스를 머리속에 떠오른데로 2~3줄 이내로 간단히 서술하면서, "이러이러한걸 만들려고 하는데, 이걸 구현하기 위한 절차와 방법을 Concept.md 문서로 만들어 줘" 형태로 시작합니다.

생성된 문서를 일단 다운로드 받아서, Concept.md 문서로 잘 보관해돕니다.

2. Design.md — UI/디자인 기준 문서 먼저 만들기

UI가 있는 앱이라면 Design.md를 먼저 작성해두면 좋습니다. 즉, 참고할만한 서비스나 앱이 있거나, 이미 스스로 UI 디자인을 할 줄 아신다면, Figma 등에서 작업해둔 디자인을 이미지로 전달하여 요청할 수도 있습니다.

방법

• 마음에 드는 실제 배포된 웹사이트를 하나 정합니다. (예: linear.app, stripe.com, toss.im 등)
• Claude, Grok에게 “해당 사이트의 레이아웃 구조, 색감(컬러 팔레트), 타이포그래피, 여백/간격, 컴포넌트 스타일을 분석해서 Design.md로 정리해줘”라고 지시합니다. 좀 더 디테일하게 지시하고 싶다면, 아래처럼 나열형으로 정리해서 요구해도 좋습니다.

프롬프트 예시

https://linear.app 사이트의 디자인을 분석해서 Design.md 문서를 작성해줘. 다음 항목을 반드시 포함해: 1. 전체 레이아웃 구조 (헤더/사이드바/본문/푸터 배치) 2. 컬러 팔레트 (Primary, Secondary, Background, Text 색상을 HEX 코드로) 3. 타이포그래피 (폰트 종류, 크기 체계, 굵기) 4. 여백과 간격 규칙 (spacing scale) 5. 버튼, 카드, 입력폼 등 주요 컴포넌트의 스타일 6. 다크모드 지원 여부와 색상 매핑

팁

• 디자인 감각이 있다면, 생성된 Design.md 문서 내용은 모두 자연어로 서술되어 있기 때문에, 직접 읽고 원하는 방향으로 직접 수정/세분화 할 수 있습니다. 이 문서가 이후 모든 UI 구현의 기준이 됩니다.
• "이 사이트처럼 만들어줘" 라고만 하면 매번 결과가 달라집니다. 문서로 고정해야 일관성이 유지됩니다.

2. 기술 스택 결정 추천 트리

만들려는 서비스 형태에 따라 아래 기준으로 스택을 먼저 확정하고 시작합니다.

서버(Backend) 공통 원칙

• 어느 로컬 환경에서든 CLI에서 바로 설치하고 실행할 수 있어야 합니다.
• 언어/런타임은 Node.js 또는 Python 으로 구성합니다.
• 패키지/실행 환경은 안정적인 배포와 모든 OS 지원이 검증된 도구를 사용합니다:
• Python → uv
• Node.js → npm

데이터베이스 선택 기준

세부 구분하여 프롬프트 지시하기 ( 개발 지식이 있는 경우 )

이 프로젝트를 는 웹앱이야. Frontend는 React로 구성하고, 로컬에서 npm run dev 로 바로 테스트할 수 있어야 하고, 배포까지 안정적으로 가능한 구조로 잡아줘. Backend는 Node.js로 구성하고, DB는 관계형이 필요하니 MariaDB를 사용해. 로컬 개발환경에서 CLI로 바로 설치/실행 가능한 setup 스크립트도 포함해줘. 해당 내용과 Concept.md 문서의 내용을 확인해서, 세부 기술 구현을 위한 ToDo.md 문서를 작성해줘.

• 해당 프롬프트와 함께 Concept.md 문서를 첨부하거나, Concept.md 문서의 내용을 복사해서 뒤에 붙여넣어서 진행하세요.

하지만, 저는 위의 내용을 잘 모르는 비 개발자인걸요?

그냥 이렇게 통합으로 지시하시면 됩니다

이 프로젝트를 어떻게 실행해야 할지 잘 모르겠으니 추천해줘. 웹이 좋은지, OS에 설치하는 방식이 개발할때 확인이 편한지, 모바일 앱으로 빌드하는게 좋은지 추천해줘. 만약 웹브라우저에서 보여질 수 있다면 Frontend는 React로 구성하고, 모바일 앱으로 서비스해야 한다면, Flutter로 Frontend를 구성해줘. 만약 별도로 로컬에 설치해서 사용해야 하는 방식이면, CLI로 손쉽게 배포하고 설치해줄 수 있는 npm 이나 uv 방식으로 구성해줘. 배포까지도 안정적으로 가능한 구조로 잡아줘. Backend가 필요할지 모르겠는데, Node.js 나 배포, 설치가 안정적인 구조로 잡아주고, DB가 필요하다면, 관계형이 필요한 경우면 MariaDB를 사용하도록 해주고, 그냥 키-값 방식의 DB라면 AWS DynamoDB를 로컬에서 사용해서 개발하고, AWS에 손쉽게 배포할 수 있도록 구성해줘. 로컬 개발환경에서 CLI로 바로 설치/실행 가능한 형식이라면, setup 스크립트도 모두 포함해줘. 이런 세부 구현 기술 스택을 추천해주고, 해당 내용과 Concept.md 문서의 내용을 확인해서, 세부 기술 구현을 위한 ToDo.md 문서를 작성해줘.

• 해당 프롬프트와 함께 Concept.md 문서를 첨부하거나, Concept.md 문서의 내용을 복사해서 뒤에 붙여넣어서 진행하세요.

3. 관리자 대시보드 — 서버가 있다면 필수

서버가 존재하는 서비스인지 잘 모를 수 있습니다만, 개발자 본인이 전체 앱의 구동 상태와 진행 상황을 직접 파악하려면 보통 함께 만드는게 좋습니다.

• 서버가 있는 프로젝트는 관리자(Admin) 대시보드를 함께 구현하는 것을 기본으로 합니다.
• 대시보드에 최소한 포함할 항목:
• 서버 구동 상태 (health check)
• 주요 데이터 현황 (가입자 수, 처리 건수 등 핵심 지표)
• 최근 에러/로그 확인
• 주요 작업(배치, 큐 등)의 처리 진행 상황

프롬프트 예시

이 서비스에 서버가 포함된 서비스라면, 관리자 대시보드도 함께 개발 계획에 포함해줘. 대시보드에서 서버 상태, 핵심 지표, 최근 로그/에러를 확인할 수 있어야 해. 기본적으로 관리자 계정은 admin 에 비번 12345 로 설정해주고, 관리자 대시보드에서 비번 변경이 가능하도록 개발 내용에 포함해줘. ToDo.md 문서 확인해서, 해당 부분이 필요하다고 판단되면, 개발 계획에 포함해줘.

4. ToDo.md 마무리하기 — 모듈 단위 개발 계획서

프로그래밍의 기본은 모듈화입니다. 코드를 작성하기 전에 모듈 단위로 세분화하도록 ToDo.md에 내용을 추가하면, 이후 유지보수를 위한 좋은 아키텍쳐가 만들어질 수 있습니다.

프롬프트 예시

ToDo.md 문서를 확인해서, 아래의 가이드에 따라서 잘 작성되었는지 확인하고, 부족한 부분은 수정 보완해줘. ToDo.md 요구사항: 1. 전체 시스템을 객체지향 설계로 모듈화가 되도록 설계해줘 2. 각 모듈마다 역할, 입출력, 데이터 구조를 명확히 해서 최대한 캡슐화 되도록 명세해줘 3. 구현 순서를 체크박스 목록으로 만들어줘 (의존성이 없는 모듈부터) 4. DB 스키마 설계를 포함해줘 5. 비기술자가 테스트를 편하게 할 수 있는 시점과 방법을 함께 서술해줘

완성된 ToDo.md에 포함되었나 확인할 내용

1. 프로젝트 개요 (한 문단)
2. 확정된 기술 스택 (2번 결정 트리 결과)
3. 모듈 목록과 각 모듈의 세부 기술 명세 ( 비기술자는 이 내용은 알아보기 어려울 수 있습니다. )

• 모듈 이름과 역할
• 입력/출력 (API라면 엔드포인트와 요청/응답 형식)
• 사용하는 데이터 구조 / DB 테이블(또는 컬렉션) 설계
• 다른 모듈과의 의존 관계

1. 구현 순서 (체크박스 형태로, 의존성 순서대로)

1. 각 테스트 방법이 내가 이해할 수 있는 수준으로 작성 되어져 있는지 확인

중요

• 생성된 ToDo.md를 반드시 직접 읽고 검토하실필요는 없습니다. 완벽하게 준비하면 잘 될 것 같지만, 바이브코딩의 핵심은, 먼저 결과물을 만들어두고, 본인이 원하는 결과물을 조금씩 수정하면서 만들어가는 과정이 가장 가치있고 재미있습니다.

**

여기부터는 "환경 설치 → GitHub → Claude Code 개발 시작" 실습 파트입니다.

컴퓨터에 개발 도구를 처음 설치하는 분도 그대로 따라 할 수 있게 작성했습니다.

• 그럼에도, 너무너무 복잡할꺼 같고 왜 이걸 써야 하는지 모르겠고 귀찮아 죽겠다면, 일단 아래 링크에서 무료 강의를 좀 듣고 오세요.

https://nomadcoders.co/git-for-beginners

5. 개발 환경 준비 (딱 2가지만 설치합니다)

우리가 설치할 것은 2가지입니다.

그리고 GitHub 계정이 필요합니다. https://github.com 에서 무료 가입하세요. (이메일 인증까지 완료) Claude Code나 Grok Build 사용에는 Claude 유료 플랜(Pro/Max/Team) 또는 Grok 유료 계정이 필요합니다.

5-1. 🪟 Windows 사용자 설치 순서

① Git 설치

1. 브라우저에서 https://git-scm.com/download/win 접속 → 자동으로 다운로드 시작
2. 다운로드된 설치 파일 실행
3. 설치 옵션이 아주 많이 나오는데, 전부 기본값 그대로 "Next"만 계속 클릭하면 됩니다.

• 단, "Choosing the default editor" 화면이 나오면 "Use Visual Studio Code as Git's default editor" 를 선택하면 좋습니다. (VS Code를 아직 설치 안 했다면 그냥 기본값도 무방)

1. 설치 확인: 시작 메뉴에서 PowerShell 을 실행하고 아래를 입력

git --version

→ git version 2.xx.x 처럼 버전이 나오면 성공. 안 나오면 PowerShell을 껐다가 다시 켜보세요.

② VS Code 설치

1. https://code.visualstudio.com 접속 → Download for Windows 클릭
2. 설치 파일 실행 → 계속 "다음" 클릭. 단, 옵션 화면에서 아래 두 개는 체크 권장:

• "PATH에 추가" (Add to PATH)
• "Code(으)로 열기 작업을 파일/디렉터리 상황에 맞는 메뉴에 추가"

1. 설치 후 VS Code 실행. 왼쪽 아래 톱니바퀴 없이도 첫 화면에서 한국어 언어팩 설치 알림이 뜨면 설치해도 좋습니다.

5-2. 🍎 Mac 사용자 설치 순서

① Git 설치

1. 터미널을 엽니다: Cmd + Space → "터미널" 입력 → Enter
2. 아래 입력:

git --version

1. 버전이 바로 나오면 이미 설치된 것 → ②로 이동. 설치 안내 팝업("명령어 라인 개발자 도구...")이 뜨면 "설치" 를 클릭하고 기다립니다. (이게 Git 설치입니다)

1. 완료 후 다시 git --version 으로 확인.

② VS Code 설치

1. https://code.visualstudio.com 접속 → Download for macOS 클릭
2. 다운로드된 zip을 풀면 나오는 Visual Studio Code.app 을 응용 프로그램(Applications) 폴더로 드래그해서 옮깁니다. (중요! 다운로드 폴더에서 바로 쓰면 안 됩니다)
3. 응용 프로그램에서 VS Code 실행.

5-3. (공통) Git에 내 이름 등록하기 — 최초 1회

커밋(저장 기록)에 "누가 작업했는지" 남기기 위한 설정입니다. PowerShell(Windows) 또는 터미널(Mac)에서:

git config --global

user.name "홍길동" git config --global

user.email "본인의깃헙가입이메일

@company .com"

이메일은 GitHub 가입에 쓴 이메일과 동일하게 입력하세요.

6. GitHub 리포지토리 만들고 VS Code로 내 PC에 연결하기

"리포지토리(Repository)"는 프로젝트 하나를 담는 클라우드 폴더라고 생각하면 됩니다. 흐름은 이렇습니다: GitHub 웹사이트에서 빈 리포지토리를 만들고 → VS Code로 내 PC에 복제(clone)해서 → 기획 문서를 올려두고 → 그 리포지토리를 Claude Code 웹에 연결합니다.

6-1. GitHub 웹사이트에서 리포지토리 만들기

1. https://github.com 로그인
2. 오른쪽 위 + 버튼 → New repository 클릭
3. 다음과 같이 입력:

• Repository name: 프로젝트 이름 (영문, 띄어쓰기 대신 하이픈. 예: my-first-app)
• Private 선택 (회사 프로젝트는 반드시 Private!)
• "Add a README file" 체크박스를 ✅ 체크 ← 초보자는 꼭 체크하세요. 이래야 다음 단계(clone)가 간단해집니다. (Claude Code 웹은 기존 리포지토리에 연결해서 작업하므로, 이렇게 미리 만들어두는 것이 시작점입니다)

4. Create repository 클릭

1. 만들어진 리포지토리 페이지에서 초록색 <> Code 버튼 클릭 → HTTPS 탭의 주소(https://github.com/계정명/my-first-app.git)를 복사 해둡니다.

6-2. VS Code로 내 PC에 복제(clone)하기

1. VS Code 실행
2. Ctrl + Shift + P (Mac은 Cmd + Shift + P) → 명령 입력창이 열림
3. clone 이라고 입력 → "Git: Clone" (Git: 복제) 선택
4. 아까 복사한 리포지토리 주소를 붙여넣고 Enter
5. "Clone from GitHub" 를 선택해도 됩니다 → 브라우저가 열리며 GitHub 로그인/승인 을 요구하면 승인하세요. (최초 1회만)
6. 프로젝트를 저장할 위치를 선택 (예: 문서/Projects 폴더를 하나 만들어두면 좋습니다)
7. 복제가 끝나면 오른쪽 아래에 "열기(Open)" 알림이 뜹니다 → 클릭
8. 왼쪽 파일 탐색기에 README.md 가 보이면 성공! 🎉 이제 이 폴더가 내 PC와 GitHub이 연결된 작업 폴더입니다.

6-3. 기획 문서 올리기 — Concept.md, Design.md, ToDo.md

Claude Code 웹은 리포지토리 안에 있는 파일을 읽을 수 있습니다. 그래서 기획 문서를 리포지토리에 올려두는 것이 곧 "문서 업로드"입니다.

1. VS Code 왼쪽 파일 탐색기의 빈 곳에서 우클릭 → 새 파일(New File) → 이름을 Concept.md 로 입력
2. 미리 작성해둔 앱 설명 내용을 붙여넣고 저장 (Ctrl+S / Cmd+S)
3. 같은 방법으로 Design.md (UI가 있는 경우) , ToDo.md 파일도 만들어 넣습니다
4. 이제 GitHub에 올립니다(commit & push) — 아래 6-4 방법으로.

6-4. VS Code에서 저장(commit)하고 올리기(push) — 마우스로만

1. 파일을 저장하면, VS Code 왼쪽의 가지 모양 아이콘(Source Control, 소스 제어) 에 숫자 배지가 붙습니다.
2. 그 아이콘을 클릭 → 변경된 파일 목록이 보입니다.
3. 위쪽 메시지 입력칸에 무엇을 했는지 한 줄로 적습니다. (예: 기획 문서 추가)
4. ✔ Commit (커밋) 버튼 클릭 → 내 PC에 세이브 완료

• "스테이징된 변경 내용이 없습니다" 팝업이 뜨면 "예(Yes)" 를 눌러 전체를 커밋하면 됩니다.

1. 이어서 Sync Changes (변경 내용 동기화) 버튼 클릭 → GitHub에 업로드(push) 완료

1. GitHub 웹사이트에서 리포지토리를 새로고침해보면 방금 올린 Concept.md 가 보입니다. 이제 Claude Code 웹도 이 문서를 읽을 수 있습니다.

pull(내려받기) 도 같은 화면에서 됩니다: Claude가 클라우드에서 올린 변경사항이 있으면 Sync Changes 버튼이 내려받기+올리기를 함께 해줍니다.

6-5. (참고) 터미널 명령어로 하면 - CLI 에 익숙해져보고 싶다면.

익숙해지면 명령어가 더 빠릅니다. VS Code 상단 메뉴 터미널(Terminal) → 새 터미널(New Terminal) 을 열고:

git add . # 변경된 파일 전부 담기 git commit -m "무엇을 했는지" # 내 PC에 세이브 git push # GitHub에 올리기 git pull # GitHub에서 내려받기

7. Claude Code 웹에 리포지토리 연결하고 개발 시작하기

이제 브라우저에서 Claude Code 웹을 열고, 방금 만든 GitHub 리포지토리를 연결합니다.

7-1. Claude Code 웹 ↔ GitHub 리포지토리 연결 (최초 1회)

1. 브라우저에서 https://claude.ai/code 접속 → Claude 계정으로 로그인
2. 처음 접속하면 GitHub 연결(Connect GitHub) 안내가 나옵니다 → 안내를 따라 진행
3. GitHub 페이지로 이동하며 Claude GitHub App 설치 화면이 나옵니다:

• 내 GitHub 계정(또는 조직)을 선택
• 접근 허용 범위 선택: "Only select repositories" 를 선택하고, 6-1에서 만든 리포지토리(예: my-first-app)를 지정하는 것을 권장합니다. (나중에 GitHub 설정에서 리포지토리를 추가할 수 있습니다)
• Install / Authorize 클릭

1. Claude로 돌아오면 연결 완료. 환경(Environment) 설정 화면이 나오면 기본값(Default) 그대로 두면 됩니다.

1. 새 세션(작업)을 시작할 때 리포지토리 선택 목록에서 내 리포지토리를 선택하고, 프롬프트를 입력하면 작업이 시작됩니다.

🏢 회사 조직(Organization) 리포지토리인 경우: GitHub App 설치에 조직 관리자의 승인이 필요할 수 있습니다. 설치 화면에서 요청(Request)을 보내면 관리자에게 알림이 가고, 승인 후 연결할 수 있습니다.

7-2. Claude Code, Grok Build 웹의 동작 방식 이해하기 (중요!)

Claude Code, Grok Build 웹은 내 PC가 아니라 클라우드의 가상 컴퓨터에서 작업합니다. 흐름은 이렇습니다:

① 내가 프롬프트 입력

↓

② Claude Code, Grok Build가 클라우드에 내 리포지토리를 복제해서 코드 작성

↓

③ 결과물을 "새 작업 브랜치"로 GitHub에 push

↓

④ 나는 그 브랜치를 내 PC로 받아서 테스트하거나, GitHub에서 Pull Request로 변경 내용을 확인

↓

⑤ 마음에 들면 main으로 병합(merge)

• main 브랜치를 직접 건드리지 않고 항상 새 브랜치로 결과를 올려주기 때문에, 뭘 시켜도 기존 코드가 망가질 걱정이 없습니다. ( Grok Build 는 main 브랜치에 작업하지만 되돌릴 수 있으니 실수 걱정마세요 )
• 세션은 이어지므로, PC에서 시작한 작업을 나중에 휴대폰의 Claude Code, Grok Build앱에서 확인할 수도 있습니다.

7-4. 개발 시작 프롬프트

문서 3종(Concept.md / Design.md / ToDo.md)이 main에 준비되었으면, 새 세션에서 드디어 개발을 시작합니다.

이 프로젝트를 개발해줘. 리포지토리에 있는 다음 문서를 기준으로 진행해: - Concept.md : 만들려는 앱에 대한 설명 - ToDo.md : 모듈 단위 개발 계획 (이 순서대로 구현해) - Design.md : 디자인 기준 (모든 UI는 이 문서를 따라)

작업 규칙: 1. ToDo.md의 구현 순서대로 한 번에 한 모듈씩 진행해 2. 테스트가 가능한 단위가 완성되면, 내 로컬 PC에서 실행/테스트하는 방법을 README 또는 답변으로 알려줘. 비개발자니까 초보자에게 알려주듯이 잘 알려줘 3. 완료된 항목은 ToDo.md에 체크 표시해 4. 작업 브랜치 이름을 나에게 알려주고, 기억하기 편한 커밋 메시지로 push 해 5. 불명확한 부분이 있으면 추측하지 말고 나에게 질문해

7-5. 개발 중 반복하는 사이클

① 웹 Claude Code가 작업 브랜치에서 모듈 하나 구현 → push

↓

② 그 작업 브랜치를 내 PC(VS Code)로 받아서 직접 실행/테스트

(브랜치 받는 방법은 8-3 참고)

↓

③ 문제가 있으면 → 에러 메시지를 통째로 복사해서 웹 세션에 붙여넣기

문제가 없으면 → "좋아, 다음 개발 계속 진행해"

↓

①로 돌아가서 다음 모듈

↓

④ 전체 기능이 완성되고 테스트를 통과했으면

→ Pull Request로 main 브랜치에 병합 (8-4 참고)

→ 배포는 항상 main 기준 (8-5 참고)

8. 브랜치(Branch) — 작업 브랜치에서 테스트하고, main으로 병합해서 배포하기

8-1. 브랜치가 뭔가요?

• main 브랜치 = 항상 잘 동작하는 완성본 진열대입니다. 배포는 언제나 main 기준으로 합니다.
• 작업 브랜치 (예: claude/feature-login) = main을 복사해서 만든 공사장입니다. 여기서 마음껏 만들고 부숴도 main은 안전합니다.

Claude Code 웹은 항상 새 작업 브랜치를 만들어 결과를 push합니다. 그래서 여러분이 알아야 할 것은 딱 세 가지입니다:

1. 지금 내 폴더가 어떤 브랜치인지 확인하는 법
2. Claude가 push한 작업 브랜치를 내 PC로 받아서 테스트하는 법
3. 완성되면 main으로 병합(merge)해서 배포하는 법

8-2. 지금 어떤 브랜치인지 확인하기

• VS Code 화면 왼쪽 맨 아래 상태바를 보세요. 가지 아이콘 옆에 브랜치 이름이 표시됩니다. (예: main 또는 claude/feature-login)
• 터미널로 확인하려면:

git branch

→ 목록에서 * 가 붙은 것이 현재 브랜치입니다.

⚠️ 중요한 개념: 브랜치를 바꾸면 폴더 안의 파일 내용이 통째로 그 브랜치의 상태로 바뀝니다. 파일이 사라진 것처럼 보여도 놀라지 마세요 — 다른 브랜치에 그대로 있습니다.

8-3. Claude Code, Grok Build가 만든 작업 브랜치를 내 PC로 받아서 테스트하기

웹 Claude Code가 "OO 브랜치에 push했어요" 라고 하면, 그 브랜치를 내 PC로 가져와서 테스트합니다. Grok Build 는 웹 화면에 우측 상단에 'Github Push 하기' 버튼이 있으니, 이걸 눌러서 push 해주세요.

VS Code로 (마우스만):

1. 왼쪽 맨 아래 브랜치 이름 클릭 → 브랜치 목록이 열립니다
2. 목록에 새 브랜치가 안 보이면, 소스 제어 탭의 ... 메뉴 → Fetch(가져오기) 를 한 번 실행 후 다시 시도
3. 목록에서 origin/claude/... 로 시작하는 Claude의 작업 브랜치를 선택 → 내 폴더가 그 브랜치 상태로 바뀝니다

터미널로:

git fetch # GitHub의 최신 브랜치 목록 가져오기

git checkout claude/feature-login # Claude가 알려준 브랜치 이름으로 전환

git pull # (이미 그 브랜치에 있었다면) 최신 내용 받기

그 상태에서 Claude가 알려준 방법대로 실행/테스트하면 됩니다. 에러가 나면 에러 메시지를 통째로 복사해서 웹 세션에 붙여넣으세요. Claude가 수정해서 같은 브랜치에 다시 push해주면, git pull (또는 Sync Changes)로 받아서 재테스트합니다.

8-4. 완성되면 main으로 병합(merge)하기 — Pull Request

작업 브랜치에서 기능이 완성되고 테스트를 통과했다면, GitHub 웹사이트에서 Pull Request(PR)로 main에 병합합니다. Claude Code 웹이 PR을 이미 만들어둔 경우가 많아서 버튼 클릭이면 끝납니다.

1. GitHub에서 내 리포지토리 접속 → Pull requests 탭 클릭

• Claude가 만든 PR이 있으면 클릭. 없으면 New pull request → base: main, compare: 작업 브랜치 선택 후 Create pull request

1. Files changed 탭에서 무엇이 바뀌는지 한번 훑어봅니다 (초록색: 추가, 빨간색: 삭제)
2. Merge pull request → Confirm merge 클릭 → main에 반영 완료!
3. 내 PC의 main도 최신으로 맞춥니다:

• VS Code 왼쪽 아래 브랜치 클릭 → main 선택 → 소스 제어 탭에서 Sync Changes
• (터미널: git checkout main → git pull)

1. 병합이 끝난 작업 브랜치는 PR 화면의 Delete branch 버튼으로 정리해도 됩니다.

병합 과정에서 충돌(conflict) 이 났다는 메시지가 뜨면, 직접 해결하려 하지 말고 웹 세션에서 Claude에게 알리세요:

main으로 병합하려는데 충돌이 났어. 충돌을 해결해서 다시 push해줘.

어떻게 해결했는지도 설명해줘.

8-5. 배포는 항상 main에서

• 배포(운영 서버에 올리기, 앱 빌드 등)는 반드시 main 브랜치 기준으로 합니다.
• 작업 브랜치를 배포하면 안 됩니다 — 아직 검증이 끝나지 않은 공사장이기 때문입니다.
• 순서를 기억하세요: 작업 브랜치에서 개발 → 내 PC에서 테스트 → PR로 main에 병합 → main에서 배포

💡 이 구조 덕분에 main은 언제나 "배포 가능한 상태"로 유지됩니다. 뭔가 크게 망가져도 main으로 돌아가면 항상 동작하는 버전이 있습니다.

9. 프롬프트 작성 요령 (공통)

바이브 코딩의 품질은 프롬프트 품질에 비례합니다.

1. 하지 말아야 할 것도 명시하라 — "내가 승인하기 전까지 함부로 코드 수정하지 마", "라이브러리 추가하지 말고 기존 스택으로만"
2. 한 번에 하나의 모듈 — 전체 앱을 한 프롬프트로 시키면 품질이 떨어집니다. ToDo.md 순서대로 잘게 시키세요.
3. 에러는 그대로 붙여넣어라 — 에러 메시지를 요약하지 말고 터미널 출력을 통째로 복사해서 전달하세요.
4. 애매하면 Claude가 물어보게 하라 — "불명확한 부분이 있으면 추측하지 말고 나에게 질문해" 를 프롬프트에 넣으세요.
5. 문서를 기준으로 대화하라 — "아까 말한 것처럼" ❌ → "Design.md 디자인 대로" ✅. 대화 기억보다 리포지토리에 있는 문서가 훨씬 안정적입니다.

끄읕.

옛 선인인 모피어스께서 말씀하셨습니다.

“네오. 내가 널 데려오는건 문지방 앞 까지다. 적어도 문 정도는 니 손목으로 여세요”