Git 완전정복

AI 개발자에게 Git은 선택이 아니라 필수입니다

Git은 소스 코드의 변경 이력을 추적하고 관리하는 분산 버전 관리 시스템(DVCS)입니다. 모델 코드, 프롬프트, 파이프라인 구성이 계속 변하는 AI 프로젝트에서 버전 관리 없이는 팀 협업이 불가능합니다.

1-1. 버전 관리가 해결하는 것

1-2. Git ≠ GitHub

Git은 내 컴퓨터에서 실행되므로 인터넷이 없어도 파일을 기록할 수 있습니다. GitHub는 팀과 공유할 때 사용합니다. clone으로 내려받고, push로 올리고, pull·fetch로 새 내용을 받아옵니다.

1-3. 커밋은 "사진 한 장" — Git은 사진첩입니다

커밋(commit)은 Git에서 가장 중요한 단어입니다. 커밋 하나는 그 순간 프로젝트 폴더 전체를 찍은 사진 한 장입니다. 바뀐 부분만 오려 붙인 메모가 아니라, 폴더 전체의 모습이 통째로 남습니다.

이 사진첩 덕분에 두 가지가 가능해집니다. 하나, 언제든 이전 사진으로 통째로 되돌아갈 수 있습니다 — 파일을 일일이 고치는 게 아니라 사진 한 장을 다시 펼치는 일입니다. 둘, 사진마다 찍은 사람·시각·메모가 함께 남습니다 — 그래서 커밋할 때 메시지를 쓰고, git log로 "누가 언제 왜"를 추적할 수 있습니다.

1-4. 4개의 공간 — 사진 한 장이 팀에 닿기까지 거치는 네 자리

Git에서는 같은 파일의 여러 버전이 각 공간에 따로 기록됩니다. 명령어는 한 공간의 내용을 다른 공간에 기록하는 방법입니다.

핵심은 세 단계입니다. git add는 이번 변경을 고르고, git commit은 그 상태를 내 컴퓨터에 기록하고, git push는 기록을 GitHub에 올립니다. 반대로 git clone과 git pull은 GitHub의 내용을 내 컴퓨터로 가져옵니다. 에러가 나면 먼저 "내 변경은 지금 어느 단계에 있지?"라고 확인하세요.

1-5. 명령 지도 — 손에 익힐 7개 + 알아 둘 2개, 외울 것은 "방향"

Git 명령이 많아 보여도, 실전의 대부분은 아래 9개로 돌아갑니다. 명령마다 4공간 그림에서 무엇이 어느 쪽으로 움직이는지만 잡으면 외울 것이 거의 없습니다.

이 중 git diff와 읽기 짝꿍인 git status(지금 어디까지 갔나)·git log(무엇이 기록됐나)까지 읽기 3종은 아무것도 바꾸지 않는 안전한 명령이라 언제든, 몇 번이든 실행해도 됩니다.

1-6. push vs pull — 반대 방향의 쌍

1-7. 브랜치는 "책갈피" — 복사본이 아닙니다

사진첩이 한 줄로만 쌓이면 팀 작업이 곤란해집니다. 내가 실험 중인 어중간한 사진과, 팀이 합의한 완성 사진이 한 줄에 섞이기 때문입니다. 그래서 Git은 사진첩에 갈래를 만들 수 있습니다. 이 갈래가 브랜치(branch)입니다.

오해가 가장 많은 부분: 브랜치는 폴더를 복사한 사본이 아닙니다. "이 갈래의 최신 사진"을 가리키는 책갈피일 뿐입니다. 그래서 브랜치를 아무리 만들어도 용량이 거의 늘지 않고, 만들고 지우는 데 1초가 안 걸립니다. 커밋을 하면 책갈피가 방금 찍은 사진으로 스스로 옮겨 갑니다.

main 갈래는 "언제나 작동하는 완성본"으로 깨끗하게 지키고, 새 작업은 새 책갈피(feat/…)를 만들어 그 갈래 위에 커밋을 쌓습니다. 브랜치 명령과 네이밍 규칙은 Ch.4에서 다룹니다.

1-8. GitHub Flow — 팀이 오늘부터 쓸 약속

브랜치와 PR을 어떤 순서로 쓸지는 팀마다 약속이 필요합니다. 우리는 GitHub가 권장하고 실무에서 가장 널리 쓰이는 GitHub Flow를 그대로 씁니다. 규칙은 다섯 줄이 전부입니다.

왜 이 수고를 할까요? 검토를 거친 변경만 main에 들어가므로 main이 깨질 일이 없고, 모든 변경에 "누가 만들고 누가 검토했는지" 기록이 남으며, 코드에 대한 대화가 PR 그 자리에 쌓입니다. 팀 프로젝트의 제출물이 바로 이 기록입니다.

1-9. 프로세스 한 바퀴 — 위 규칙을 명령으로 옮기면

다섯 규칙을 실제 명령 순서로 펼치면 아래와 같습니다 — 최초 1회의 걸음 0, 그리고 반복되는 여섯 걸음. 실전 프로젝트는 이 바퀴의 반복입니다. 지금 명령이 낯설어도 괜찮습니다 — 각 걸음을 해당 챕터에서 손으로 밟습니다.

막히는 지점은 대부분 걸음 사이의 이음새입니다 — 그때 Ch.7의 에러 카드가 현재 위치를 알려줍니다.

1-10. 이 과정에서 GitHub의 3가지 역할

1-11. GitHub 활용 레벨 — 지금 나는 어디에 있는가

이 핸드북의 목표는 수강 기간 안에 Lv.2 → Lv.4로 올라가는 것입니다. Ch.2~7이 Lv.2를, Ch.8~10이 Lv.3의 협업 근육을, Ch.11이 Lv.3~4의 생태계를 만듭니다.

처음 한 번만 제대로 설정하면 끝

2-1. OS별 설치

복사# 설치 확인 — 버전 숫자가 나오면 통과
git --version
git version 2.43.0

2-2. 초기 설정 + 추천 alias

이름과 이메일은 GitHub 계정과 동일하게 입력하세요. alias는 자주 쓰는 명령을 줄여줍니다.

복사# ①② 이름·이메일 줄은 복사 버튼에서 제외됩니다 — 본인 값으로 바꿔 직접 입력하세요
git config --global user.name "본인이름"
git config --global user.email "github가입이메일"
git config --global init.defaultBranch main
# (선택) VS Code 사용자만 — VS Code가 없으면 이 줄을 건너뛰세요 (commit 때 편집기를 못 찾습니다)
#   git config --global core.editor "code --wait"
# pull은 merge 방식으로 — 안 하면 최신 Git에서 divergent 에러 (Ch.7-C)
git config --global pull.rebase false
# 줄바꿈 통일 — 본인 OS 줄 하나만 골라 직접 입력. 팀원마다 다르면 "한 줄 고쳤는데 diff가 파일 전체" (Ch.7-B)
#   Windows: git config --global core.autocrlf true
#   macOS:   git config --global core.autocrlf input
# 한글 파일명이 status에서 숫자 코드로 깨져 보이는 것 방지
git config --global core.quotepath false
# 추천 alias — st(상태), lg(그래프 로그), undo(직전 커밋 취소), today(오늘 작업)
git config --global alias.st status
git config --global alias.lg 'log --oneline --graph --all --decorate'
git config --global alias.undo 'reset HEAD~1 --mixed'
git config --global alias.today 'log --oneline --since=midnight'
# 설정 전체 확인 — 화면이 : 나 (END)에서 멈추면 고장이 아니라 스크롤 모드입니다, q 키로 빠져나옵니다
git config --list
# (git log·diff도 출력이 길면 같은 화면이 됩니다 — 언제나 q로 탈출)

2-3. HTTPS vs SSH — 어떤 방식으로 연결할까

수업과 팀 실습은 HTTPS + 브라우저 인증이면 충분합니다 — Windows는 Git for Windows에 내장된 인증 관리자(GCM) 덕에 첫 push 때 브라우저 창 인증으로 끝납니다. SSH는 프로젝트 기간에 개인 PC에서 전환하는 선택지로 생각하세요(아래 2-4).

