# [[Feature Branch Workflow]]

## 📌 Brief Summary
Feature Branch Workflow는 새로운 기능 추가나 버그 수정과 같은 모든 단일 작업을 메인(`main`) 브랜치에서 파생된 독립적인 단기(short-lived) 브랜치에서 수행하는 버전 관리 전략입니다 [1, 2]. 이 접근 방식은 메인 브랜치의 코드가 항상 배포 가능하고 안정적인 상태를 유지하도록 보장합니다 [1-3]. 코드를 병합하기 전에는 반드시 Pull Request(PR)와 동료의 코드 리뷰, 그리고 자동화된 테스트를 거치도록 요구하여 충돌을 방지하고 코드 품질을 유지하는 데 초점을 맞춥니다 [4, 5].

## 📖 Core Content
* **브랜치 운영 및 역할:**
  * `main` 브랜치는 항상 안정적이고 배포 가능한 상태를 유지해야 하며, 개발자가 `main`에 직접 커밋하는 것은 엄격히 금지됩니다 [1-3, 6].
  * 새로운 작업(기능, 버그 수정 등)을 시작할 때마다 `main`에서 파생된 전용 기능 브랜치(Feature Branch)를 생성하여 작업을 분리합니다 [1, 2].
  * 각 기능 브랜치는 수명이 짧아야 하며, 하나의 브랜치에서는 오직 하나의 논리적 변경 사항(Atomic Commits)만 구현해야 합니다 [4, 5, 7].

* **병합 프로세스와 품질 관리:**
  * 기능 개발이 완료되면 `main` 브랜치를 향해 Pull Request(PR)를 생성해야 합니다 [4, 5].
  * 코드를 병합하기 위해서는 최소 1명의 동료 리뷰(Peer Review) 승인과 CI(Continuous Integration) 테스트 통과가 필수적입니다 [4, 5, 8, 9].
  * 병합 시에는 전체 커밋 이력을 깔끔하게 유지하기 위해 "스쿼시 머지(Squash and merge)" 전략을 주로 사용하며, 병합 후에는 해당 기능 브랜치를 자동으로 삭제합니다 [5, 6, 8, 9].

* **명명 규칙 및 추적성(Traceability):**
  * 브랜치 이름은 수행할 작업을 명확하게 식별할 수 있도록 `feature/<short-description>` 또는 `bugfix/<short-description>`과 같이 짧고 목적이 드러나는 형식을 사용해야 합니다 [2, 4, 7].
  * 이슈 트래커(JIRA, GitHub Issues 등)를 사용할 경우, `feature/PROJ-123-user-auth`처럼 티켓 ID를 브랜치 이름과 커밋 메시지에 포함시켜 코드 변경 사항과 비즈니스 요구사항 간의 양방향 추적이 가능하게 해야 합니다 [10-12].

## ⚖️ Trade-offs & Caveats
* **부작용 및 제약 사항 (Trade-offs):**
  * `main` 브랜치에 직접 커밋하는 방식에 비해서는 PR을 생성하고 리뷰를 기다려야 하는 최소한의 프로세스 오버헤드가 발생합니다 [3, 13, 14].
* **반대 급부 및 안티 패턴 (Caveats & Anti-patterns):**
  * **수명이 긴 브랜치(Long-lived branches):** 브랜치를 수 주 동안 열어두는 것은 이 워크플로우의 가장 큰 안티 패턴이며, 심각한 머지 충돌을 유발합니다 [13, 15, 16].
  * **동기화 실패:** 대규모 충돌을 방지하기 위해 개발자는 매일 작업 시작 전과 작업 도중에 수시로 `main` 브랜치의 최신 변경 사항을 자신의 브랜치로 가져와(Pull/Rebase) 점진적으로 충돌을 해결해야 합니다 [5, 14, 15].
  * **거대한 PR:** 한 번에 너무 많은 변경을 포함하는 거대한 커밋과 PR은 빠른 피드백을 방해하므로, PR 크기를 가급적 작게(예: 200줄 이하) 유지하는 규율이 필요합니다 [8, 17].

## 🔗 Knowledge Connections

### Related Concepts

#### [아키텍처/기반 기술]
- [[Trunk-Based Development]]
  - 연결 이유: Feature Branch Workflow보다 빠른 코드 통합을 목표로 할 때 도입할 수 있는 대안적 브랜칭 전략입니다 [18, 19].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 숙련된 팀이 기능 플래그(Feature Flags)를 활용하여 메인 브랜치에 직접 작은 변경을 지속적으로 커밋하는 방식과 Feature Branch Workflow의 속도 및 안정성 차이를 이해할 수 있습니다 [19].

