git-workflow-guidelines

name	git-workflow-guidelines
description	Git 브랜치 전략·커밋 컨벤션·머지 정책 가이드라인. Conventional Commits, GitFlow vs Trunk-based vs Feature Branch 선택 기준, 브랜치 네이밍 규칙(Jira 이슈 키 연계), 리베이스 vs 머지 vs squash 전략, destructive 작업 안전 가이드(force-push/reset/branch 삭제). git 에이전트(git-workflow-expert)가 실행 시 참조하는 SSOT.
triggers	["git","깃","conventional commit","feature branch","rebase","리베이스","merge","머지","commit message","커밋 메시지","branch","브랜치","squash"]

Git Workflow Guidelines

팀 협업 기반 Git 운영 표준. 에이전트(git-workflow-expert, pr-manager, release-manager)가 실행 시 이 가이드라인을 참조.

---

🔧 Pipeline(공통) vs Config(프로젝트별) 분리

핵심 원칙: 작업 절차는 모든 프로젝트에서 동일. 다른 것은 설정값뿐.

구분	내용	프로젝트마다 다름?	관리 방식
Pipeline (공통)	브랜치 생성 → 커밋(컨벤션 검증) → 푸시 → PR → 리뷰 → 머지 → 태그 → 릴리즈	❌ 동일 (skill 본문)	이 SKILL.md
Config (프로젝트별)	base_branch, 브랜치 전략, 네이밍 패턴, valid_types, issue tracker 연계, 머지 정책, destructive 게이트 레벨	✅ 항상 다름	.claude/config/git.yaml
Data (팀별)	기존 브랜치 목록, 커밋 이력	✅ 시간에 따라 변함	git 자체가 관리

시사점: 에이전트는 .claude/config/git.yaml 부재 시 Bootstrap 와이자드로 자동 생성 (§Bootstrap 참조).

---

🚀 Bootstrap — 첫 실행 초기 세팅 (Agent 필수 동작)

트리거 조건: .claude/config/git.yaml 부재.

7단계 요약 (상세 명령은 resources/bootstrap.md 참조)

Step	내용	결정 결과
1	git repo 검증 (git rev-parse, remote -v)	레포/원격 확인
2	base branch 자동 감지 (symbolic-ref → ls-remote → branch --show-current)	base_branch
3	최근 50 커밋 Conventional Commits 준수율 분석	commit.conventional (strict/warn/off)
4	원격 브랜치 네이밍 prefix 집계	types_allowed 초기값
5	사용자 질문 4건 (전략/Tracker/머지 정책/main 보호)	설정 확정
6	.claude/config/git.yaml 생성 (아래 템플릿)	파일 생성
7	YAML 파싱·base_branch 존재·strategy 유효성 검증	Bootstrap 완료

핵심 자동 감지 규칙:

• Step 3 판정: 준수율 ≥80% → strict / 40~80% → warn / <40% → off / 커밋 없음 → strict (신규)
• Step 5 Q2 체이닝: issue_tracker.type = jira 선택 시 jira-workflow-guidelines Bootstrap 자동 호출
• Idempotency: git.yaml 존재 시 skip (덮어쓰기는 --force 또는 "재세팅" 명시 시에만, .bak 백업 생성)

생성 템플릿:

# .claude/config/git.yaml
# Generated by git-workflow-expert bootstrap on <date>

# ─── Step 2: base branch ───
base_branch: main                 # 브랜치 생성 기준 + PR 타겟

# ─── Step 5: 전략 ───
strategy: github-flow             # github-flow | gitflow | trunk-based | feature-branch

# ─── Step 3·4: 커밋·브랜치 규칙 ───
commit:
  conventional: strict            # strict | warn | off (Step 3에서 자동 판정)
  max_subject_length: 72
  require_scope: false
  require_issue_key: false        # Jira 사용 시 true 권장

branch_naming:
  pattern: "{type}/{short-desc}"  # 또는 {type}/{domain}/{short}-{ISSUE-KEY}
  types_allowed:
    - feat
    - fix
    - refactor
    - perf
    - docs
    - style
    - test
    - chore
    - env
    - hotfix

# ─── Step 5: Issue Tracker ───
issue_tracker:
  type: jira                      # jira | github | none
  smart_commit: true              # Jira smart commits (fix/close/#time)
  key_pattern: "[A-Z]+-\\d+"      # PROJ-123 형식