2-4. SSH Key 발급 — 4단계

복사ssh-keygen -t ed25519 -C "github가입이메일"
# Enter 3회 (기본 경로 사용, 개인 PC는 passphrase 생략 가능)
# 키가 이미 있으면 Overwrite (y/n)? 가 뜹니다 — 덮어쓰려면 y
ls -la ~/.ssh/
# id_ed25519(개인키) + id_ed25519.pub(공개키) 두 파일 확인

복사cat ~/.ssh/id_ed25519.pub
# 출력 전체를 복사. macOS는 pbcopy < ~/.ssh/id_ed25519.pub
# Windows Git Bash는 clip < ~/.ssh/id_ed25519.pub

복사ssh -T git@github.com
# 처음 한 번은 Are you sure you want to continue connecting? 이 뜹니다 — yes 를 끝까지 입력하고 Enter (y만 치면 거부됩니다)
Hi username! You've successfully authenticated...

2-5. AI 프로젝트 .gitignore — 시작 시 반드시 설정

API 키·대용량 모델·가상환경은 처음부터 추적 대상에서 제외합니다. 프로젝트 루트에 .gitignore 파일을 만들고 아래 내용을 넣으세요. 만드는 법: Git Bash에서 touch .gitignore 후 VS Code 등 편집기로 열어 붙여넣기 — 메모장 "다른 이름으로 저장"은 .txt가 붙을 수 있어 피하세요.

복사# 환경변수 (절대 커밋 금지)
.env
.env.local
.env.*.local
.streamlit/secrets.toml
# 가상환경·캐시
.venv/
__pycache__/
*.pyc
.ipynb_checkpoints/
# AI 모델 파일 (용량 초과 + 라이선스 문제)
*.gguf
*.bin
*.pt
*.safetensors
models/
# 벡터 DB (재생성 가능)
chroma_db/
faiss_index/
# 미디어·OS 파일
*.wav
*.mp3
.DS_Store
Thumbs.db

2-6. 명령 전에 확인할 두 가지

초보자가 자주 하는 실수는 명령을 잘못 입력하는 것이 아니라, 엉뚱한 폴더에서 명령을 실행하는 것입니다. 아래 두 줄을 모든 작업 전에 먼저 실행하세요.

복사# ① 나는 지금 어느 폴더에 있나
pwd
# ② git은 지금 어느 저장소를 보고 있나
git rev-parse --show-toplevel

커밋 메시지만 읽어도 무슨 작업인지 알 수 있어야 합니다

3-1. 기본 워크플로우

복사git status                    # 지금 상태 확인 — 모든 작업의 시작
git diff                      # Working Dir vs Staging 비교
git diff --staged             # Staging vs 마지막 커밋 비교
git add src/rag/embedding.py  # 파일 단위로 담기
# git add -p  ← 부분 선택 담기(권장)는 대화형이라 단독으로 실행하세요 — 블록 통째 붙여넣기에 섞이면 다음 줄을 답변으로 삼킵니다
git commit -m "feat: BGE-M3 임베딩 모델 교체 구현"
git log --oneline --graph --all

3-2. 커밋 타입 9종 — 형식: 타입: 무엇을 어떻게 했고 결과가 무엇인지

3-3. 타입별 실전 예시

feat — 새 기능

복사git switch -c feature/stt-whisper-local
git add src/stt/whisper_stt.py src/stt/__init__.py
git commit -m "feat: Whisper large-v3 로컬 STT 파이프라인 구현"
# 본문까지 쓰려면 git commit (에디터가 열림):
#   feat: Whisper large-v3 로컬 STT 파이프라인 구현
#   - LocalWhisperSTT 클래스 구현
#   - 한국어 자동 감지 및 강제 지정 옵션
#   - STTResult 데이터클래스로 반환 형식 통일
#   Closes #7

fix — 원인을 함께 기록

복사git switch -c fix/stt-language-misdetect
git add src/stt/whisper_stt.py
git commit -m "fix: Whisper 짧은 한국어 발화 오인식 — language='ko' 강제 지정"
# 원인 기록: 2초 미만 발화에서 language=None이면 중국어로 감지. Fixes #15

refactor — 기능이 같고 구조만 바뀌면 feat이 아니라 refactor

복사git switch -c feature/rag-module-split
git add src/rag/embedding.py src/rag/vectorstore.py src/rag/retriever.py
git commit -m "refactor: RAG 파이프라인을 기능별 모듈로 분리"

prompt — 프롬프트 변경 전용 타입

복사git switch -c feature/prompt-korean-quality
git add src/llm/prompts/system_prompt.txt
git commit -m "prompt: 시스템 프롬프트 한국어 응답 품질 개선"
# 이전 프롬프트와 비교: git diff HEAD~1 src/llm/prompts/system_prompt.txt

chore + 절대 하지 말아야 할 예

복사git switch -c chore/langchain-1x-migration
git add requirements.txt src/llm/ollama_client.py
git commit -m "chore: LangChain 0.x → 1.x 마이그레이션"
# ─── 절대 이렇게 하지 말 것 ─────────────
git commit -m "수정"        # 무슨 수정?
git commit -m "update"      # 무엇을?
git commit -m "작업중"      # 미완성 커밋 금지
git commit -m "asdf"        # 이력이 무의미해짐

하나의 기능 = 하나의 브랜치

브랜치는 작업 공간입니다. 원본 코드를 건드리지 않고 새 작업 공간에서 작업한 뒤, 완성되면 원본에 합칩니다. main이 최종 발표 자료라면, feature 브랜치는 초안 작업 파일입니다.

4-1. 브랜치 기본 명령

복사git branch -a                              # 모든 브랜치 보기
git switch -c feature/stt-whisper-groq     # 만들면서 이동
git switch main                            # main으로 이동
git branch -d feature/stt-whisper-groq     # 병합 완료된 브랜치 삭제
git push origin --delete feature/stt-whisper-groq  # 원격 브랜치도 삭제

4-2. 브랜치 네이밍 규칙

팀 프로젝트용

일일 과제 제출용

4-3. Merge 방향 원칙 — 가장 흔한 실수 지점

복사# STEP 1. 결과를 받을 브랜치(main)로 이동
git switch main
# STEP 2. 원격 main 최신화
git pull origin main
# STEP 3. feature 브랜치를 현재(main)에 병합
git merge feature/rag-chromadb
# STEP 4. push + 브랜치 삭제
git push origin main
git branch -d feature/rag-chromadb
git push origin --delete feature/rag-chromadb
# ─── 주의: 아래는 "main에 반영"이 목적이었다면 방향이 반대입니다 ───
git switch feature/rag-chromadb
git merge main        # 이 결과는 feature ← main — main에는 아무것도 반영되지 않습니다
# 단, "내 브랜치를 최신 main으로 갱신"하려는 목적이면 이 방향이 정상입니다 (PR 전 최신화, Ch.7-2)

4-4. GitHub Flow — 우리가 쓰는 6단계

4-5. 원격 저장소 핵심 명령

복사git clone git@github.com:aihuman-7th/저장소이름.git   # 원격 저장소 복제
git remote add origin git@github.com:계정/저장소.git   # 기존 폴더에 원격 연결
git push -u origin main            # 첫 push (-u로 기본 연결 저장)
git push origin feature/rag-chromadb
git pull                           # fetch + merge
git pull --rebase                  # fetch + rebase (이력을 일자로)

PR 만들기 — 10단계로 따라 하기

Pull Request(PR)는 "내가 만든 변경을 main에 합쳐도 될까요?"라고 팀에 묻는 요청입니다. GitHub에서 변경 내용을 설명하고, 동료에게 리뷰를 받고, 문제가 없는지 확인한 뒤 합칩니다. PR은 코드가 아니라 "무엇을 왜 만들었는지"를 설명하는 문서이기도 합니다.

아래에서는 하나의 PR이 만들어지고 합쳐지는 과정을 10단계로 나눠 봅니다. 정상적인 방법을 먼저 보여주고, 바로 아래에 자주 만나는 실수와 해결 방법을 카드로 붙였습니다. 리뷰어가 수정을 요청하면 작업자가 추가 커밋을 push하는 피드백 루프(⑥→⑦→⑥)가 PR의 심장입니다.