- [[Git Flow]]
  - 연결 이유: 소규모 팀에 적합한 Feature Branch Workflow와 대조되는, 훨씬 무겁고 복잡한 기존의 대규모 브랜칭 전략입니다 [14, 18].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 예정된 릴리스 일정이 있거나 규모가 큰 프로젝트에서 왜 `develop` 및 `release` 브랜치가 추가로 요구되는지, 그리고 작은 팀에게는 왜 이것이 오버헤드가 되는지 알 수 있습니다 [18, 20].

#### [구현/활용 도구]
- [[Pull Request (PR)]]
  - 연결 이유: Feature Branch Workflow에서 격리된 코드를 `main`으로 병합하기 전 반드시 거쳐야 하는 핵심 게이트웨이입니다 [4, 5, 7].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 코드 리뷰를 습관화하고, 단독 병합을 방지하며, CI 도구와 결합하여 어떻게 코드 품질을 방어하는지 이해할 수 있습니다 [5, 7, 21].

- [[Conventional Commits]]
  - 연결 이유: 피처 브랜치에서 수행하는 커밋 메시지의 명확성과 일관성을 보장하기 위한 업계 표준 규칙입니다 [4, 21].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: `feat:`, `fix:`, `chore:` 등의 접두사를 사용하여 커밋의 의도를 명확히 하고, 브랜치의 작업 내역을 빠르고 쉽게 파악하는 방법을 배울 수 있습니다 [21, 22].

### Deeper Research Questions
- Feature Branch Workflow에서 브랜치 수명이 길어질 때 필연적으로 발생하는 머지 충돌을 최소화하기 위한 구체적인 브랜치 동기화(Sync) 전략은 무엇인가?
- 팀의 규모가 3-5명에서 10명 이상의 다수 팀으로 커질 때, Feature Branch Workflow는 어떻게 확장되거나 다른 전략(예: Git Flow, GitLab Flow)으로 전환되어야 하는가?
- Pull Request의 코드 크기가 과도하게 커지는 것을 방지하고, 이를 "원자적 커밋(Atomic Commits)" 단위로 유지하게 만드는 실무적인 가이드라인은 무엇인가?
- CI/CD 파이프라인에서 Feature Branch Workflow를 지원하기 위해, PR 생성 시 병목을 일으키지 않으면서 필수적으로 수행해야 하는 자동화된 검사(lint, test 등)의 적정선은 어디인가?
- 개발자가 브랜치명과 커밋 메시지에 티켓 ID(JIRA 등)를 누락하지 않도록 Git Hooks나 플랫폼(GitHub, GitLab) 설정을 통해 어떻게 강제할 수 있는가?

### Practical Application Contexts

- **Implementation:** 소규모 팀(2~5명) 프로젝트 시작 시, 리포지토리 설정에서 `main` 브랜치에 직접 푸시하지 못하도록 보호(Branch Protection)를 걸고, 모든 작업을 `feature/` 또는 `bugfix/`로 명명된 브랜치에서 시작하도록 세팅합니다 [2].
- **System Design:** 버전 관리 시스템(GitHub)과 이슈 트래커(JIRA, Linear)를 연동하도록 설계하여, 개발자가 `feature/PROJ-123` 형태의 브랜치명으로 코드를 올리면 이슈 트래커에 PR 상태와 커밋 내역이 자동으로 추적되게 만듭니다 [11, 23, 24].
- **Operation / Maintenance:** 관리의 효율성을 위해, 메인 브랜치로 PR이 성공적으로 병합된 이후에는 해당 피처 브랜치가 자동으로 삭제(Auto-delete merged branches)되도록 저장소 설정을 유지합니다 [6-8].
- **Learning Path:** 처음 팀 프로젝트를 경험하는 초보 개발자들은 로컬 환경에서의 단독 작업을 넘어, 기능별로 브랜치를 분리하고 PR을 통해 동료의 리뷰를 받는 과정을 통해 올바른 협업의 기초를 다집니다 [18, 25].
- **My Project Relevance:** 현재 진행 중인 프로젝트에서 기능 병합 시 코드 충돌이 잦거나 배포 브랜치가 자주 고장난다면, 이 워크플로우를 채택하여 코드가 안정성을 확보한 상태에서만 메인 브랜치에 합류하도록 규칙을 정립할 수 있습니다 [1, 2, 14].

### Adjacent Topics
- [[Continuous Integration (CI)]]
  - 확장 방향: 피처 브랜치의 PR이 생성될 때마다 해당 코드가 안정적인지 자동으로 테스트하고 빌드하여 병합 가능 여부를 시스템적으로 검증하는 파이프라인 구축 방법으로 이해를 확장합니다.
- [[GitHub Flow]]
  - 확장 방향: Feature Branch Workflow와 매우 유사하지만, GitHub 환경과 지속적 배포(Continuous Deployment)에 더 최적화된 단순한 형태의 워크플로우로 개념을 확장하여 비교해 봅니다.

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