# [[Feature-Branch Workflow]]

## 📌 Brief Summary
`Feature-Branch Workflow`는 메인 브랜치(main/master)를 항상 안정적이고 배포 가능한 상태로 유지하며, 새로운 기능 개발 및 버그 수정 등의 모든 작업을 짧은 수명을 가진 독립적인 피처 브랜치(feature branch)에서 수행하는 버전 관리 협업 방식이다 [1-4]. 개발이 완료된 변경 사항은 풀 리퀘스트(Pull Request)를 통해 코드 리뷰와 테스트를 거친 후 메인 브랜치로 병합된다 [5-7]. 이 워크플로우는 소규모 팀에 매우 적합하며, 코드 충돌을 방지하고 품질을 유지하면서도 Git-Flow와 같은 무거운 프로세스의 오버헤드를 피할 수 있게 해준다 [1, 8, 9].

## 📖 Core Content
- **기본 구조 및 원칙:** 
  항상 배포 가능한 상태인 `main` 브랜치를 중심으로 작동한다 [2-4]. 개발자는 새로운 작업(기능 추가, 버그 수정 등)을 시작할 때마다 `main`에서 새로운 브랜치를 생성하며, `main` 브랜치에 직접 커밋(Direct push)하는 것은 엄격히 금지된다 [4, 5, 10].
- **브랜치 명명 규칙 (Naming Conventions):** 
  브랜치의 목적을 명확히 알 수 있도록 짧고 서술적인 이름을 사용한다. 구조적 관리를 위해 접두사(`feature/`, `bugfix/`, `chore/` 등)를 사용하며 [6, 11, 12], 추적성을 높이기 위해 JIRA나 GitHub의 티켓 ID를 포함하는 것이 권장된다 (예: `feature/PROJ-123-user-auth`, `bugfix/GH-456-login-fix`) [13, 14]. 
- **커밋 및 통합 (Commits & Merging):** 
  한 번에 하나의 논리적 변경사항만 커밋하는 원자적 커밋(Atomic Commits)을 지향하며, 커밋을 작고 빈번하게 수행한다 [6, 11, 15]. 기능 구현이 완료되면 풀 리퀘스트(PR)를 열어 최소 1명 이상의 팀원에게 리뷰를 받아야 하며, CI 테스트 통과 후 병합한다 [4-7]. 커밋 히스토리를 깔끔하게 유지하기 위해 '스쿼시 병합(Squash Merge)' 방식을 주로 사용하며, 병합 완료 후 피처 브랜치는 즉시 삭제한다 [5, 7, 16].
- **충돌 방지 (Conflict Prevention):** 
  대규모 병합 충돌을 피하기 위해 작업 중인 피처 브랜치에 `main` 브랜치의 최신 변경 사항을 자주 가져와(pull 또는 rebase) 동기화하며, 충돌을 점진적으로 해결한다 [7, 8].
- **풀 리퀘스트(PR) 에티켓:** 
  PR은 리뷰가 용이하도록 작게 유지해야 한다 (가능하면 200줄 미만). PR 내용에는 무엇이 변경되었는지, 왜 변경되었는지, 그리고 UI 변경 시 스크린샷 등을 포함하여 리뷰어에게 충분한 맥락을 제공해야 한다 [5, 17].

## ⚖️ Trade-offs & Caveats
- **브랜치 수명 관리의 중요성:** 피처 브랜치가 오랫동안 병합되지 않고 유지될 경우(Long-lived feature branches), 메인 브랜치와의 코드 차이가 기하급수적으로 커져 심각한 대규모 병합 충돌(Merge conflicts)이 발생할 위험이 있다 [10, 18]. 따라서 피처 브랜치는 단일 논리적 변경에만 집중하여 가급적 짧은 수명(Short-lived)을 유지해야 한다 [2, 19, 20].
- **병합 전 절차로 인한 병목 현상:** 아무리 작고 간단한 변경이라도 풀 리퀘스트 생성, 동료 리뷰, CI/CD 체크를 거쳐야 한다 [10, 11]. 이는 코드 품질을 보장하지만, 아주 사소한 수정조차도 즉각적인 적용이 지연되는 병목이 될 수 있다 (팀에 따라 사소한 수정은 `main`에 직접 커밋하는 예외를 두기도 한다 [8]).
- **복잡한 릴리스 관리의 한계:** 여러 기능이 하나로 묶여 특정 스케줄에 따라 배포되어야 하는 대규모 프로젝트의 경우, `main` 브랜치 하나만 운영하는 단순 피처 브랜치 워크플로우는 관리가 어려울 수 있다. 이 경우 Git-Flow 같은 더 무거운 구조가 요구된다 [9].

## 🔗 Knowledge Connections

### Related Concepts

#### [버전 관리 / 통합 아키텍처]
- [[Pull Request (PR)]]
  - 연결 이유: 피처 브랜치에서의 작업물을 메인 브랜치로 병합하기 전, 코드 리뷰와 자동화된 테스트를 진행하는 핵심 관문이다 [6, 11].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 팀 내 피드백 루프 작동 방식, 코드 품질 유지 매커니즘, 그리고 안전한 코드 통합 절차.