⓪ 팀 저장소 준비

mkdir -p ~/work && cd ~/work   # 확인 1) 작업 폴더 만들기 겸 이동 — OneDrive·바탕화면 밖, 공백·한글 없는 경로가 안전합니다
# Windows 계정 이름이 한글이면(~가 한글 경로면): mkdir -p /c/work && cd /c/work
git clone https://github.com/aihuman-7th/본인팀저장소.git   # 본인 팀 주소로 바꿔 직접 입력
cd 본인팀저장소   # ★ 확인 2) clone은 폴더만 만듭니다 — 이 cd를 빠뜨리면 다음 명령이 전부 어긋납니다
pwd && git rev-parse --show-toplevel   # 지금 팀 저장소 안인가 — 저장소 폴더가 나와야 통과
git remote -v                          # 확인 3) origin — 팀 저장소 주소가 이미 보여야. clone이 자동으로 넣어줍니다(손으로 add 금지)

① 브랜치 만들기 — 최신 main에서 출발합니다

복사# 출발점을 최신으로 맞춤
git switch main
git pull origin main

git switch -c feat/intro-본인GitHub아이디   # 본인 아이디로 바꿔 직접 입력
git branch --show-current   # feat/intro-내아이디인지 확인

# 커밋을 쌓기 전에 알아챘다면: 잘못 분기한 브랜치를 지우고 최신 main에서 다시 분기
git switch main
git branch -D feat/login   # 잘못 만든 브랜치 정리 — 안 지우면 'a branch named ... already exists' 에러가 납니다
git pull origin main
git switch -c feat/login

# push 전이라면: 커밋을 새 브랜치로 옮기고 main을 되돌림
git status                       # ⓪ 미커밋 변경이 있으면 먼저
git stash push -u -m "main 복구 전 임시 보관"
git branch feat/login            # ① 지금 커밋을 새 브랜치로 보존
git fetch origin                 # ② 지금 origin/main을 최신으로 맞춘 뒤 되돌립니다
git reset --hard origin/main    # ③ main을 원격 상태로 되돌리기
git switch feat/login           # ④ 커밋된 작업이 보존된 브랜치로 이동
git stash pop                   # ⓪에서 "Saved working directory…"가 떴을 때만 실행 (No stash entries found = 보관한 게 없다는 뜻, 무해)

② 작업하고 기록하기 — 작게, 자주

복사git diff README.md
git add README.md
git diff --staged
git commit -m "docs: README에 팀원 소개 행 추가"

# push 전이라면: 최근 커밋들을 풀어서 다시 묶기
git reset HEAD~3
# 기본 모드(--mixed)는 세 커밋의 변경을 스테이지에서 내려 작업 폴더에 되돌려 둡니다 — 파일은 그대로
# 이제 파일 단위로 나눠 add → 의미 있는 커밋 2~3개로 재구성
git add login.py
git commit -m "feat: 로그인 폼 구현"
git add auth.py
git commit -m "feat: 인증 로직 추가"

③ GitHub에 올리기 — 첫 push

복사git branch --show-current   # 먼저 확인 — feat/… 가 아니라 main이 나오면 멈추고 ①로 (main도 그대로 push되어 버립니다)
git push -u origin HEAD
# HEAD = 지금 서 있는 내 브랜치. 다음부터는 git push만으로 충분

git push -u origin feat/login

git push -u origin feat/login

④ PR 열기 — 합칠 방향과 내용을 확인합니다

⑤ 리뷰 요청 — 읽어줄 팀원을 지정합니다

⑥ 리뷰 받기 — 질문과 제안을 확인합니다

⑦ 수정 반영 — 같은 PR에 이어서 올립니다

git switch feat/intro-본인GitHub아이디   # 원래 PR 브랜치로 직접 이동

복사git diff README.md
git add README.md
git commit -m "docs: 리뷰 반영 — 팀원 소개 수정"
git push

git push

⑧ 충돌 해결 — 두 사람의 변경을 합칩니다

# 마커 잔재 전수 검사 — 세 마커를 모두 검사합니다 (위에서부터 지우다 만 경우 ===·>>>만 남기도 합니다)
# ^(줄 시작) 앵커가 중요: README의 충돌 안내 문구(문장 중간 마커)는 건너뛰고 진짜 마커만 잡습니다
git grep -nE '^(<<<<<<<|=======$|>>>>>>>)'
# 마커 삭제 후
git add 파일
git commit -m "fix: 충돌 마커 제거"
git push

⑨ main에 합치기 — 리뷰가 끝난 뒤 진행합니다

머지 방식 3종 — 버튼의 드롭다운에는 세 가지가 있습니다. 팀 기본값은 merge commit입니다.

⑩ 마무리 — 다음 작업을 준비합니다

복사git switch main
git pull origin main
git fetch --prune   # 원격에서 지워진 브랜치 목록 정리 — fetch는 원격 정보만 받아옵니다
# (pull = fetch + merge. fetch만 하면 내 브랜치의 파일은 바뀌지 않습니다)

git branch -d feat/intro-본인GitHub아이디   # 머지 끝난 내 브랜치 이름을 직접 입력해 삭제 (팁: @{-1} = "직전 브랜치"의 축약형)

git switch main
git pull origin main
# 작업 전이면: 브랜치를 지우고 최신 main에서 다시 분기
# 이미 작업했다면: git switch feat/next && git merge main

팀의 PR 규칙 한 장

이 10단계는 한 번 외우고 끝나는 절차가 아니라 프로젝트 기간 내내 반복합니다. 어느 단계에서 막혔는지 확인한 뒤, 이 챕터의 해당 카드를 다시 찾아보세요.

5-11. PR 제목 규칙

복사[Ch02-Day06] Anthropic API 스트리밍 응답 구현
[Ch03-Mini] PDF 기반 RAG Q&A 챗봇 완성
[Fix] 토큰 초과 시 재시도 로직 추가
feat: STT Groq API 마이그레이션 (8초 → 0.7초)   # 성능 변화를 제목에 담으면 최고

5-12. PR 본문 템플릿 — AI 활용 내역까지

복사## 구현 내용
- Anthropic API의 스트리밍 응답을 구현했습니다
- 토큰 사용량을 실시간으로 출력하는 기능을 추가했습니다

## AI 활용 내역
- Claude에게 스트리밍 구현 방법을 질문하고 코드를 생성받았습니다
- 생성된 코드에서 에러 처리 부분이 누락된 것을 발견하고 직접 추가했습니다

## 어려웠던 점 / 해결 방법
- 비동기 스트리밍에서 yield 사용법이 헷갈렸습니다
- Python 공식 문서와 Claude의 도움으로 해결했습니다

## 리뷰 요청 포인트
- 에러 처리 방식이 올바른지 확인해주세요
- 더 효율적인 스트리밍 방법이 있는지 피드백 부탁드립니다

## 셀프 체크리스트
- [x] 코드가 실행됩니다
- [x] 린트 에러가 없습니다
- [x] README를 업데이트했습니다
- [ ] 테스트를 작성했습니다 (다음 PR에서 추가 예정)

5-13. 팀 공용 PR 템플릿 파일

저장소에 아래 파일을 만들어두면 PR을 열 때마다 자동으로 양식이 채워집니다.

복사<!-- 파일 위치: .github/PULL_REQUEST_TEMPLATE.md — 이 HTML 주석은 PR 화면에 표시되지 않습니다 -->
## 변경 내용
- (무엇을 구현/수정했는지)

## 성능 / 결과 변화
- Before: (기존 상태)
- After: (변경 후 상태)

## 테스트 방법
```bash
python tests/test_stt.py
```

## 체크리스트
- [ ] .env 파일 미포함 확인
- [ ] 모델 파일(.gguf) 미포함 확인
- [ ] requirements.txt 업데이트

Closes #

받는 것보다 "주는 것"이 더 많이 배웁니다

코드리뷰는 동료의 코드를 읽고 개선점을 댓글로 제안하는 활동입니다.