# ─── Step 5: 머지 정책 ───
merge_policy:
  default: squash                 # squash | merge | rebase
  main_protected: true            # main에 직접 push/force-push 차단
  require_linear_history: false

# ─── Destructive 게이트 레벨 ───
destructive_gates:
  force_push: require_confirmation       # require_confirmation | block
  reset_hard: require_confirmation
  branch_delete: require_confirmation
  clean_fd: block                        # 복구 불가 → 무조건 차단

# ─── Pre-commit 권고 (프로젝트별 선택) ───
pre_commit_hooks:
  recommended:
    - commitlint
    - detect-secrets
  enforced: []                    # 팀 합의 후 추가

Step 7 — 시험 호출

에이전트가 .claude/config/git.yaml 유효성 검증:

• base_branch 실제 존재?
• strategy 허용값?
• YAML 파싱 OK?

통과 시 Bootstrap 완료, 원래 요청 처리.

---

1. 브랜치 전략 선택

프로젝트 규모·배포 주기·팀 크기에 따라 선택.

전략	주 브랜치	보조 브랜치	적합 상황	배포 주기
Trunk-based	main	단명 feature (≤2일)	소규모 팀 / CI/CD 성숙 / 주기적 배포	일 1회 이상
GitHub Flow	main	feature/*	중소 팀 / 웹 서비스	수시 (PR 머지 시)
GitFlow	main + develop	feature/* + release/* + hotfix/*	중대형 팀 / 릴리즈 버전 관리 필요	정기 (sprint 단위)
Feature Branch	main	feature/* + hotfix/*	일반 스타트업	PR 머지 시

선택 의사결정 트리

릴리즈 버전을 명시적으로 관리하나? (v1.0, v1.1 등)
├─ YES → GitFlow
└─ NO
   └─ CI/CD 파이프라인이 성숙하고 feature flag 사용하나?
      ├─ YES → Trunk-based
      └─ NO → GitHub Flow (또는 Feature Branch)

---

2. 브랜치 네이밍 규칙

기본 원칙

규칙	준수	이유
소문자만	✅ 필수	일부 FS case-insensitive 충돌 방지
하이픈 구분	✅ 필수	언더스코어·공백 금지
한글 금지	✅ 필수	터미널·CI 도구 호환성
이슈 키 포함	🟡 권장	Jira/GitHub 연계 추적
60자 이하	🟡 권장	디스플레이 가독성

네이밍 패턴 (3가지)

패턴	예시	적합 상황
{type}/{short-desc}	feat/login-form	Jira 미사용 / 간단 프로젝트
{type}/{domain}/{short}-{ISSUE-KEY}	feat/ai/short-PROJ-209	도메인 분리 + Jira 연계
{type}/{ISSUE-KEY}-{short-desc}	feat/PROJ-209-login-form	Jira 필수 연계

Type 화이트리스트

feat       : 새 기능 추가
fix        : 버그 수정
refactor   : 기능 변경 없는 리팩터링
perf       : 성능 개선
docs       : 문서만 변경
style      : 포매팅·세미콜론 등 (동작 무변화)
test       : 테스트 추가/수정
chore      : 빌드·의존성·CI 설정
env        : 환경설정 변경
plan       : 계획/설계 문서
design     : UI/UX 디자인 작업
hotfix     : 프로덕션 긴급 패치
release    : 릴리즈 브랜치

검증 정규식

^(feat|fix|refactor|perf|docs|style|test|chore|env|plan|design|hotfix|release)/[a-z0-9][a-z0-9\-\/]*[a-z0-9]$

---

3. Conventional Commits

형식

<type>(<scope>): <subject>

<body (optional)>

<footer (optional)>

규칙

요소	규칙	예시
type	위 화이트리스트 11종	feat, fix
scope (선택)	영향 영역, 소문자	(auth), (api), (ui)
subject	현재형 동사, 50자 이하, 마침표 X	add login endpoint
body	왜(why) 중심, 72자 줄바꿈	변경 동기·배경
footer	Breaking Change 표시, 이슈 참조	BREAKING CHANGE: ..., Refs: PROJ-209

예시 모음

# 좋은 예시
feat(auth): add JWT refresh token rotation
fix(api): handle 401 on expired access token
refactor(db): extract repository from service layer
docs: update README with Docker setup
chore(deps): bump fastapi to 0.110.0

# Breaking Change
feat(api)!: rename /users endpoint to /members

BREAKING CHANGE: /users endpoint removed, use /members.
Migration: update frontend API client to new path.

Refs: PROJ-209

# Jira 키 연계
fix(ui): correct button hover state

Refs: PROJ-308

안티패턴

❌ "fix bug"              → 무엇을 고쳤는지 불명
❌ "WIP"                  → 머지 전 squash 필요
❌ "updated login.py"     → 파일명 나열 금지
❌ "Fixed login bug."     → 과거형 + 마침표
❌ "Add Login Feature"    → Title Case 금지
✅ "fix(auth): handle null user on expired session"

---

4. 머지 전략 (Rebase vs Merge vs Squash)

상황별 선택

전략	히스토리	적합 상황
Merge Commit	Non-linear (공식 머지 이력 보존)	큰 기능 브랜치 / release → main
Rebase	Linear (깔끔)	로컬 feature 브랜치 최신화 / 공유 전
Squash Merge	Linear + 1 커밋	소규모 feature → main / WIP 커밋 정리
Fast-forward Only	Linear (강제)	hotfix

의사결정 매트릭스

PR이 2 커밋 이하 + 관련 기능 1개?
├─ YES → Squash Merge
└─ NO
   └─ 공식 머지 이력이 필요한가? (release, versioned feature)
      ├─ YES → Merge Commit
      └─ NO → Rebase

안전 규칙 (Rebase 위험 회피)

⚠️ 원격에 이미 push된 커밋을 rebase하면 force-push 필요 → 협업자 히스토리 깨짐

✅ 로컬에만 있는 커밋만 rebase
✅ 혼자 쓰는 feature 브랜치만 rebase
❌ 공유 브랜치(main, develop, 다른 팀원과 공유 중)는 rebase 금지
❌ 이미 PR 올라간 브랜치는 rebase 대신 merge 사용

---

5. Destructive 작업 — 확인 게이트 필수

다음 작업들은 실행 전 반드시 사용자 확인하고, 영향 범위·롤백 가능 여부를 명시해야 함.

작업	영향	롤백 가능?
git push --force	원격 히스토리 덮어쓰기	⚠️ 협업자가 pull 전이면 가능
git push --force-with-lease	조건부 덮어쓰기	같음 (권장)
git reset --hard HEAD~N	로컬 커밋 N개 삭제	⚠️ reflog로 24시간 복구
git branch -D <branch>	브랜치 강제 삭제	⚠️ reflog로 복구
git clean -fd	추적되지 않는 파일 삭제	❌ 복구 불가
git checkout -- .	모든 unstaged 변경 폐기	❌ 복구 불가
git rebase --onto	커밋 재배치	⚠️ reflog 복구

확인 게이트 템플릿

🛑 Destructive 작업 확인:
─────────────────────────
작업: <git command>
영향 범위: <구체적 영향>
롤백 가능 여부: <reflog 24h / 협업자 pull 전까지 / 복구 불가>
─────────────────────────
진행하시겠습니까? (OK / NO)

절대 금지 (사용자 명시 요청이 있어도 재확인)

• main / master / develop / dev 브랜치에 직접 force-push
• git push --force (--force-with-lease 사용 권장)
• 공유 브랜치 rebase

---

6. 이슈 트래커 연계 (Jira / GitHub Issue)

커밋 메시지 패턴

# 커밋마다 이슈 키 (footer)
feat(auth): add JWT refresh

Refs: PROJ-209

# 1 커밋 = 1 이슈 key 원칙
# 여러 이슈 관련 시 개별 커밋 분리 권장

브랜치 ↔ 이슈 양방 추적

방향	패턴
브랜치명 → 이슈	feat/ai/short-PROJ-209 → 자동 파싱
이슈 → 브랜치	Jira Development 패널에 자동 표시 (smart commit 연동 시)
PR 제목	feat(auth): add JWT refresh (PROJ-209)

Smart Commit 키워드 (Jira)

fix PROJ-209           → 상태 "Resolved"로 전이
close PROJ-209         → 상태 "Closed"로 전이
#time 2h PROJ-209      → Time tracking 2시간 기록
#comment <텍스트>       → Jira에 코멘트 자동 추가

⚠️ Smart Commit은 Jira 인스턴스 설정에 따라 동작 차이. 팀 컨벤션 확인 후 사용.

---

7. Pre-commit 훅 권고 항목

검사	도구 예시	목적
커밋 메시지 Conventional 준수	commitlint / commit-msg hook	포맷 강제
브랜치명 규칙	custom pre-push hook	원격 push 차단
대용량 파일 차단 (>10MB)	pre-commit (check-added-large-files)	레포 비대화 방지
시크릿 탐지	detect-secrets / gitleaks	자격증명 누출 방지
린터·포매터	ruff / black / eslint / prettier	코드 품질

---

8. 일상 작업 패턴

새 기능 착수 (Feature Branch 전략)

# 1. 최신화
git checkout main
git pull origin main

# 2. 브랜치 생성
git checkout -b feat/auth/jwt-refresh-PROJ-209

# 3. 작업 중 커밋 (Conventional Commits)
git add backend/auth/jwt.py
git commit -m "feat(auth): add JWT refresh token rotation

Refs: PROJ-209"

# 4. 원격 push
git push -u origin feat/auth/jwt-refresh-PROJ-209

# 5. PR 생성 (→ pr-manager 에이전트)

로컬 커밋 정리 (Interactive Rebase)

# 마지막 3 커밋 squash
git rebase -i HEAD~3

# 편집기에서:
# pick abc123 feat: initial
# squash def456 wip
# squash ghi789 wip
# → 하나의 커밋으로 합침

Conflict 해결

# main 기준 최신화
git checkout feat/xxx
git fetch origin
git rebase origin/main

# 충돌 발생 시
# 1. 파일 편집으로 해결
# 2. git add <해결한 파일>
# 3. git rebase --continue

# 포기 (안전)
git rebase --abort

긴급 되돌리기 (reflog)

# 방금 한 실수 복구
git reflog                      # HEAD 이력 확인
git reset --hard HEAD@{3}       # 3단계 전 상태로

# 삭제한 브랜치 복구
git reflog | grep <branch-name>
git checkout -b <branch-name> <commit-hash>

---

9. Claude Agent 실행 가이드

git-workflow-expert 호출 시

에이전트가 이 guideline을 읽고 아래 규칙을 적용:

• Conventional Commits 자동 생성 — 변경 파일 분석 후 type + scope + subject 제안
• 브랜치명 검증 — §2 정규식으로 사용자 입력 검증
• Destructive 작업 게이트 — §5 템플릿으로 확인 유도
• Rebase 안전성 체크 — git log --remotes --contains <sha> 로 원격 push 여부 확인

pr-manager 호출 시

• PR 제목에 이슈 키 포함 (§6)
• 머지 전략 결정 (§4)
• Conventional Commits 준수 검증

release-manager 호출 시

• semver 결정 근거: 커밋 type 통계 (feat → minor, fix → patch, Breaking → major)
• CHANGELOG 자동 생성: Conventional Commits body 기반

---

10. 안티패턴 요약

❌ 안티패턴	✅ 대안
main에 직접 커밋	feature 브랜치 + PR
"WIP" 커밋 그대로 머지	squash merge 또는 interactive rebase로 정리
공유 브랜치 rebase	merge 사용
git push --force (무조건)	--force-with-lease + 사전 확인
1 커밋에 여러 기능	커밋 분리 (원자성 원칙)
브랜치명에 한글·대문자	소문자 + 하이픈 + 영문
커밋 메시지 "fix bug"	Conventional Commits 준수
Long-lived feature branch (>1주)	잘게 쪼개서 더 자주 merge

---

외부 참조

• Conventional Commits: https://www.conventionalcommits.org/
• GitFlow: https://nvie.com/posts/a-successful-git-branching-model/
• Trunk-based Development: https://trunkbaseddevelopment.com/
• Jira Smart Commits: https://support.atlassian.com/jira-software-cloud/docs/process-issues-with-smart-commits/

---

변경 이력

일자	변경
2026-04-24	하네스 v1 — Phase 15-A 협업 트랙. Jira 연계 섹션 포함