- [[Squash Merge]]
  - 연결 이유: 피처 브랜치에서 발생한 여러 개의 자잘한 커밋을 하나의 의미 있는 커밋으로 압축하여 메인 브랜치에 병합하는 전략이다 [5, 7].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 메인 브랜치의 깃 히스토리(Git history)를 깔끔하고 가독성 높게 유지하는 원리.
- [[Continuous Integration (CI)]]
  - 연결 이유: PR이 생성되었을 때 메인 브랜치에 병합되기 전 자동화된 테스트(예: 린팅, 빌드 검증)를 수행하여 코드가 안전한지 확인하는 방어 시스템이다 [4, 5].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: `main` 브랜치의 상태를 '항상 배포 가능(Always stable)'하게 유지하는 기술적 보장 방법.

#### [개발 방법론 / 규약]
- [[Ticket IDs Traceability]]
  - 연결 이유: 브랜치 이름과 커밋 메시지에 JIRA나 GitHub Issues와 같은 티켓 ID(예: PROJ-123)를 포함시켜 코드 변경 사항을 비즈니스 요구사항과 직접적으로 연결한다 [13, 16].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 코드 변경의 배경 파악, 리뷰어의 맥락 이해 지원, 요구사항 구현 추적성 확보.
- [[Conventional Commits]]
  - 연결 이유: `feat:`, `fix:`, `chore:` 등 표준화된 형식을 사용하여 커밋 메시지를 작성하는 규칙으로, 피처 브랜치의 변경 내역을 일관성 있게 소통한다 [6, 17, 21].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 커밋 히스토리의 가독성 향상 및 자동화된 릴리스 노트 생성의 기반.

### Deeper Research Questions

- 대규모 병합 충돌을 피하기 위해, 피처 브랜치 워크플로우 내에서 브랜치의 수명(Lifetime)을 기술적/절차적으로 짧게 강제하려면 어떤 방법들을 적용할 수 있는가?
- 단순한 피처 브랜치 워크플로우를 사용하다가, 팀 규모가 커지고 스케줄링된 정기 릴리스가 필요해질 때 Git-Flow 등으로의 마이그레이션을 어떻게 점진적으로 수행할 수 있는가?
- 로컬 피처 브랜치에서 `main` 브랜치의 최신 변경 사항을 동기화할 때, `git merge main`과 `git rebase main`을 사용하는 것의 실질적인 장단점 및 권장 사례는 무엇인가?
- 원자적 커밋(Atomic Commits) 규칙을 개발 팀 내에서 효과적으로 정착시키기 위해 코드 리뷰 과정이나 CI 도구에서 어떤 검증 기준을 세울 수 있는가?
- 긴급하게 프로덕션 환경의 버그(Hotfix)를 수정해야 할 경우, 피처 브랜치 워크플로우 내에서 `main`의 안정성을 해치지 않으면서 가장 빠르고 안전하게 배포하는 흐름은 무엇인가?

### Practical Application Contexts

- **Implementation:** GitHub 레포지토리 설정에서 `main` 브랜치에 직접 커밋을 막는 보호 기능(Branch protection)을 활성화하고, 최소 1명의 리뷰와 CI 통과를 필수로 설정하여 프로세스를 강제한다 [5]. 브랜치 이름은 `{type}/{ticket-id}-{description}` 형식을 사용한다 [14].
- **System Design:** 변경된 UI 코드가 시스템 디자인에 악영향을 주지 않도록, PR 리뷰 단계에서 Storybook 및 Chromatic과 같은 시각적 회귀 테스트(Visual regression testing) 도구를 연동하여 검증을 자동화한다 [22].
- **Operation / Maintenance:** 문제가 발생했을 때 문제의 원인이 되는 커밋을 롤백(Revert)하거나 추적하기 쉽도록, Squash Merge 옵션만을 허용하여 커밋 단위를 기능별로 정리하고 병합된 브랜치는 자동 삭제(Auto-delete) 옵션을 켜둔다 [5, 7, 11].
- **Learning Path:** 2~5인 규모의 소규모 학생 팀이나 스타트업 프로젝트에서 버전 관리를 시작할 때 가장 먼저 도입하여 Git 협업의 기초(브랜치 생성, 커밋, PR, 리뷰, 머지)를 학습하는 용도로 적합하다 [3, 9].
- **My Project Relevance:** 팀원들이 겹치는 파일을 수정하다 코드가 유실되는 것을 막고, PR을 통한 코드 리뷰 문화 정착으로 전체적인 코드 품질과 팀원의 이해도를 상향 평준화하는 기본 협업 모델로 도입할 수 있다.

### Adjacent Topics

- [[Trunk-Based Development]]
  - 확장 방향: 피처 브랜치의 수명을 수 시간 이내로 극단적으로 줄이고, 메인 브랜치(Trunk)로 아주 빈번하게 병합하는 방식이다 [9]. 강력한 CI와 기능 토글(Feature flags)이 뒷받침되는 시니어 팀을 위한 심화 협업 워크플로우로 비교 학습할 수 있다 [9, 20].
- [[Git-Flow]]
  - 확장 방향: `develop`, `release`, `hotfix` 등 더 복잡하고 분리된 브랜치 계층을 가지는 전략이다 [9]. 소규모 팀의 단순한 피처 브랜치 워크플로우가 대규모 엔터프라이즈 환경 및 정기 배포 환경으로 확장될 때 어떻게 변모하는지 학습할 수 있다 [9, 23].

---
*Last updated: 2026-04-30*