작업 브랜치 정책

작업 브랜치 정책 — 실전 적용 구조와 코드 예시

언제 쓰나 · 한 저장소에서 **운영용 코드와 개발용 코드를 같은 브랜치에 섞지 않으려고 할 때**. · 전형적 증상: · 사용자가 "수정해줘"라고만 말하면 AI 에이전트가 운영에 손댈지 개발에 손댈지 모호함 · main 브랜치에 실험적 작업이 들어가 운영 빌드가 깨짐

---
title: 개발/운영 브랜치 분리 정책 (dev_branch / main)
tags: [infra, git, branch-strategy, workflow, agents-md]
created: 2026-04-27
---

## 1. 언제 쓰는가

한 저장소에서 **운영용 코드와 개발용 코드를 같은 브랜치에 섞지 않으려고 할 때**.

전형적 증상:

- 사용자가 "수정해줘"라고만 말하면 AI 에이전트가 운영에 손댈지 개발에 손댈지 모호함
- main 브랜치에 실험적 작업이 들어가 운영 빌드가 깨짐
- 운영 hotfix 와 dev refactor 가 같은 라인 위에서 충돌
- "정리된 운영 라인"과 "개발 흔적이 남은 라인"이 자연 발생적으로 갈라져 두 brand 가 따로 진화

이 패턴은 위 모호함을 **명시적 디폴트 + 명시적 키워드** 로 해결한다.

## 2. 핵심 원칙

| 원칙 | 의미 |
|---|---|
| **디폴트는 `dev_branch`** | 사용자가 단순 명령("수정", "추가", "고쳐")만 내리면 모든 작업은 `dev_branch` 또는 그 후손 브랜치에서. |
| **`main`은 운영 라인** | 명시적 키워드("운영", "배포", "hotfix", "main에", "프로덕션")가 등장할 때만 main 에 손댐. |
| **`main` 직접 commit 금지** | 검증된 dev 변경을 cherry-pick / merge 로 옮긴다. |
| **모호하면 묻는다** | 키워드가 애매하면 추측하지 말고 사용자에게 dev/main 여부 확인. |

## 3. AGENTS.md / CLAUDE.md 에 넣을 정책 텍스트 (템플릿)

각 프로젝트의 `AGENTS.md`(또는 `CLAUDE.md`)에 BEGIN/END 마커로 감싸 추가하면 향후 자동 업데이트도 쉽다.

```markdown
<!-- BEGIN:branch-policy -->
# 작업 브랜치 정책

이 저장소는 운영(`main`)과 개발(`dev_branch`)을 분리한다.

## 디폴트는 `dev_branch`

사용자가 단순히 "수정해줘", "기능 추가", "버그 고쳐"라고 하면 항상 `dev_branch`(또는 그 후손인 worktree 브랜치)에서 작업한다. **`main`에 직접 commit 금지.**

## `main` 작업은 명시적 키워드일 때만

다음 중 하나가 등장할 때만 `main`(운영)에 손댄다:

- "운영", "배포", "hotfix", "main에", "프로덕션" 등 운영 라인 지시 키워드
- 사용자가 명시적으로 브랜치명 지정 (예: "main 브랜치에서 …")

키워드가 모호하면 추측하지 말고 dev 인지 main 인지 사용자에게 한 번 묻는다.

## 반영 흐름 (dev → main)

1. `dev_branch`(또는 그 후손)에서 작업한다.
2. build / 테스트로 검증한다.
3. 운영 반영 시점에 `main`에 옮긴다.
   - **두 라인이 크게 갈라져 있을 때**: cherry-pick 으로 단건 이전.
     `git checkout main && git cherry-pick <검증된 dev commit hash>`
   - **두 라인이 정상화된 후**: `git merge dev_branch` 또는 fast-forward.
<!-- END:branch-policy -->
```

## 4. 신호 단어 매핑 (사용자 발화 → 적용 브랜치)

