# [[Git Workflow for Frontend Teams]]

## 📌 Brief Summary
프론트엔드 팀을 위한 Git 워크플로우는 코드 변경 사항을 체계적으로 관리하여 충돌을 방지하고 협업을 촉진하며 안정적인 배포 환경을 유지하기 위한 구조화된 접근 방식이다 [1-3]. 주요 전략으로는 기능 브랜치(Feature-branch), 깃허브 플로우(GitHub Flow), 트렁크 기반(Trunk-based) 개발 등이 있으며, 이들은 짧은 수명의 브랜치, 명확한 명명 규칙 및 커밋 컨벤션, 동료 리뷰가 포함된 풀 리퀘스트(PR)를 공통으로 강조한다 [2, 4, 5]. 잘 구현된 워크플로우는 잠재적인 혼란을 예측 가능한 고품질 업데이트의 흐름으로 변환하는 핵심 역할을 한다 [2].

## 📖 Core Content
* **브랜칭 전략 (Branching Strategies)**: 2~5명 규모의 소규모 팀은 오버헤드가 큰 Git Flow 대신 심플한 기능 브랜치(Feature-branch) 워크플로우나 트렁크 기반 개발을 주로 채택한다 [6-8]. 이러한 워크플로우는 항상 배포 가능한 안정적인 `main` 브랜치를 기반으로 하며, `main`으로의 직접적인 커밋은 엄격히 제한된다 [9, 10].
* **브랜치 관리 및 명명 규칙 (Branch Management & Naming)**: 브랜치는 수명이 짧아야 하고, 단일 논리적 변경에만 집중해야 하며, 병합 후에는 자동으로 삭제되어야 한다 [9, 11]. 브랜치 이름은 서술적이어야 하며, 변경 사항의 추적성을 높이기 위해 이슈/티켓 ID(예: `feature/PROJ-123-user-auth`, `bugfix/GH-456-login-fix`)를 포함하는 것이 권장된다 [12, 13].
* **커밋 규칙 (Commits)**: 각 커밋은 하나의 논리적 변경 사항만 포함하는 원자적 커밋(Atomic Commits) 형태여야 한다 [14]. 가독성 높은 히스토리 유지와 릴리스 노트 자동화를 위해 `feat:`, `fix:`, `docs:`, `refactor:`, `chore:` 등을 사용하는 'Conventional Commits' 포맷을 따른다 [11, 15, 16].
* **풀 리퀘스트 및 병합 (PR & Merging)**: 철저한 리뷰를 위해 PR은 가급적 작은 크기(예: 200줄 이하)로 유지해야 한다 [9]. 병합 전에는 최소 한 명의 동료 리뷰어 승인과 CI/CD 테스트 통과가 필수적으로 요구된다 [9, 10]. 깔끔한 `main` 브랜치 히스토리를 유지하기 위해 스쿼시 병합(Squash merge)이 널리 권장된다 [9, 17]. 또한, Storybook이나 Chromatic과 같은 도구를 사용하여 시각적 회귀(Visual regression) 검토를 PR 과정에 연동할 수 있다 [18].
* **충돌 방지 (Conflict Prevention)**: 개발자는 대규모 병합 충돌이 누적되는 것을 막기 위해 `main` 브랜치의 최신 변경 사항을 자주 가져와(pull/rebase) 자신의 기능 브랜치를 동기화하고, 충돌을 점진적으로 해결해야 한다 [7, 17].

## ⚖️ Trade-offs & Caveats
* **트렁크 기반 vs Git Flow**: 트렁크 기반 개발은 빠른 피드백과 통합을 가능하게 하지만, 지속적인 통합(CI)을 완벽히 구축한 경험 많은 팀에게 적합하다 [8]. 반면, Git Flow는 정기적인 릴리스를 수행하는 대규모 프로젝트에 강력한 구조를 제공하지만, 소규모 팀이 도입하기에는 복잡성과 절차적 오버헤드가 커서 진행 속도를 늦추는 부작용(Trade-off)이 있다 [6, 8].
* **브랜치 수명 (Branch Lifespan)**: 기능 브랜치가 분리되어 오래 유지될수록 병합 충돌의 위험이 기하급수적으로 커진다. 이를 막기 위해 짧은 수명의 브랜치를 유지하면 빈번한 PR 생성과 코드 동기화로 인한 문맥 전환(Context switching) 오버헤드가 발생하지만, 장기적으로 파괴적인 충돌과 리팩토링 비용을 예방하는 반대 급부가 있다 [7, 19].
* **엄격한 규칙 vs 유연성**: 모든 브랜치와 커밋에 티켓 ID를 강제하고 Conventional Commits를 따르게 하면 개발자에게 규율을 요구하지만, 이를 간과할 경우 코드 변경의 맥락과 요구 사항의 추적성(Traceability)을 완전히 상실하게 되는 한계점이 존재한다 [20].

## 🔗 Knowledge Connections

### Related Concepts

#### [아키텍처/기반 기술]
- [[Trunk-Based Development]]
  - 연결 이유: 무거운 Git Flow에 대비되는 경량화 전략의 대표적 사례이기 때문이다 [6, 8].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 메인 브랜치에 코드를 자주, 작게 밀어 넣음으로써 대규모 병합 충돌을 피하고 빠른 코드 통합을 이루는 원리.