6-1. GitHub에서 코드리뷰 하는 방법 — 4 STEP

6-2. 단계별 코드리뷰 체크리스트

기초 단계 — Spec과 코드 기본기

LLM + RAG 단계

에이전트 + 배포 단계

6-3. 좋은 댓글 vs 나쁜 댓글

6-4. AI 코드리뷰 — 일반 리뷰와 무엇이 다른가

AI 프로젝트의 코드 리뷰는 일반 소프트웨어 리뷰와 다릅니다. 프롬프트 변경, 모델 교체, 임베딩 모델 교체 등 AI 특화 항목을 리뷰어가 체계적으로 확인해야 합니다.

프롬프트 변경 PR 체크리스트

복사# 프롬프트 변경 PR에서 리뷰어가 확인하는 방법
git diff main feature/prompt-v2 -- src/llm/prompts/   # 1. 변경 내용 확인
git switch feature/prompt-v2                          # 2. 로컬에서 직접 테스트
python scripts/test_prompt.py --samples 10
# 3. LangSmith에서 이전/이후 run 비교 — run_name으로 커밋 hash 검색 (Ch.10)

모델 전환 PR 체크리스트 (예: Ollama qwen → Groq llama, 로컬 → 클라우드 API)

임베딩 모델 교체 PR 체크리스트 (예: all-MiniLM → bge-m3)

6-5. 건설적 AI 코드리뷰 문화

리뷰어 입장에서

• 사람이 아닌 코드를 비판하세요: "이 프롬프트가 할루시네이션을 유발할 것 같아요" (당신이 나쁘다는 뜻이 아님)
• 질문 형태로 제안: "이 청크 크기(512)를 256으로 줄이면 한국어 검색 품질이 나아질 것 같은데 어떻게 생각하세요?"
• 실험 근거 요청: "이 프롬프트 변경의 효과를 수치로 보여주실 수 있나요?"
• Nitpick 구분: 변수명 스타일(선호도)과 API Key 노출(보안 이슈)을 다르게 취급

PR 작성자 입장에서

