GitHub Spec Kit 완벽 가이드: Spec-Driven Development로 개발 효율성 극대화하기
GitHub에서 공개한 Spec Kit의 개념과 사용법을 완벽하게 정리했습니다. 명세 기반 개발(Spec-Driven Development)로 AI 코딩 에이전트를 활용하여 프로젝트의 생산성을 높이는 방법을 알아봅니다.
Git은 현대 소프트웨어 개발의 필수 도구입니다. 하지만 단순히 Git 명령어를 아는 것과, 팀과 효과적으로 협업하는 것은 완전히 다른 이야기입니다.
잘못된 Git 워크플로우는:
반면, 체계적인 Git 워크플로우는:
이 글에서는 실무에서 바로 적용할 수 있는 Git 워크플로우 전략을 상세히 알아보겠습니다.
Git Flow는 Vincent Driessen이 제안한 가장 널리 사용되는 브랜치 전략입니다.
main (프로덕션)
↑
develop (개발 통합)
↑
feature/* (기능 개발)
hotfix/* (긴급 수정)
release/* (릴리스 준비)
main (master)
develop
feature/*
feature/user-authentication, feature/payment-integrationrelease/*
release/1.2.0hotfix/*
hotfix/critical-security-patch# 1. 새 기능 개발 시작
git checkout develop
git pull origin develop
git checkout -b feature/user-profile
# 2. 개발 및 커밋
git add .
git commit -m "feat: Add user profile page"
git push origin feature/user-profile
# 3. PR 생성 후 리뷰 및 머지
# develop으로 머지 완료
# 4. 릴리스 준비
git checkout develop
git pull origin develop
git checkout -b release/1.2.0
# 5. 버그 수정 및 테스트
git commit -m "fix: Resolve profile image loading issue"
# 6. 릴리스 배포
git checkout main
git merge release/1.2.0
git tag -a v1.2.0 -m "Release version 1.2.0"
git push origin main --tags
# develop에도 병합
git checkout develop
git merge release/1.2.0
git push origin develop
# 7. 릴리스 브랜치 삭제
git branch -d release/1.2.0
장점:
단점:
적합한 프로젝트:
GitHub Flow는 Git Flow를 단순화한 전략으로, GitHub에서 사용하고 권장하는 방식입니다.
main (프로덕션)
↑
feature/* (기능 개발)
단 두 종류의 브랜치만 사용합니다!
# 1. 최신 main 가져오기
git checkout main
git pull origin main
# 2. 새 브랜치 생성
git checkout -b add-search-functionality
# 3. 작업 및 커밋 (자주 푸시)
git add src/search.js
git commit -m "feat: Add basic search functionality"
git push origin add-search-functionality
# 더 작업...
git add src/search.js src/search.test.js
git commit -m "feat: Add search tests and optimize query"
git push origin add-search-functionality
# 4. GitHub에서 PR 생성
# 5. 코드 리뷰 진행
# 6. CI 테스트 통과 확인
# 7. main에 병합 (Squash or Merge)
# 8. 자동 배포 (CD 파이프라인)
# 9. 로컬에서 정리
git checkout main
git pull origin main
git branch -d add-search-functionality
장점:
단점:
적합한 프로젝트:
GitLab Flow는 환경별 브랜치를 두어 두 전략의 장점을 결합했습니다.
main (개발)
↑
feature/* (기능 개발)
↓
production (프로덕션)
pre-production (스테이징)
# 기능 개발
git checkout -b feature/new-dashboard main
# ... 개발 ...
git push origin feature/new-dashboard
# PR to main
# main에서 staging으로
git checkout staging
git merge main
git push origin staging
# 스테이징 환경 배포 및 테스트
# staging에서 production으로
git checkout production
git merge staging
git push origin production
# 프로덕션 배포
일관된 커밋 메시지는 코드 이력을 이해하기 쉽게 만듭니다.
가장 널리 사용되는 커밋 메시지 형식입니다.
<type>(<scope>): <subject>
<body>
<footer>
feat: 새로운 기능 추가
fix: 버그 수정
docs: 문서 변경
style: 코드 포맷팅 (세미콜론, 들여�기 등)
refactor: 코드 리팩토링
test: 테스트 코드 추가/수정
chore: 빌드 프로세스, 도구 설정 변경
perf: 성능 개선
ci: CI 설정 변경
좋은 커밋 메시지:
# 기본
git commit -m "feat: Add user authentication"
# 스코프 포함
git commit -m "fix(auth): Resolve token expiration issue"
# 상세 설명 포함
git commit -m "feat(payment): Integrate Stripe payment gateway
- Add Stripe SDK configuration
- Implement payment processing flow
- Add webhook handler for payment events
- Update user subscription status
Closes #123"
# Breaking Change
git commit -m "feat!: Change API response format
BREAKING CHANGE: API now returns data in { data, meta } format
instead of flat structure. Update all API clients accordingly."
나쁜 커밋 메시지:
❌ git commit -m "update"
❌ git commit -m "fix bug"
❌ git commit -m "WIP"
❌ git commit -m "asdf"
❌ git commit -m "Update index.js"
[Type] Short description of changes
예시:
[Feature] Add user profile editing
[Fix] Resolve memory leak in data fetching
[Refactor] Simplify authentication logic
## 변경 사항
- 사용자 프로필 편집 기능 추가
- 프로필 이미지 업로드 지원
- 입력 유효성 검증 추가
## 변경 이유
사용자가 프로필 정보를 직접 수정할 수 있도록 하여 UX 개선
## 테스트 방법
1. /profile 페이지 접속
2. "편집" 버튼 클릭
3. 정보 수정 후 저장
4. 변경사항이 즉시 반영되는지 확인
## 스크린샷
(이미지 첨부)
## 체크리스트
- [x] 로컬에서 테스트 완료
- [x] 단위 테스트 추가
- [x] 문서 업데이트
- [x] Breaking change 없음
- [x] 코드 리뷰 준비 완료
## 관련 이슈
Closes #456
Related to #123
작은 PR이 좋은 PR입니다!
✅ 좋은 PR 크기: +200/-150 lines
⚠️ 보통 PR 크기: +500/-300 lines
❌ 나쁜 PR 크기: +2000/-1500 lines
큰 PR을 작게 나누는 방법:
# Before: 거대한 하나의 PR
feature/user-management (+2000 lines)
# After: 작은 여러 개의 PR
feature/user-model (+200 lines)
feature/user-api (+300 lines)
feature/user-ui (+250 lines)
feature/user-tests (+150 lines)
기능 및 로직
코드 품질
테스트
보안
건설적인 피드백:
✅ "이 부분에서 null 체크를 추가하면 더 안전할 것 같습니다.
예: if (user?.profile) { ... }"
✅ "성능을 위해 이 배열 순회를 Map으로 바꾸는 건 어떨까요?
O(n) -> O(1)로 개선될 것 같습니다."
✅ "좋은 해결책이네요! 다만 이 케이스도 고려해주세요:
사용자가 동시에 여러 요청을 보낼 때..."
피해야 할 코멘트:
❌ "이건 왜 이렇게 작성했나요?" (비판적)
❌ "이해가 안 되네요" (불명확)
❌ "다시 하세요" (무례함)
❌ "제 방식대로 하세요" (강압적)
# 현재 상태 확인
git status
git log --oneline --graph --all
# 변경사항 확인
git diff
git diff --staged
git diff main..feature/branch
# 커밋 수정
git commit --amend
git commit --amend --no-edit
# 브랜치 관리
git branch -a # 모든 브랜치 보기
git branch -d feature/old # 로컬 브랜치 삭제
git push origin --delete feature/old # 원격 브랜치 삭제
# Stash 활용
git stash # 변경사항 임시 저장
git stash list # stash 목록
git stash pop # 최근 stash 적용 및 삭제
git stash apply stash@{0} # 특정 stash 적용
# 리베이스
git rebase main # main 기반으로 리베이스
git rebase -i HEAD~3 # 최근 3개 커밋 대화형 리베이스
# 체리픽
git cherry-pick abc123 # 특정 커밋만 가져오기
# 특정 파일 변경 이력 보기
git log -p -- path/to/file
# 누가 언제 수정했는지 보기
git blame path/to/file
# 버그를 일으킨 커밋 찾기 (이진 탐색)
git bisect start
git bisect bad # 현재가 버그 있음
git bisect good abc123 # 이 커밋은 정상이었음
# ... 자동으로 중간 커밋들을 테스트하며 찾아감
# 리팩토링 시 유용: 파일 이동 추적
git log --follow -- path/to/file
# 커밋 되돌리기 (히스토리 유지)
git revert abc123
# 커밋 취소 (히스토리 삭제)
git reset --soft HEAD~1 # 커밋만 취소, 변경사항 유지
git reset --hard HEAD~1 # 커밋과 변경사항 모두 삭제 (위험!)
# 원격 브랜치를 로컬로 가져오기
git fetch origin
git checkout -b feature/new origin/feature/new
# 시나리오: 같은 파일의 같은 라인을 두 사람이 수정
# User A
git checkout -b feature/a
# file.js 3번 라인 수정
git commit -m "feat: Update greeting message"
# User B
git checkout -b feature/b
# file.js 3번 라인 수정 (다른 내용)
git commit -m "feat: Add localization support"
# User A가 먼저 main에 병합
# User B가 병합 시도하면 Conflict 발생!
# Pull 또는 merge 시 conflict 발생
git pull origin main
# Auto-merging file.js
# CONFLICT (content): Merge conflict in file.js
# file.js 파일 확인
<<<<<<< HEAD (현재 브랜치)
console.log('Hello, World!');
=======
console.log('안녕하세요!');
>>>>>>> feature/b (병합하려는 브랜치)
# 수동으로 수정
console.log('Hello, World! 안녕하세요!');
# 해결 후 커밋
git add file.js
git commit -m "resolve: Merge conflict in greeting message"
# Rebase 시 conflict 발생
git rebase main
# Conflict 해결 후
git add file.js
git rebase --continue
# 너무 복잡하면 중단
git rebase --abort
# 1. 자주 pull 받기
git pull origin main # 매일 아침
# 2. 작은 단위로 자주 커밋
# 큰 변경사항보다 작은 변경사항이 conflict 적음
# 3. 브랜치 수명 짧게 유지
# 오래된 브랜치일수록 conflict 발생률 높음
# 4. 팀원과 작업 영역 조율
# 같은 파일을 동시에 수정하지 않도록
# VS Code, IntelliJ 등에서 제공하는 Merge Tool 활용
git mergetool
# 외부 도구 설정
git config --global merge.tool vscode
git config --global mergetool.vscode.cmd 'code --wait $MERGED'
# .gitignore 예시
# 의존성
node_modules/
venv/
vendor/
# 환경 변수 및 비밀 정보
.env
.env.local
*.key
*.pem
config/secrets.json
# 빌드 산출물
dist/
build/
*.min.js
*.min.css
# IDE 설정
.vscode/
.idea/
*.swp
*.swo
# OS 파일
.DS_Store
Thumbs.db
# 로그
*.log
logs/
# 캐시
.cache/
*.pyc
__pycache__/
# 테스트 커버리지
coverage/
.nyc_output/
# 특정 파일을 Git에서 제거 (로컬 파일은 유지)
git rm --cached .env
git commit -m "chore: Remove .env from git tracking"
# .gitignore에 추가
echo ".env" >> .gitignore
git add .gitignore
git commit -m "chore: Add .env to .gitignore"
# 이미 커밋된 민감한 정보는 history에서 완전 삭제 필요
# BFG Repo-Cleaner 사용 권장
커밋 전에 자동으로 검사를 실행합니다.
# .git/hooks/pre-commit (실행 권한 필요)
#!/bin/sh
# 린터 실행
npm run lint
if [ $? -ne 0 ]; then
echo "❌ Lint 검사 실패! 커밋을 중단합니다."
exit 1
fi
# 테스트 실행
npm test
if [ $? -ne 0 ]; then
echo "❌ 테스트 실패! 커밋을 중단합니다."
exit 1
fi
echo "✅ 모든 검사를 통과했습니다!"
exit 0
# Husky 설치
npm install --save-dev husky
# Husky 초기화
npx husky install
# pre-commit hook 추가
npx husky add .husky/pre-commit "npm run lint && npm test"
# package.json에 추가
{
"scripts": {
"prepare": "husky install"
}
}
# .husky/commit-msg
#!/bin/sh
# Conventional Commits 형식 검사
commit_msg=$(cat "$1")
pattern="^(feat|fix|docs|style|refactor|test|chore)(\(.+\))?: .{1,50}"
if ! echo "$commit_msg" | grep -qE "$pattern"; then
echo "❌ 커밋 메시지 형식이 올바르지 않습니다!"
echo "올바른 형식: type(scope): subject"
echo "예: feat(auth): Add login functionality"
exit 1
fi
# 1. 이슈 생성 (GitHub/Jira)
# Issue #123: 사용자 알림 기능 추가
# 2. 브랜치 생성
git checkout main
git pull origin main
git checkout -b feature/user-notifications
# 3. 개발
# ... 코딩 ...
# 4. 테스트 작성 및 실행
npm test
# 5. 커밋
git add .
git commit -m "feat(notifications): Add user notification system
- Implement real-time notification service
- Add notification UI component
- Integrate with WebSocket
- Add notification preferences
Closes #123"
# 6. 푸시 및 PR 생성
git push origin feature/user-notifications
# GitHub에서 PR 생성
# 7. 코드 리뷰
# 팀원들의 리뷰 및 승인 대기
# 8. CI 테스트 통과 확인
# GitHub Actions, Jenkins 등
# 9. Main에 병합
# Squash and merge 또는 Merge commit
# 10. 배포
# CD 파이프라인 자동 배포 또는 수동 배포
# 11. 브랜치 정리
git checkout main
git pull origin main
git branch -d feature/user-notifications
# 1. 프로덕션에서 Critical 버그 발견!
# 결제 시스템 오류
# 2. Hotfix 브랜치 생성
git checkout main
git pull origin main
git checkout -b hotfix/payment-error
# 3. 빠른 수정
# ... 버그 수정 ...
# 4. 테스트
npm test
# 5. 커밋
git commit -m "fix(payment): Resolve payment processing timeout
- Increase timeout from 5s to 30s
- Add retry logic for failed payments
- Add error logging
Critical fix for production issue"
# 6. 긴급 배포 프로세스
git push origin hotfix/payment-error
# 즉시 리뷰 및 병합
# 프로덕션 배포
# 7. Develop에도 반영
git checkout develop
git merge hotfix/payment-error
git push origin develop
# 개발자 A: UI 작업
git checkout -b feature/dashboard-ui
# 개발자 B: API 작업
git checkout -b feature/dashboard-api
# 개발자 A가 먼저 병합
# PR 생성 → 리뷰 → 병합
# 개발자 B는 A의 변경사항을 반영
git checkout feature/dashboard-api
git pull origin main
git rebase main
# Conflict 해결
git push origin feature/dashboard-api --force-with-lease
# PR 생성 → 리뷰 → 병합
# 최근 3개 커밋을 하나로 합치기
git rebase -i HEAD~3
# 에디터에서 pick을 squash로 변경
pick abc123 feat: Add feature A
squash def456 fix: Fix typo
squash ghi789 refactor: Clean code
# 푸시 (주의: 이미 푸시된 커밋을 수정할 때)
git push origin feature/branch --force-with-lease
# main에 실수로 커밋함
git checkout main
git log # 마지막 커밋 해시 확인: abc123
# 새 브랜치로 커밋 옮기기
git checkout -b feature/correct-branch
git cherry-pick abc123
# main에서 커밋 제거
git checkout main
git reset --hard HEAD~1
# ❌ 위험: 다른 사람의 작업을 덮어씀
git push --force
# ✅ 안전: 원격에 새 커밋이 있으면 실패
git push --force-with-lease
# Git LFS (Large File Storage) 사용
git lfs install
git lfs track "*.psd"
git lfs track "*.mp4"
git add .gitattributes
git add large-file.psd
git commit -m "chore: Add large design file"
브랜치 전략
커밋 관리
코드 리뷰
자동화
문서화
Git 워크플로우를 마스터했다면:
효과적인 Git 워크플로우는 팀의 생산성을 극대화하고, 안정적인 소프트웨어 개발을 가능하게 합니다. 오늘 배운 내용을 팀에 적용하여 더 나은 협업 문화를 만들어보세요!
Happy Coding! 🎉