- [[Git Flow]]
  - 연결 이유: 개발 브랜치, 릴리스 브랜치 등을 두는 전통적이고 복잡한 브랜칭 모델이기 때문이다 [6, 8, 21].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 단순한 워크플로우를 넘어 특정 스케줄과 버전에 따른 복잡한 배포 관리가 필요할 때 요구되는 구조적 접근.
- [[GitHub Flow]]
  - 연결 이유: 안정적인 메인 브랜치와 PR 기반의 기능 브랜치를 사용하는 대중적인 전략이기 때문이다 [5, 22].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 추가적인 통합 브랜치(develop 등) 없이 기능 브랜치에서 바로 테스트를 거쳐 `main`으로 병합되는 지속적 배포의 흐름.

#### [구현/활용 도구]
- [[Conventional Commits]]
  - 연결 이유: 프로젝트의 커밋 이력을 직관적으로 파악할 수 있게 돕는 표준화된 포맷이기 때문이다 [11, 15].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 일관된 커밋 형식이 어떻게 릴리스 노트 자동화 및 코드 히스토리 스캐닝으로 이어지는지에 대한 메커니즘.
- [[Pull Requests (PR)]]
  - 연결 이유: 코드가 메인 브랜치로 통합되기 전 검증을 거치는 핵심 관문이기 때문이다 [14, 15].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 팀 내 코드 리뷰, 자동화된 테스트(CI) 확인 등 품질 게이트(Quality Gate)로서의 작동 방식.
- [[Visual Regression Testing]]
  - 연결 이유: 프론트엔드 환경의 특성상 PR 단계에서 UI 시각적 검증 도구 연동이 중요하게 다뤄지기 때문이다 [18].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: Chromatic과 같은 도구를 통해 CSS, 레이아웃 변경이 예기치 않게 다른 컴포넌트에 미치는 영향을 PR 단계에서 감지하는 방법.

### Deeper Research Questions

- 기능 브랜치(Feature-branch) 워크플로우에서 트렁크 기반(Trunk-based) 개발로 원활하게 마이그레이션하기 위해 팀은 어떤 단계적 절차를 거쳐야 하는가?
- 짧은 수명의 기능 브랜치를 안전하게 자동 병합(Auto-merge)하도록 지원하려면 CI/CD 파이프라인과 테스트 자동화를 어떻게 구성해야 하는가?
- 스토리북 및 Chromatic을 활용한 시각적 회귀 테스트(Visual Regression Testing) 도구를 PR 리뷰 주기에 병목 현상 없이 최적으로 통합하는 방법은 무엇인가?
- 여러 커밋이 하나로 압축되는 스쿼시 병합(Squash Merge)을 사용할 때, 특정 세부 변경 사항을 감사(Audit)하거나 추적하는 데 발생하는 구조적 한계점은 무엇인가?
- 메인 브랜치를 항상 배포 가능한 상태로 유지하기 위해 기능 플래그(Feature Flags)는 기능 브랜치 워크플로우와 어떻게 상호 작용하는가?

### Practical Application Contexts

- **Implementation:** 새로운 기능이나 버그 수정을 진행할 때 티켓 ID가 포함된 짧은 수명의 브랜치를 생성하고, 의미 있는 단위로 원자적 커밋을 수행하며, 잦은 `pull`을 통해 `main`과의 충돌을 선제적으로 예방한다.
- **System Design:** GitHub, GitLab 등의 저장소 설정에서 `main` 브랜치 보호 규칙(Branch protection)을 설정하여 직접 커밋을 차단하고, 병합 전 최소 1명의 코드 리뷰와 CI 통과를 강제하는 구조를 설계한다.
- **Operation / Maintenance:** PR 병합(Merge) 시 자동으로 기능 브랜치가 삭제되도록 시스템을 구성하고, 스쿼시 병합(Squash merge)을 통해 프로젝트의 커밋 트리를 간결하게 유지한다.
- **Learning Path:** 소규모 프로젝트나 프론트엔드 입문자는 복잡한 Git Flow 대신, `main` 브랜치와 단일 `feature` 브랜치를 활용하는 단순한 기능 브랜치 워크플로우부터 학습하는 것이 권장된다.
- **My Project Relevance:** 팀 내 코드 리뷰 에티켓을 정립하고, JIRA 등 이슈 트래커의 티켓 번호를 커밋 메시지와 연동하며, Storybook을 PR 검토 과정에 연동하여 UI 버그를 사전에 차단하는 규칙을 수립하는 데 직접적으로 적용할 수 있다.

### Adjacent Topics

- [[Continuous Integration / Continuous Deployment (CI/CD)]]
  - 확장 방향: PR 생성, 커밋 푸시와 같은 Git 이벤트가 어떻게 빌드, 테스트, 배포 파이프라인을 자동으로 트리거하고 개발 피드백 루프를 단축하는지 조사.
- [[Storybook & Component-Driven Development]]
  - 확장 방향: 격리된 컴포넌트 환경이 어떻게 버전 관리 시스템(Git)과 연동되어 PR 리뷰어에게 시각적 컨텍스트를 제공하는지에 대한 구체적 사례 탐구.

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