• 모든 리뷰 댓글에 응답하기 (반영 / 미반영 이유 모두 명시)
• 실험 결과를 PR 설명에 먼저 첨부해서 리뷰어 부담 줄이기
• 대규모 프롬프트 변경은 작은 PR 여러 개로 분리
• '실험 중인 코드'는 experiment/* 브랜치에서, '확정된 코드'만 main으로 PR

충돌은 사고가 아니라 협업의 일상입니다

충돌(conflict)은 두 사람이 같은 곳을 다르게 고쳤다는 알림입니다. Git이 임의로 한쪽을 버리지 않고 사람에게 판단을 넘기는 것 — 오히려 안전장치입니다.

7-1. 충돌 마커 해부

<<<<<<< feat/intro-me      ← 내 브랜치가 쓴 내용
| 나 | my-id | 안녕하세요 |
=======
| 팀원 | their-id | 반갑습니다 |
>>>>>>> main               ← 이미 머지된 내용

마커 세 줄(<<<·===·>>>)은 git이 그어준 경계선입니다. 해결 = 경계선을 지우고, 남길 내용을 사람이 결정하는 것. 위 소개 표처럼 둘 다 의미가 있으면 두 행 모두 살리면 됩니다.

7-2. 해결 방법 두 가지

방법 1 — GitHub 웹 에디터 (처음에는 이것부터)

git switch feat/내브랜치
git pull --no-rebase origin main   # main의 최신을 내 브랜치로 가져옴 → 충돌 발생
CONFLICT (content): Merge conflict in README.md
# 해결이 꼬였으면 병합 자체를 취소하고 pull 전 상태로: git merge --abort
# 편집기에서 마커 정리 후
git add README.md
git commit -m "merge: main 충돌 해결"
git push
git grep -nE '^(<<<<<<<|=======$|>>>>>>>)'   # 마커 3종 잔재 검사 — 아무것도 안 나와야 완료 (^앵커: README 안내 문구는 제외)

7-3. 고급 기능 — Stash · Rebase · Tag

git stash — 작업 중 급한 일이 생겼을 때

복사git stash push -m "RAG 청크 크기 튜닝 작업 중"   # 작업 임시 보관
# ... 긴급 대응 후 복귀 ...
git switch feature/rag-chunk-tuning
git stash pop                                    # 보관한 작업 복원
git stash list                                   # 보관 목록 확인 — stash는 쌓입니다. pop 후에도 남은 항목이 없는지 여기서 확인

git rebase -i — push 전 커밋 정리

복사git rebase -i HEAD~3
# pick   a1b2c3  feat: Whisper STT 기본 구조
# squash d4e5f6  fix: 오타 수정
# squash g7h8i9  fix: 또 오타 수정
# → 커밋 3개가 1개로 합쳐짐. push 전에만 사용. 이미 push된 브랜치는 금지.

git tag — 마일스톤 버전 표시

복사git tag -a m1-submit -m "M1 마일스톤 제출: STT+TTS+LLM 완성"
git push origin --tags
git checkout m1-submit   # 제출 버전으로 이동
git switch -             # 원래 브랜치로 복귀

7-4. AI 프로젝트 특화 실수 TOP 5

7-5. 자주 쓰는 복구 명령

복사git commit --amend -m "올바른 메시지"   # 직전 커밋 메시지 수정 (push 전)
git reset --soft  HEAD~1               # 커밋만 취소 (staged 유지)
git reset --mixed HEAD~1               # 커밋 취소 (modified 상태)
git reset --hard  HEAD~1               # 커밋 + 파일 모두 되돌림 (주의!)
git restore 파일명.py                   # 수정 취소
git restore --staged 파일명.py          # Staging 취소

7-6. 에러 카탈로그 — 상황별 해결 카드

에러 메시지는 "망했다"는 뜻이 아니라 현재 상태를 알려주는 안내입니다. 수업과 프로젝트에서 자주 만나는 상황을 증상별로 모아 두었습니다. 카드 읽는 순서: ① 터미널의 에러 문구와 카드의 회색 문장을 비교하고(에러는 처음부터 끝까지 읽기) ② 펼치기 전에 원인을 한 번 추측한 뒤 ③ 복구 명령을 실행하고 예방 습관을 하나 기억합니다.

카테고리 바로가기 — A 위치·시작 · B 스테이징·커밋 · C 원격·push·인증 · D 브랜치·병합 · E PR · F 보안 · G 되돌리기 SOS

케이스 전체 펼치기 — 페이지 내 검색(Ctrl+F)으로 복구 명령까지 찾고 싶을 때 먼저 누르세요 (Ch.5의 케이스 카드도 함께 열립니다)

A. 위치·시작

pwd                       # 지금 위치 확인
cd ~/work/저장소이름       # 있는 저장소로 '들어가기' — 이게 답입니다
git status

ls               # clone이 만든 폴더 이름 확인
cd 저장소이름     # 그 폴더 안으로 이동
git status

ls               # 폴더가 정말 없는지 확인
# 작업 폴더 자체가 없다면: mkdir -p ~/work && cd ~/work
# clone을 건너뛴 것이라면: 본인 저장소 주소로 clone부터
git clone https://github.com/내아이디/내저장소.git
cd 내저장소

pwd
git rev-parse --show-toplevel   # 저장소 루트가 정말 홈 폴더인지 확인
mv .git .git-home-mistake-backup   # 즉시 삭제하지 않고 되돌릴 수 있게 격리
git status   # "not a git repository"가 나오면 격리 성공
cd 프로젝트폴더

# 1) 사고로 생긴 저장소를 지우지 말고 격리 (작업한 파일은 폴더에 그대로 남습니다)
git log --oneline          # 첫 줄에 (root-commit)이 보이면 확진
mv .git .git-accident-backup
# 2) 팀 저장소를 '제대로' 복제하고 그 안으로 들어가기
git clone https://github.com/aihuman-7th/본인팀저장소.git
cd 본인팀저장소
# 3) 새 브랜치를 만들고, 아까 만든 파일을 이 저장소로 옮겨 담기
git switch -c feat/intro-본인아이디
mv ../내파일 .
git add . && git commit -m "feat: 파일 추가"
git push -u origin HEAD    # 이제 origin은 clone이 넣어둔 것 — 손으로 add할 필요 없음

B. 스테이징·커밋

git log --oneline   # 방금 커밋이 기록됐는지 확인
git status          # 고친 게 있는데도 이 메시지면: 편집기 저장(Ctrl+S, macOS는 Cmd+S) 여부와 pwd 확인

pwd              # ① 지금 어디인가
ls               # ② 파일이 여기 있는가
cd 프로젝트폴더    # ③ 올바른 폴더로 이동
git add comment.js

# 아래 두 줄은 본인 이름·GitHub에 연결된 이메일로 바꿔 입력하세요 (그대로 치면 전원이 홍길동이 됩니다)
git config --global user.name  "본인이름"
git config --global user.email "github연결이메일"
git commit -m "feat: 첫 커밋"   # 다시 커밋

# Vim이 열렸다면: Esc 키 → :q! 를 입력 → Enter (저장 없이 탈출)
# Ch.2-2에서 code --wait를 설정했다면 Vim 대신 VS Code 탭이 열립니다 — 저장하지 않고 탭을 닫으면 커밋 취소
# "Aborting commit due to empty commit message."가 뜨면: 편집기를 못 찾았거나 메시지가 빈 것 — 아래처럼 -m으로
git commit -m "feat: 커밋 메시지"  # -m과 함께 다시

# 먼저 확인: 에디터(VS Code 등)·다른 터미널에서 git 작업이 진행 중이지 않은지
# — 작업이 끝났는데 남아 있는 파일일 때만 삭제합니다
rm .git/index.lock
git commit -m "feat: 커밋 메시지"

git commit --amend -m "feat: 댓글 기능 추가"   # push 전이면 메시지만 교체

git config --global core.quotepath false
git status   # 한글 파일명이 제대로 보입니다

git log -1 --format='%an %ae'   # 최근 커밋에 기록된 이름·이메일 확인
# GitHub → Settings → Emails 의 등록 이메일과 대조한 뒤
git config --global user.email "GitHub에-연결된-이메일-또는-noreply-주소"
# 이미 쌓인 과거 커밋: 커밋에 적힌 그 이메일을 GitHub 계정(Settings → Emails)에 추가하면 소급 연결됩니다
# 주의: private 저장소 커밋은 여기까지 해도 잔디에 안 보입니다 — 아래 예방의 Private contributions 체크까지

C. 원격·push·인증

git pull    # 원격의 새 커밋을 먼저 합치기
git push    # 충돌이 나면 7-2 절차로 해결 후 push

# 길 A. 작업이 완성됐다면 — 커밋 후 pull
git add README.md
git commit -m "feat: 소개 행 수정"
git pull
# 길 B. 아직 어중간하다면 — stash로 치워 두고 pull
git stash push -u -m "pull 전 임시 보관"
git pull
git stash pop    # 치워 둔 수정 복원 — 충돌이 나면 7-2 절차로 해결

# usage: 줄의 < > 괄호 자리가 곧 빠뜨린 단어입니다
git remote add origin https://github.com/내아이디/git-practice.git

# HTTPS로 시작했다면 — 주소가 git@…라면 HTTPS로 전환
git remote set-url origin https://github.com/내아이디/git-practice.git
# SSH를 쓰려면: 공개키 등록(Ch.2-4) 후 테스트
cat ~/.ssh/id_ed25519.pub   # 복사 → GitHub Settings → SSH and GPG keys
ssh -T git@github.com

git remote -v      # 아무것도 안 나오면 연결이 없는 것
git remote add origin https://github.com/내아이디/git-practice.git
# 주소가 이상하게 등록돼 있다면(예: git@github.com:.git — 자리표시자를 안 채운 채 실행한 흔적):
#   git remote set-url origin 올바른주소  로 교체
git push -u origin main   # -u: 다음부터는 git push만으로 OK

git rm --cached models/qwen3.5.gguf   # 추적만 제거 (파일은 유지)
echo "*.gguf" >> .gitignore           # >는 새로 쓰기, >>는 파일 끝에 덧붙이기
git add .gitignore
git commit --amend --no-edit          # 방금 커밋에서 대용량 파일 제외
git push
# 여러 커밋 전에 들어갔다면: 이력 정리가 필요하니 상황 전체를 AI에게 설명하세요

git push   # 다시 시도 → 뜨는 브라우저 창에서 GitHub 로그인
# macOS에서 브라우저 창이 원래 안 뜨는 경우: 고장이 아닙니다 —
#  기본 git에는 GCM이 없어서입니다. Ch.2-3의 macOS 인증 안내
#  (GCM 설치 / gh auth login / PAT) 중 하나로 해결
# 창이 안 뜨면(Windows): 저장된 옛 자격 증명을 지우고 재시도
#  Windows: 자격 증명 관리자 → git:https://github.com 제거
#  macOS:   키체인 접근 → github.com 항목 제거

# ① 주소 재확인 — 손으로 치지 말고 저장소 페이지의 초록 Code 버튼에서 다시 복사
# ② 브라우저에서 github.com/aihuman-7th 접속 → 상단 초대 배너가 보이면 수락
# ③ 그래도 안 되면: 등록 폼 제출 여부를 확인하고 강사에게 등록 확인을 요청
git clone https://github.com/aihuman-7th/본인팀repo.git

git remote -v   # URL의 팀 이름이 내 팀이 맞는지 확인
# 다른 팀 저장소였다면: 본인 팀 저장소를 다시 clone해서 작업
# 본인 팀 저장소가 맞다면: 초대 수락 여부 확인 후, 강사에게
#  collaborator 등록 확인을 요청

D. 브랜치·병합

git branch --show-current   # 원래 브랜치 이름을 먼저 기록
git stash push -u -m "브랜치 이동 전 임시 보관"
git switch main            # 필요한 확인·동기화 작업
git switch 원래브랜치       # 변경을 만든 브랜치로 돌아온 뒤
git stash pop              # 다시 꺼내기 — 충돌 가능

# 구경만 했고 보존할 변경·커밋이 없다면
git switch main

# detached 상태에서 커밋했다면 main으로 이동하지 말고 즉시
git switch -c fix/rescue-work   # 현재 커밋을 새 브랜치에 보존

# A. 아직 push 전이라면 — 커밋을 브랜치로 옮기고 main 되돌리기
git status                       # ⓪ 미커밋 변경이 있으면 먼저
git stash push -u -m "main 복구 전 임시 보관"
git branch feat/작업             # ① 지금 커밋을 새 브랜치로 복사
git fetch origin                 # ② 지금 origin/main을 최신으로 맞춘 뒤 되돌립니다
git reset --hard origin/main    # ③ main을 원격 상태로 (커밋은 ①에 안전)
git switch feat/작업             # ④ 브랜치에서 push → PR로 진행
git stash pop                   # ⓪에서 보관한 것이 있을 때만 복원
# reset --hard는 커밋을 브랜치에 보존하고 미커밋 변경을 stash한 뒤에만 쓰는 예외입니다

# B. 이미 push했다면 — 이력을 지우지 않고 취소 커밋으로
git revert 해시                  # 취소 커밋 생성 → push 후 PR로 재작업

git switch main        # ① 결과를 '받을' 브랜치로 먼저 이동
git pull               # ② 원격 main 최신화
git merge feat/login   # ③ feature를 main에 병합
git push               # ⚠️ 개인 연습 저장소에서만 — 팀 저장소는 이 줄 대신 브랜치 push 후 PR로 (main 직접 push 금지)

git fetch origin        # 원격 브랜치 목록 최신화
git switch feat/login   # 원격에 같은 이름이 있으면 자동으로 연결해 가져옵니다
# 이어서 작업 → 커밋 → git push — 같은 브랜치이므로 열려 있던 PR이 자동 갱신됩니다 (Ch.5 ⑦)

E. PR

base: main  ←  compare: feat/login   # 이 방향으로 다시 선택
# 이미 반대로 생성했다면 그 PR은 Close 후 올바른 방향으로 재생성

# 실수로 만든 중복 PR은 Close 하고, 리뷰받던 브랜치에서:
git switch feat/login
git add login.py && git commit -m "fix: 리뷰 반영 — 예외 처리 추가"
git push        # 기존 PR에 커밋이 자동으로 추가됩니다

git switch main
git pull
git switch -c feat/next-work   # 최신 main에서 분기

F. 보안

# 0) 키부터 즉시 재발급 — 파일을 지워도 이력에 남으므로 재발급이 진짜 해결
echo ".env" >> .gitignore
git rm --cached .env        # 추적에서 제거 (로컬 파일은 유지)
git add .gitignore
git commit -m "fix: .env 추적 제거"
git push

git rm --cached .env   # 추적 목록에서만 제거
git commit -m "chore: .env 추적 중단"
git push

# 민감 파일이면 키 재발급부터. 그다음 로컬에서:
git pull                    # 웹 커밋을 로컬로 가져오고
git rm --cached .env        # 추적 제거 후
git commit -m "fix: 웹 업로드된 .env 제거"
git push

G. 되돌리기 SOS

git log --oneline               # 삭제가 들어간 커밋 해시 확인
git revert a1b2c3d              # 그 커밋을 '취소하는 새 커밋' 생성 (push 후에도 안전)
git push
# 파일 하나만 살릴 때: git restore --source=b2c3d4e src/app.py  (b2c3d4e = 삭제 전 커밋)

git commit --amend -m "feat: 로그인 기능 추가"   # push 전에만
# 이미 push했다면: 그대로 두는 게 안전 — force push는 팀 이력을 깨뜨립니다(강사에게 문의)

git log --oneline        # 머지 커밋 해시 확인
git revert -m 1 a1b2c3d  # -m 1 = main 쪽 부모 기준으로 취소
git push

7-7. 여기 없는 에러를 만났을 때

7-8. 자주 묻는 질문 (FAQ)

복사git stash push -u -m "복구 전 임시 보관"   # ⓪ 미커밋 변경부터 보존 — 이게 없으면 아래 reset이 작업을 지웁니다
git branch rescue/my-work                 # ① 커밋을 새 브랜치로 보존
git fetch origin
git reset --hard origin/main              # ② main을 원격 상태로 — 커밋이 몇 개든 안전 (①에 보존됨)
git switch rescue/my-work                 # ③ 보존한 브랜치에서 push → PR로 진행
git stash pop                             # ⓪에서 "Saved…"가 떴을 때만

복사git commit --amend -m "수정된 커밋 메시지"   # push 전이라면 수정 가능
# 이미 push했다면 강사에게 문의 (force push는 주의 필요)

복사git log --oneline                          # 삭제 전 커밋 확인
git checkout 커밋해시 -- 파일경로            # 특정 커밋의 파일 복구
# 예: git checkout abc1234 -- ch02/day06/code.py

복사# GitHub에서 PR 머지 후 "Delete branch" 클릭 (권장)
git checkout main
git branch -d ch02/day06-홍길동   # 로컬에서도 삭제
git fetch --prune                # 원격 브랜치 목록 정리

역할 분담 → 브랜치 격리 → 일일 루틴 — 이 세 가지가 전부입니다

8-1. 팀 구성과 역할 분담 (AI 음성 에이전트 프로젝트 예시)

8-2. 브랜치 전략 (GitHub Flow)

복사main
├─ feature/stt-whisper-groq        (팀원 A)
├─ feature/llm-tool-calling        (팀원 B)
├─ feature/rag-bge-m3-embedding    (팀원 C)
├─ feature/ui-chat-interface       (팀원 D)
└─ release/m1                      (팀장, 마일스톤 직전 생성)

8-3. 일일 협업 루틴

8-4. 역할별 실전 시나리오 4가지

복사git switch main && git pull origin main
git switch -c feature/stt-groq-migration
git add src/stt/whisper_stt.py
git commit -m "feat: Groq Whisper API 클라이언트 추가"
git add .env.example
git commit -m "docs: GROQ_API_KEY 환경변수 예시 추가"
git push origin feature/stt-groq-migration
# PR 제목: 'feat: STT Groq API 마이그레이션 (8초 → 0.7초)'

복사git switch feature/rag-bge-m3-embedding
git fetch origin && git rebase origin/main
# 충돌 해결 후
git add src/rag/retriever.py && git rebase --continue
git push --force-with-lease origin feature/rag-bge-m3-embedding
# --force-with-lease: 남의 커밋을 덮어쓰지 않는 안전한 force push
# 전제: 이 브랜치에 나 혼자만 커밋할 때 — 둘 이상이 함께 쓰는 브랜치에는 금지 (Ch.7-3의 rebase 규칙과 동일)

복사git stash push -m "UI 다크모드 작업 중"     # 하던 일 보관
git switch main && git pull origin main
git switch -c hotfix/streamlit-session-crash
git add src/ui/streamlit_app.py
git commit -m "fix: Streamlit session_state 초기화 누락 수정"
# ⚠️ 아래 직접 merge·push는 개인 연습 저장소 기준 — 팀 저장소에서는 hotfix도 push 후 PR로 (main 직접 push 금지)
git switch main && git merge --no-ff hotfix/streamlit-session-crash
git push origin main
git branch -d hotfix/streamlit-session-crash
git switch feature/ui-dark-mode && git stash pop   # 하던 일 복귀

복사git switch main && git pull origin main
git switch -c release/m1
echo '1.0.0-m1' > VERSION
git add VERSION && git commit -m "chore: M1 마일스톤 버전 설정"
# 팀원 전체 최종 테스트 후
# ⚠️ 아래 직접 merge·push는 팀장이 팀 합의 하에 릴리즈 시점에만 쓰는 예외 — 평상시에는 PR 경유 (main 직접 push 금지)
git switch main
git merge --no-ff release/m1 -m "release: M1 마일스톤"
git tag -a m1-submit -m "M1 마일스톤 제출"
git push origin main && git push origin m1-submit

8-5. 충돌 없는 협업 5가지 규칙

8-6. 모듈 간 인터페이스 합의 — interfaces.py

팀장이 최초 작성하고, 팀원들은 이 스펙에 맞게 구현합니다. 실제 구현 전에도 Mock으로 연동 테스트가 가능해집니다.

복사# src/interfaces.py — 팀장이 최초 작성
from dataclasses import dataclass, field

@dataclass
class STTResult:
    text: str
    language: str
    confidence: float
    segments: list[dict] = field(default_factory=list)

@dataclass
class RAGResult:
    answer: str
    sources: list[str]
    retrieval_scores: list[float]

# 실제 구현 전에도 Mock으로 연동 테스트 가능
def mock_transcribe(audio_path: str) -> STTResult:
    return STTResult(text='테스트', language='ko', confidence=0.95)

8-7. 과정 전체의 저장소 구조

조직(Organization): aihuman-7th
├── 강사 저장소: curriculum            ← 교안, 강의 자료, 과제 출제
├── 공용 저장소: project-template      ← 과제 템플릿
├── 수강생 저장소: {이름}-assignments  ← 개인 과제 제출
│     ├── ch01_python/day01/          ← README.md + spec.md + code.py
│     ├── ch02_llm/  ch03_rag/  ch04_agentic_ai/  ch05_productization/
│     └── README.md                   ← 본인 소개 + 포트폴리오 요약
└── 팀 저장소: team-{번호}-project     ← 팀 최종 프로젝트

8-8. 주간 워크플로우 예시

팀 협업의 질은 저장소 첫날 설정이 결정합니다

.github/ 폴더는 팀장이 저장소를 초기화할 때 가장 먼저 설정해야 할 공간입니다. 브랜치 보호 규칙, 자동 CI 테스트, 이슈 템플릿이 여기에 삽니다.

9-1. 브랜치 보호 규칙 (Branch Protection Rules)

main 브랜치를 실수로 직접 push하거나 테스트를 건너뛰고 병합하는 사고를 막는 설정입니다. 설정 위치: 저장소 → Settings → Branches → Add branch protection rule → main

9-2. GitHub Actions CI 파이프라인

PR을 생성하면 자동으로 테스트와 코드 검사가 실행됩니다. 사람이 리뷰하기 전에 기본 품질을 기계가 확인합니다.

복사# .github/workflows/ci.yml
name: CI — pytest + lint
on:
  pull_request:
    branches: [ main ]
  push:
    branches: [ main ]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Python 3.11 설정
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: 의존성 설치
        run: pip install -r requirements.txt
      - name: 단위 테스트
        run: pytest tests/ -v --tb=short
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
      - name: 코드 스타일 검사
        run: |
          pip install flake8
          flake8 src/ --max-line-length=100 --exclude=__pycache__
      - name: .env 파일 미포함 확인
        run: |
          if find . -name '.env' -not -path './.git/*' | grep -q '.'; then
            echo 'ERROR: .env 파일이 커밋에 포함됐습니다!'
            exit 1
          fi

9-3. Issue 템플릿

복사# .github/ISSUE_TEMPLATE/bug_report.md
---
name: 버그 리포트
about: 버그를 발견했을 때 사용
labels: bug
---
## 버그 설명
(무엇이 잘못됐는지)
## 재현 방법
1. '...' 실행
2. '...' 입력
3. 오류 발생
## 예상 동작
(원래 어떻게 되어야 했는지)
## 실제 동작 / 오류 메시지
```
(오류 로그 붙여넣기)
```
## 환경
- OS: (예: Windows 11, macOS 14, Ubuntu 22.04)
- Python: (예: 3.11.5)
- LLM Provider: (예: Ollama / Groq)

9-4. Issue → 브랜치 → PR — 이슈 중심 작업 흐름

Milestone으로 마일스톤 관리

GitHub → Issues → Milestones → New milestone으로 M1, M2, M3를 생성하고 이슈를 연결합니다.

9-5. n8n으로 운영 자동화 — PR 알림·리뷰어 배정·리마인더

수강생 수십 명의 PR을 수동으로 관리하면 운영이 불가능합니다. n8n(노코드 자동화 도구)으로 반복 작업을 자동화하는 4가지 워크플로우입니다. 운영자용 내용이지만, "GitHub Webhook → 처리 → 알림" 구조는 여러분이 앞으로 만들 모든 자동화의 원형입니다.

# 워크플로우 1 — PR 생성 → Discord 알림
[트리거] GitHub Trigger (Event: Pull Request opened)
   ↓
[처리] Set 노드 — "{{PR 작성자}} 님이 PR을 올렸습니다!" + 제목·URL 추출
   ↓
[출력] Discord 노드 — #코드리뷰 채널로 전송

복사// 워크플로우 2 — 리뷰어 자동 배정 (n8n Code 노드)
const students = ["hong-gildong", "kim-cheolsu", "lee-younghee" /* ... */];
const author = $input.item.json.pull_request.user.login;
const candidates = students.filter(s => s !== author);   // 작성자 제외
const shuffled = candidates.sort(() => Math.random() - 0.5);
const reviewers = shuffled.slice(0, 2);                  // 무작위 2명
return [{ json: { reviewers } }];