| 사용자 표현 | 적용 브랜치 |
|---|---|
| "수정해줘", "기능 추가", "버그 고쳐", "리팩터" | `dev_branch` |
| "운영 반영", "배포해", "main 에 올려", "hotfix" | `main` |
| "dev 에서 검증한 거 운영에 보내" | dev → main 반영 (cherry-pick / merge) |
| "프로덕션 깨졌어" | `main` 직접 hotfix (긴급) |

## 5. 초기 셋업 (브랜치 생성)

기존 저장소에 적용할 때:

```bash
# 1) 운영 라인을 main 으로 (또는 별도 운영 브랜치를 main 으로 rename)
#    이미 main 이 운영 라인이면 생략.
git branch -m main old-main          # 임시 백업
git branch -m production-line main   # 운영 라인을 main 으로

# 2) 개발 라인을 dev_branch 로
git branch -m old-main dev_branch
# 또는 main 에서 새로 분기:
git checkout main && git checkout -b dev_branch
```

worktree 가 attached 된 브랜치를 rename 하면 git 이 worktree HEAD 도 자동으로 따라간다 (Git 2.x+).

## 6. 반영 흐름 상세

### 6.1 정상 흐름 (두 라인이 정렬되어 있을 때)

```bash
# dev_branch 에서 작업 + 검증 후
git checkout main
git merge dev_branch          # fast-forward 또는 일반 merge
```

### 6.2 두 라인이 갈라져 있을 때 (역사적 분기 / 운영 정리본 / 충돌 해결본)

**큰 merge 한 번보다 cherry-pick 단건 이전이 안전.**

```bash
# dev_branch 에서 검증된 commit 의 hash 를 확인
git log --oneline dev_branch

# main 으로 이동 후 cherry-pick
git checkout main
git cherry-pick <hash>

# 충돌 시 해결 후
git cherry-pick --continue
```

cherry-pick 단건이 누적되어 두 라인 차이가 사라지면 그 시점부터 6.1 흐름으로 전환.

## 7. worktree 와 함께 쓰기

여러 작업을 동시에 진행할 때:

```bash
# 운영 hotfix 용 worktree
git worktree add ../<repo>-hotfix main

# dev 작업용 worktree
git worktree add ../<repo>-feature dev_branch

# 단발성 dev_branch 편집 (정책 문서 갱신 등)
git worktree add /tmp/<repo>-dev-edit dev_branch
# 작업 후
git worktree remove /tmp/<repo>-dev-edit
```

## 8. 안티패턴

| 하지 말 것 | 이유 |
|---|---|
| `main` 에 직접 commit | 검증되지 않은 변경이 운영 라인에 들어감 |
| dev 와 main 을 자주 큰 merge | conflict 누적 → resolve 비용 폭증 |
| AGENTS.md 정책 누락 | 새 세션의 AI 가 디폴트를 모름 |
| "그냥 빠르게 main 에" | 한 번의 빠른 우회가 정책 무력화의 시작 |

## 9. 새 프로젝트 적용 체크리스트

- [ ] `dev_branch` 와 `main` 두 브랜치가 존재하는가
- [ ] AGENTS.md (또는 CLAUDE.md) 에 위 §3 정책 텍스트가 들어갔는가
- [ ] 운영용 worktree 가 `main` 에 attached 되어 있는가
- [ ] 개발용 worktree(들)이 `dev_branch` 또는 그 후손 브랜치에 attached 되어 있는가
- [ ] 첫 cherry-pick / merge 흐름을 한 번 연습해 두었는가

## 10. 발생 배경 메모

이 패턴은 Vibeollio 프로젝트(2026-04-27)에서 다음 상황으로 정리되었다:

- `deploy-main`(운영 정리본, `[v0.x.x]` 태그 컨벤션)과 `main`(개발 흔적 + origin/main 충돌 해결 흔적)이 공통 조상에서 갈라져 따로 진화
- 사용자가 "수정해줘"만 하면 어느 라인을 가리키는지 불명확
- 해결: deploy-main → main, 옛 main → dev_branch 로 rename. 정책 텍스트를 AGENTS.md 에 명문화. 두 라인 통합은 cherry-pick 으로 단건 진행.