챕터 09 · L2
Git 연동 워크플로우
Claude Code와 Git을 함께 사용하는 실전 워크플로우
Claude Code와 함께 브랜치·커밋·PR 설명을 한 흐름으로 진행할 수 있어요.
참고 문서
공개 문서
09. Git 연동 워크플로우
아래는 content/courses/09-git-workflow.mdx 와 동일한 원문입니다. Markdown과 HTML 변환 결과를 각각 복사할 수 있습니다.
공개 문서 원문 (Markdown)
# Git 연동 워크플로우
> **이 챕터를 마치면** Claude Code와 함께 브랜치·커밋·PR 설명을 한 흐름으로 진행할 수 있어요.
Claude Code는 Git을 자연스럽게 이해해요.
"이 기능 브랜치 만들고 구현 후 커밋해줘"처럼 말하면 **Git 명령을 직접 실행**해 줘요.
---
## 기본 패턴: 브랜치 → 구현 → 커밋
```bash
# Claude Code에게 전체 흐름을 한 번에 요청
claude "feat/user-profile 브랜치 만들고,
사용자 프로필 페이지(app/profile/page.tsx)를 구현한 뒤
'feat: 사용자 프로필 페이지 추가' 메시지로 커밋해줘"
```
Claude Code가 실제로 실행하는 순서:
```
✻ Bash: git checkout -b feat/user-profile
✻ Read: app/layout.tsx
✻ Write: app/profile/page.tsx
✻ Edit: app/layout.tsx
✻ Bash: git add app/profile/page.tsx app/layout.tsx
✻ Bash: git commit -m "feat: 사용자 프로필 페이지 추가"
✻ 완료: 브랜치 생성, 구현, 커밋까지 완료
```
---
## 실전 시나리오 3가지
### 시나리오 1: 새 기능 개발
```bash
# 1. 기능 브랜치에서 시작
git checkout -b feat/search
# 2. Claude Code로 구현
claude "검색 기능을 추가해줘.
- 검색 인풋: components/SearchBar.tsx
- 검색 결과: app/search/page.tsx
- 검색 로직: lib/search.ts"
# 3. 결과 확인 후 커밋
git diff # 변경사항 검토
git add -A
git commit -m "feat: 검색 기능 추가"
```
### 시나리오 2: 버그 수정
```bash
# 1. 에러 로그를 그대로 전달
claude "아래 에러가 발생해. 원인 찾아서 고쳐줘:
TypeError: Cannot read properties of undefined (reading 'map')
at CourseList (components/CourseList.tsx:23)
at renderWithHooks
에러 발생 조건: 강의가 0개일 때"
# 2. 수정 확인 후 커밋
git diff
git commit -am "fix: 강의 0개일 때 CourseList 에러 수정"
```
### 시나리오 3: 리팩토링
```bash
# 1. 리팩토링 요청
claude "components/ 폴더를 분석해서 중복 코드를 공통 컴포넌트로 통합해줘.
변경 전/후를 설명해주고, 기존 동작이 유지되는지 확인해줘."
# 2. Claude Code가 제안한 변경사항 검토
git diff --stat # 변경된 파일 목록
git diff components/ # 컴포넌트 변경 상세
# 3. 승인 후 커밋
git commit -am "refactor: 공통 UI 컴포넌트로 중복 제거"
```
---
## 안전하게 작업하는 습관
### 작업 전 스냅샷 만들기
```bash
# 방법 1: 커밋으로 저장 (권장)
git add -A
git commit -m "chore: Claude Code 작업 전 스냅샷"
# 방법 2: stash 활용
git stash push -m "작업 전 임시 저장"
claude "..." # 작업 실행
git stash pop # 문제 있으면 복구
```
### 변경사항 검토 루틴
```bash
# Claude Code 작업 완료 후 반드시
git diff --stat # 어떤 파일이 바뀌었나
git diff # 실제 내용 확인
pnpm build # 빌드 오류 없는지
pnpm dev # 브라우저에서 동작 확인
git commit -am "..." # 이상 없으면 커밋
```
---
## Claude Code에게 Git 작업 직접 시키기
### PR 준비
```bash
claude "현재 브랜치(feat/search)의 변경사항을 요약해서
PR 설명으로 쓸 마크다운을 작성해줘.
변경 이유, 주요 파일, 테스트 방법을 포함해서."
```
### 커밋 메시지 작성
```bash
# git diff 내용을 파이프로 전달
git diff | claude "이 변경사항에 맞는 커밋 메시지를 Conventional Commits 형식으로 작성해줘"
```
### 충돌 해결
```bash
git merge main # 충돌 발생
claude "Git 충돌이 발생했어. 아래 파일들을 분석해서 올바르게 병합해줘:
components/Header.tsx
현재 브랜치: 로그인 버튼 추가
main 브랜치: 다크모드 토글 추가
두 기능 모두 유지되어야 해."
```
---
## 팀 작업 워크플로우
혼자 개발할 때도 팀처럼 브랜치를 관리하면 실수를 줄일 수 있습니다.
```
main ← 항상 동작하는 버전
│
├─ feat/auth ← Claude Code로 인증 구현 중
├─ feat/dashboard ← 대시보드 작업
└─ fix/typo ← 오타 수정
```
**브랜치 전략:**
```bash
# 기능 시작
git checkout -b feat/{기능명}
claude "..."
# 완료 후 main에 병합
git checkout main
git merge feat/{기능명}
git branch -d feat/{기능명} # 완료된 브랜치 삭제
```
---
## .gitignore 관리
```bash
# Claude Code에게 .gitignore 생성 요청
claude "Next.js 15 + Supabase + Vercel 프로젝트의 .gitignore를 만들어줘.
node_modules, .env, .next, .vercel 등 필수 항목 포함해서."
```
**절대 커밋하면 안 되는 파일:**
```
.env ← API 키, DB 비밀번호
.env.local ← 로컬 환경변수
.env.production ← 프로덕션 시크릿
```
```bash
# .env 실수로 추가했을 때 제거
git rm --cached .env
echo ".env" >> .gitignore
git commit -m "fix: .env 파일 추적 제거"
```
---
## 요약: Claude Code + Git 황금 규칙
1. **작업 전 항상 커밋 또는 stash** — 되돌릴 방법을 만들어두기
2. **기능별 브랜치 사용** — main은 항상 동작하는 상태 유지
3. **변경사항은 반드시 검토** — `git diff`로 확인 후 커밋
4. **.env는 절대 커밋 금지** — `.gitignore`에서 확인
5. **작은 단위로 자주 커밋** — 한 번에 너무 많은 변경 피하기
---
## 8장 보강 프로세스 적용: Git 운영 체크포인트
6~7장에서 쓴 기본샘플프로세스를 09챕터에 동일 적용합니다.
핵심은 "Git 명령을 아는 것"보다 **복구 가능한 흐름**을 습관화하는 것입니다.
### 유튜브 대본 기반 실전 패턴
성과가 좋은 입문 워크플로우는 아래 4단계를 반복합니다.
1. 브랜치 생성
2. 기능 구현
3. diff 검토 + 실행 확인
4. 의미 단위 커밋
이 사이클이 짧을수록 충돌·회귀·누락이 줄어듭니다.
### Git 실패 패턴 TOP 5 (09챕터)
1. **main에서 직접 작업**
- 대응: 기능 시작 시 무조건 `feat/*`, `fix/*` 브랜치 생성
2. **커밋 전에 동작 확인 생략**
- 대응: 최소 개발 서버 확인 후 커밋
3. **커밋 메시지가 모호함**
- 대응: "왜 바꿨는지"가 보이도록 작성
4. **시크릿 파일 추적**
- 대응: `.env*` 추적 여부를 작업마다 점검
5. **대규모 한 번 커밋**
- 대응: 기능/버그/리팩토링을 분리 커밋
### 09챕터 실행형 체크리스트 (DoD)
- [ ] 브랜치에서 작업 시작 완료
- [ ] `git diff --stat` + `git diff` 검토 완료
- [ ] 실행 확인 후 커밋 완료
- [ ] 커밋 메시지에 변경 이유 포함 완료
- [ ] 시크릿 파일 미추적 확인 완료
### 9장(중급 워크플로우 II)로 넘길 입력값
- 반복 가능한 브랜치 네이밍 규칙
- 커밋 메시지 템플릿(기능/수정/리팩토링)
- PR 요약 포맷(변경 이유/테스트/리스크)공개 문서 변환 코드 (HTML)
<h1>Git 연동 워크플로우</h1>
<blockquote>
<p><strong>이 챕터를 마치면</strong> Claude Code와 함께 브랜치·커밋·PR 설명을 한 흐름으로 진행할 수 있어요.</p>
</blockquote>
<p>Claude Code는 Git을 자연스럽게 이해해요.
"이 기능 브랜치 만들고 구현 후 커밋해줘"처럼 말하면 <strong>Git 명령을 직접 실행</strong>해 줘요.</p>
<hr>
<h2>기본 패턴: 브랜치 → 구현 → 커밋</h2>
<pre><code class="language-bash"># Claude Code에게 전체 흐름을 한 번에 요청
claude "feat/user-profile 브랜치 만들고,
사용자 프로필 페이지(app/profile/page.tsx)를 구현한 뒤
'feat: 사용자 프로필 페이지 추가' 메시지로 커밋해줘"
</code></pre>
<p>Claude Code가 실제로 실행하는 순서:</p>
<pre><code>✻ Bash: git checkout -b feat/user-profile
✻ Read: app/layout.tsx
✻ Write: app/profile/page.tsx
✻ Edit: app/layout.tsx
✻ Bash: git add app/profile/page.tsx app/layout.tsx
✻ Bash: git commit -m "feat: 사용자 프로필 페이지 추가"
✻ 완료: 브랜치 생성, 구현, 커밋까지 완료
</code></pre>
<hr>
<h2>실전 시나리오 3가지</h2>
<h3>시나리오 1: 새 기능 개발</h3>
<pre><code class="language-bash"># 1. 기능 브랜치에서 시작
git checkout -b feat/search
# 2. Claude Code로 구현
claude "검색 기능을 추가해줘.
- 검색 인풋: components/SearchBar.tsx
- 검색 결과: app/search/page.tsx
- 검색 로직: lib/search.ts"
# 3. 결과 확인 후 커밋
git diff # 변경사항 검토
git add -A
git commit -m "feat: 검색 기능 추가"
</code></pre>
<h3>시나리오 2: 버그 수정</h3>
<pre><code class="language-bash"># 1. 에러 로그를 그대로 전달
claude "아래 에러가 발생해. 원인 찾아서 고쳐줘:
TypeError: Cannot read properties of undefined (reading 'map')
at CourseList (components/CourseList.tsx:23)
at renderWithHooks
에러 발생 조건: 강의가 0개일 때"
# 2. 수정 확인 후 커밋
git diff
git commit -am "fix: 강의 0개일 때 CourseList 에러 수정"
</code></pre>
<h3>시나리오 3: 리팩토링</h3>
<pre><code class="language-bash"># 1. 리팩토링 요청
claude "components/ 폴더를 분석해서 중복 코드를 공통 컴포넌트로 통합해줘.
변경 전/후를 설명해주고, 기존 동작이 유지되는지 확인해줘."
# 2. Claude Code가 제안한 변경사항 검토
git diff --stat # 변경된 파일 목록
git diff components/ # 컴포넌트 변경 상세
# 3. 승인 후 커밋
git commit -am "refactor: 공통 UI 컴포넌트로 중복 제거"
</code></pre>
<hr>
<h2>안전하게 작업하는 습관</h2>
<h3>작업 전 스냅샷 만들기</h3>
<pre><code class="language-bash"># 방법 1: 커밋으로 저장 (권장)
git add -A
git commit -m "chore: Claude Code 작업 전 스냅샷"
# 방법 2: stash 활용
git stash push -m "작업 전 임시 저장"
claude "..." # 작업 실행
git stash pop # 문제 있으면 복구
</code></pre>
<h3>변경사항 검토 루틴</h3>
<pre><code class="language-bash"># Claude Code 작업 완료 후 반드시
git diff --stat # 어떤 파일이 바뀌었나
git diff # 실제 내용 확인
pnpm build # 빌드 오류 없는지
pnpm dev # 브라우저에서 동작 확인
git commit -am "..." # 이상 없으면 커밋
</code></pre>
<hr>
<h2>Claude Code에게 Git 작업 직접 시키기</h2>
<h3>PR 준비</h3>
<pre><code class="language-bash">claude "현재 브랜치(feat/search)의 변경사항을 요약해서
PR 설명으로 쓸 마크다운을 작성해줘.
변경 이유, 주요 파일, 테스트 방법을 포함해서."
</code></pre>
<h3>커밋 메시지 작성</h3>
<pre><code class="language-bash"># git diff 내용을 파이프로 전달
git diff | claude "이 변경사항에 맞는 커밋 메시지를 Conventional Commits 형식으로 작성해줘"
</code></pre>
<h3>충돌 해결</h3>
<pre><code class="language-bash">git merge main # 충돌 발생
claude "Git 충돌이 발생했어. 아래 파일들을 분석해서 올바르게 병합해줘:
components/Header.tsx
현재 브랜치: 로그인 버튼 추가
main 브랜치: 다크모드 토글 추가
두 기능 모두 유지되어야 해."
</code></pre>
<hr>
<h2>팀 작업 워크플로우</h2>
<p>혼자 개발할 때도 팀처럼 브랜치를 관리하면 실수를 줄일 수 있습니다.</p>
<pre><code>main ← 항상 동작하는 버전
│
├─ feat/auth ← Claude Code로 인증 구현 중
├─ feat/dashboard ← 대시보드 작업
└─ fix/typo ← 오타 수정
</code></pre>
<p><strong>브랜치 전략:</strong></p>
<pre><code class="language-bash"># 기능 시작
git checkout -b feat/{기능명}
claude "..."
# 완료 후 main에 병합
git checkout main
git merge feat/{기능명}
git branch -d feat/{기능명} # 완료된 브랜치 삭제
</code></pre>
<hr>
<h2>.gitignore 관리</h2>
<pre><code class="language-bash"># Claude Code에게 .gitignore 생성 요청
claude "Next.js 15 + Supabase + Vercel 프로젝트의 .gitignore를 만들어줘.
node_modules, .env, .next, .vercel 등 필수 항목 포함해서."
</code></pre>
<p><strong>절대 커밋하면 안 되는 파일:</strong></p>
<pre><code>.env ← API 키, DB 비밀번호
.env.local ← 로컬 환경변수
.env.production ← 프로덕션 시크릿
</code></pre>
<pre><code class="language-bash"># .env 실수로 추가했을 때 제거
git rm --cached .env
echo ".env" >> .gitignore
git commit -m "fix: .env 파일 추적 제거"
</code></pre>
<hr>
<h2>요약: Claude Code + Git 황금 규칙</h2>
<ol>
<li><strong>작업 전 항상 커밋 또는 stash</strong> — 되돌릴 방법을 만들어두기</li>
<li><strong>기능별 브랜치 사용</strong> — main은 항상 동작하는 상태 유지</li>
<li><strong>변경사항은 반드시 검토</strong> — <code>git diff</code>로 확인 후 커밋</li>
<li><strong>.env는 절대 커밋 금지</strong> — <code>.gitignore</code>에서 확인</li>
<li><strong>작은 단위로 자주 커밋</strong> — 한 번에 너무 많은 변경 피하기</li>
</ol>
<hr>
<h2>8장 보강 프로세스 적용: Git 운영 체크포인트</h2>
<p>6~7장에서 쓴 기본샘플프로세스를 09챕터에 동일 적용합니다.
핵심은 "Git 명령을 아는 것"보다 <strong>복구 가능한 흐름</strong>을 습관화하는 것입니다.</p>
<h3>유튜브 대본 기반 실전 패턴</h3>
<p>성과가 좋은 입문 워크플로우는 아래 4단계를 반복합니다.</p>
<ol>
<li>브랜치 생성</li>
<li>기능 구현</li>
<li>diff 검토 + 실행 확인</li>
<li>의미 단위 커밋</li>
</ol>
<p>이 사이클이 짧을수록 충돌·회귀·누락이 줄어듭니다.</p>
<h3>Git 실패 패턴 TOP 5 (09챕터)</h3>
<ol>
<li><p><strong>main에서 직접 작업</strong></p>
<ul>
<li>대응: 기능 시작 시 무조건 <code>feat/*</code>, <code>fix/*</code> 브랜치 생성</li>
</ul>
</li>
<li><p><strong>커밋 전에 동작 확인 생략</strong></p>
<ul>
<li>대응: 최소 개발 서버 확인 후 커밋</li>
</ul>
</li>
<li><p><strong>커밋 메시지가 모호함</strong></p>
<ul>
<li>대응: "왜 바꿨는지"가 보이도록 작성</li>
</ul>
</li>
<li><p><strong>시크릿 파일 추적</strong></p>
<ul>
<li>대응: <code>.env*</code> 추적 여부를 작업마다 점검</li>
</ul>
</li>
<li><p><strong>대규모 한 번 커밋</strong></p>
<ul>
<li>대응: 기능/버그/리팩토링을 분리 커밋</li>
</ul>
</li>
</ol>
<h3>09챕터 실행형 체크리스트 (DoD)</h3>
<ul>
<li><input disabled="" type="checkbox"> 브랜치에서 작업 시작 완료</li>
<li><input disabled="" type="checkbox"> <code>git diff --stat</code> + <code>git diff</code> 검토 완료</li>
<li><input disabled="" type="checkbox"> 실행 확인 후 커밋 완료</li>
<li><input disabled="" type="checkbox"> 커밋 메시지에 변경 이유 포함 완료</li>
<li><input disabled="" type="checkbox"> 시크릿 파일 미추적 확인 완료</li>
</ul>
<h3>9장(중급 워크플로우 II)로 넘길 입력값</h3>
<ul>
<li>반복 가능한 브랜치 네이밍 규칙</li>
<li>커밋 메시지 템플릿(기능/수정/리팩토링)</li>
<li>PR 요약 포맷(변경 이유/테스트/리스크)</li>
</ul>