"어떤 코드에서 어떤 프롬프트로 어떤 결과였는지" — 완전한 이력

일반 소프트웨어는 코드만 버전 관리하면 됩니다. AI 개발은 코드 외에도 프롬프트, 모델, 파라미터(temperature, chunk_size 등)가 성능을 결정합니다. Git과 LangSmith를 연계하면 실험의 전체 이력을 추적할 수 있습니다.

10-1. 왜 함께 써야 하는가

10-2. 커밋 hash를 LangSmith run에 기록하기

복사# src/llm/prompt_manager.py
import os
from langchain_core.prompts import ChatPromptTemplate

GIT_COMMIT = os.environ.get('GIT_COMMIT', 'unknown')

def get_system_prompt() -> str:
    """현재 Git 커밋과 연결된 프롬프트 반환"""
    with open('src/llm/prompts/system_prompt.txt') as f:
        return f.read().strip()

def run_with_tracking(user_input: str, llm) -> dict:
    """LangSmith에 Git 커밋 hash를 메타데이터로 기록"""
    prompt = ChatPromptTemplate.from_messages([
        ('system', get_system_prompt()),
        ('human', '{input}'),
    ])
    chain = prompt | llm
    # run_name에 커밋 hash 포함 → LangSmith에서 검색 가능
    return chain.invoke(
        {'input': user_input},
        config={
            'run_name': f'run-{GIT_COMMIT[:7]}',
            'metadata': {
                'git_commit': GIT_COMMIT,
                'prompt_version': 'v2.1',
            }
        }
    )

10-3. 커밋 메시지에 실험 결과 URL 기록

프롬프트를 변경할 때마다 커밋에 LangSmith 실험 결과를 기록하면, 나중에 "그 프롬프트가 왜 좋았는지"를 즉시 추적할 수 있습니다.

복사git switch -c feature/prompt-v2-korean
git add src/llm/prompts/system_prompt.txt
git commit -m "prompt: 시스템 프롬프트 v2 — 한국어 응답 품질 개선

변경 내용:
- 출력 형식을 '마크다운 → 평문'으로 변경
- Few-shot 예시 2개 추가 (AI 관련 Q&A)

실험 결과 (LangSmith):
- 이전: https://smith.langchain.com/runs/abc123
- 이후: https://smith.langchain.com/runs/def456
- 품질 점수: 3.2 → 4.1 (5점 척도)

Closes #22"

10-4. 실험 브랜치 전략 — experiment/*

프롬프트·모델 파라미터 실험은 experiment/* 브랜치에서 수행합니다. 결과가 좋으면 PR로 main에 반영하고, 아니면 브랜치째 삭제합니다.

복사git switch -c experiment/prompt-cot-few-shot
# 실험 중 자주 커밋 — 버전별 점수를 메시지에 남기기
git commit -m "experiment: CoT 프롬프트 v1 — LangSmith 결과 확인 필요"
git commit -m "experiment: CoT 프롬프트 v2 — few-shot 2개 추가"
git commit -m "experiment: CoT 프롬프트 v3 — 최종 (점수 4.3/5.0)"
# 결과가 좋으면 main에 PR
git push origin experiment/prompt-cot-few-shot
# 결과가 나쁘면 미련 없이 삭제
git switch main
git branch -D experiment/prompt-cot-few-shot

잘 관리된 GitHub 하나가, 자기소개서 10장보다 강합니다

AI 도입 이후 주니어 채용 시장은 빠르게 좁아지고 있습니다 — 채용 담당자들 사이에서 "GitHub 없으면 면접 없다"는 말이 나올 정도입니다. 그래도 기회는 있습니다. AI-native 스킬 + 실제 동작하는 프로젝트 포트폴리오를 가진 주니어는 오히려 수요가 늘고 있고, GitHub 생태계를 제대로 활용하는 것이 가장 확실한 차별화 전략입니다.

11-1. README 작성법 — 채용 담당자를 3분 안에 설득하기

채용 담당자는 GitHub에서 3분을 봅니다. README 첫 화면에서 무엇을·왜·어떻게가 보이면 클릭을 이어가고, 없으면 닫습니다.

README 7단계 구조 — 이 순서를 지키세요

복사# 📄 법률 문서 RAG 챗봇
계약서와 법률 문서에 대한 질문을 5초 안에 답변하는 AI 챗봇

![Python](https://img.shields.io/badge/Python-3.11-blue)
![FastAPI](https://img.shields.io/badge/FastAPI-0.110-green)
![LangChain](https://img.shields.io/badge/LangChain-0.2-orange)

복사## 🎬 데모
[![Demo](docs/demo.gif)](https://your-app.streamlit.app)
> 라이브 데모: https://your-app.streamlit.app

복사## ✨ 핵심 기능
- 📄 **PDF/Word 문서 업로드** → 자동 벡터 인덱싱 (ChromaDB)
- 💬 **자연어 질문** → 출처 인용과 함께 정확한 답변 생성
- 🔄 **대화 기록 유지** — 이전 질문 맥락을 이어서 답변

복사## 🛠 기술 스택
| 레이어 | 기술 |
|--------|------|
| Frontend | Streamlit |
| Backend | FastAPI, Python 3.11 |
| AI/LLM | LangChain, GPT-4o-mini |
| Vector DB | ChromaDB |
| Deploy | Streamlit Cloud |

복사## 🏗 아키텍처
```mermaid
graph LR
A[사용자] -->|질문| B[Streamlit UI]
B -->|API 호출| C[FastAPI 서버]
C -->|임베딩 검색| D[(ChromaDB)]
C -->|LLM 호출| E[GPT-4o-mini]
```

복사## 🚀 시작하기
git clone https://github.com/your-id/legal-rag-chatbot.git
cd legal-rag-chatbot
python -m venv .venv && source .venv/bin/activate
# Windows(Git Bash)는: source .venv/Scripts/activate
pip install -r requirements.txt
cp .env.example .env   # API 키 입력
streamlit run app.py

복사## 🗺 Roadmap
- [x] PDF 문서 RAG 구현
- [x] Streamlit Cloud 배포
- [ ] 한국어 임베딩 모델(KoSimCSE) 적용
- [ ] Docker 컨테이너화

README 감점 요소 5가지

11-2. GitHub Pages + MkDocs — 무료 포트폴리오 사이트

복사git clone git@github.com:아이디/아이디.github.io.git && cd 아이디.github.io
pip install mkdocs mkdocs-material
mkdocs new .   # docs/index.md + mkdocs.yml 생성

복사site_name: 홍길동 | AI Engineer
site_url: https://hong-gildong.github.io
theme:
  name: material
  features: [navigation.tabs, search.suggest]
nav:
  - Home: index.md
  - Projects:
      - RAG Chatbot: projects/rag-chatbot.md

복사# .github/workflows/deploy.yml
name: Deploy MkDocs
on:
  push:
    branches: [main]
permissions:
  contents: write   # gh-pages 브랜치 push 권한 — 없으면 신규 계정에서 403
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.11' }
      - run: pip install mkdocs mkdocs-material
      - run: mkdocs gh-deploy --force

11-3. 배포 연동 — Live Demo 링크가 채용 담당자 경험을 가릅니다

rag-chatbot/
├── app.py               ← 메인 파일 (루트에 있어야 함)
├── requirements.txt     ← pip freeze > requirements.txt 권장 (버전 고정)
├── .streamlit/secrets.toml  ← 로컬 API 키 (.gitignore 필수!)
└── src/

복사# app.py — Cloud에선 st.secrets, 로컬에선 .env로 fallback
import streamlit as st, os
def get_secret(key: str) -> str:
    try:
        return st.secrets['api_keys'][key]
    except (KeyError, FileNotFoundError):
        return os.getenv(key, '')

복사# FastAPI 백엔드(Render) 연결 시 CORS 설정 필수
from fastapi.middleware.cors import CORSMiddleware
app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        'https://내앱.vercel.app',   # Vercel 도메인
        'http://localhost:3000',       # 로컬 개발
    ],
    allow_methods=['*'], allow_headers=['*'],
)

복사# render.yaml — 루트에 두면 대시보드 클릭 없이 자동 설정
services:
  - type: web
    name: rag-api
    runtime: python
    plan: free            # 무료 (슬립 있음) / starter = $7/월
    region: singapore     # 한국에서 가장 가까운 리전
    buildCommand: pip install -r requirements.txt
    startCommand: uvicorn src.api.main:app --host 0.0.0.0 --port $PORT
    healthCheckPath: /health
    envVars:
      - key: OPENAI_API_KEY
        sync: false       # 대시보드에서 직접 입력

복사# /health 엔드포인트 — 상태 확인용
@app.get('/health')
def health_check():
    return {'status': 'ok', 'version': '1.0.0'}
# 배포 확인: https://rag-api.onrender.com/health → {status: ok}
# Swagger UI: https://rag-api.onrender.com/docs

11-4. 기술 문서화 — GitBook vs MkDocs

GitBook 연동 요약: Space 생성 → Integrations → GitHub → 레포·브랜치·Root path(docs/) 지정 → SUMMARY.md로 목차 구성 → push하면 사이트 자동 갱신 → Publish로 공개 URL 생성.

11-5. 오픈소스 기여 — 첫 PR을 날리기까지

복사# 1. 기여할 레포 우측 상단 'Fork' 클릭 → 내 계정에 복사본 생성
git clone git@github.com:내아이디/langchain.git && cd langchain
git remote add upstream git@github.com:langchain-ai/langchain.git
git fetch upstream && git checkout main && git merge upstream/main

복사git checkout -b fix/docs-typo-issue-1234   # 이슈 번호를 브랜치 이름에
git add docs/typo-fix.md
git commit -m 'docs: Fix typo in RAG tutorial (closes #1234)'
git push origin fix/docs-typo-issue-1234   # 내 Fork에 push

복사# PR 제목: docs: Fix typo 'retreival' → 'retrieval' in RAG guide
## 변경 사항
RAG 튜토리얼 문서에서 오타를 수정했습니다. `retreival` → `retrieval` (3곳)
## 관련 이슈
Closes #1234
## 체크리스트
- [x] 기존 테스트 통과 확인
- [x] 문서 변경만 포함 (코드 변경 없음)

AI 개발자에게 추천하는 기여 레포

한 번 GitHub에 올라간 키는 이미 유출된 것입니다

12-1. 올바른 환경변수 관리 — 3단계 체계

① .gitignore(Ch.2-5의 목록)로 추적 차단 → ② .env.example로 팀원에게 키 이름만 공유 → ③ 코드에서 환경변수로 읽기.

.env.example — 레포에 커밋 OK, 값은 비워둠

복사# .env.example
# LLM API Keys
OPENAI_API_KEY=your-openai-api-key-here
GROQ_API_KEY=your-groq-api-key-here
ANTHROPIC_API_KEY=your-anthropic-api-key-here
# LangSmith (실험 추적)
LANGCHAIN_API_KEY=your-langsmith-api-key-here
LANGCHAIN_PROJECT=ai-human-7th
LANGCHAIN_TRACING_V2=true
# 앱 설정
DEBUG=false
MAX_TOKENS=2000

# 팀원이 처음 세팅할 때: cp .env.example .env → 실제 키 입력

코드에서 읽는 올바른 패턴

복사# ❌ 절대 이렇게 하지 말 것
openai_key = 'sk-proj-abc123...'   # 하드코딩

# ✅ 방법 1 — python-dotenv
from dotenv import load_dotenv
import os
load_dotenv()
openai_key = os.getenv('OPENAI_API_KEY')
if not openai_key:
    raise ValueError('OPENAI_API_KEY가 설정되지 않았습니다')

# ✅ 방법 2 — pydantic-settings (권장)
from pydantic_settings import BaseSettings
class Settings(BaseSettings):
    openai_api_key: str
    groq_api_key: str = ''    # 선택적
    debug: bool = False
    class Config:
        env_file = '.env'
settings = Settings()

12-2. 저장소 공개/비공개 전략

12-3. 이미 .env를 올렸다면 — 긴급 복구 3 STEP

복사echo '.env' >> .gitignore
git rm --cached .env         # 추적만 제거, 로컬 파일은 유지
git add .gitignore
git commit -m 'fix: .env 파일 Git 추적 제거 및 .gitignore 추가'
git push

복사pip install git-filter-repo
git filter-repo --path .env --invert-paths --force
git push origin --force --all   # 팀원 전체 동기화 필요 — 팀과 합의 후 실행
# 완료 확인: GitHub 레포에서 파일 검색 → 이력에서 안 나오면 완료
# 이후 팀원은 레포를 새로 clone해야 합니다

Lv.2에서 Lv.4까지 — 이 순서만 따라가세요

주차별 도입 로드맵 (12주)

최종 체크리스트 — 수료 전 점검 10항목

첫 주 세팅 체크리스트 — 수업 시작 전

이 핸드북은 팀 프로젝트와 포트폴리오를 완성하는 여정의 안내서입니다. 막힐 때마다 다시 펼쳐 보세요.