AI 에이전트 협업 팀을 위한 Git 운영 튜토리얼

AI 에이전트를 적극적으로 쓰는 팀에서 Git이 어려워지는 이유는 거의 항상 똑같습니다.

• 에이전트가 “큰 변경”을 한 번에 만들어 PR이 커짐
• 브랜치가 오래 살아남아 main과 멀어짐(드리프트)
• 충돌 해결이 늘어나고, 리뷰가 지옥이 됨
• 실험 코드/임시 변경이 제품 코드에 섞임

그래서 가장 안정적으로 굴러가는 조합이:

• Trunk-Based Development(메인 중심)
• exp/* 브랜치로 실험 격리
• Squash Merge로 main 히스토리 깨끗하게 유지
• Worktree로 브랜치 전환 스트레스 제거

이 글은 위 구조를 팀이 그대로 따라할 수 있게 “튜토리얼”로 풀어 씁니다.

---

0. 목표 운영 원칙(팀 합의 5줄)

1. main은 항상 배포 가능해야 한다(깨지면 최우선 복구).
2. 기능 개발은 feature/*, 버그는 fix/*, 실험은 exp/*.
3. PR은 작게, 브랜치는 짧게(가능하면 1~2일 내 머지).
4. main으로 들어갈 때는 기본 Squash Merge.
5. Worktree로 동시 작업(AI 실행/실험/핫픽스)을 안전하게 분리한다.

---

1. 브랜치/폴더 설계: “제품”과 “실험”을 물리적으로 갈라라

1) 브랜치 네이밍 규칙(추천)

• main : 운영(Protected)
• feature/<ticket>-<short-title> : 기능
• fix/<ticket>-<short-title> : 버그
• chore/<short-title> : 도구/리팩토링(기능 변경 없음)
• exp/<topic>-<who>-<date> : 실험/에이전트 탐색

예시

• feature/JIRA-123-auth-refresh
• fix/JIRA-201-null-crash
• exp/rag-prompt-minsoo-2026-02-12

2) Worktree 폴더 구조(추천)

한 저장소를 이런 형태로 씁니다.

repo-main/          (main)
repo-feature-auth/  (feature/JIRA-123-auth-refresh)
repo-exp-rag/       (exp/rag-prompt-minsoo-2026-02-12)
repo-fix-crash/     (fix/JIRA-201-null-crash)

포인트:

• 폴더가 다르면 실행 환경도 다릅니다.
• AI 에이전트가 파일을 대량 수정/생성해도 다른 작업공간이 안전합니다.
• “브랜치 전환”으로 인한 작업 상태 꼬임이 거의 사라집니다.

---

2. 리포지토리 기본 세팅(팀 표준 만들기)

1) main 보호 규칙(강력 추천)

GitHub 기준으로 보통 이렇게 설정합니다.

• main 직접 push 금지
• PR 필수
• 리뷰 1명 이상(혹은 CODEOWNERS)
• CI 통과 필수(테스트/린트/타입체크)
• (가능하면) “Require linear history”는 팀 성향 따라 선택
  • Squash를 쓰면 히스토리는 대체로 선형에 가까워집니다.

2) PR 기본 정책(숫자로 박아두면 강해짐)

• PR 변경량 상한(예시): ≤ 500 lines 또는 ≤ 20 files
• 한 PR = 한 목적(기능 + 리팩토링 섞지 않기)
• 실험(exp/*) PR은 기본 “머지 대상 아님”으로 분리(아래에서 운영법 설명)

---

3. Worktree 실전 튜토리얼: “동시에 여러 브랜치”를 가장 안전하게

Worktree는 폴더 복사가 아닙니다.
Git 저장소는 공유하고, 작업 파일만 폴더별로 분리합니다.

0) 준비: 메인 작업 폴더 만들기

이미 클론이 있다면 그 폴더를 repo-main으로 쓰세요.

git clone <YOUR_REPO_URL> repo-main
cd repo-main
git checkout main
git pull origin main

1) feature 브랜치를 Worktree로 생성

repo-main 폴더에서 실행:

git worktree add -b feature/JIRA-123-auth-refresh ../repo-feature-auth main

이제:

• repo-main은 main
• repo-feature-auth는 feature/JIRA-123-auth-refresh

2) 실험 브랜치(exp)도 Worktree로 생성

git worktree add -b exp/rag-prompt-minsoo-2026-02-12 ../repo-exp-rag main

3) 지금 worktree 목록 확인

git worktree list

4) 작업 끝난 worktree 제거

git worktree remove ../repo-exp-rag

제거는 폴더만 지우는 게 아니라 worktree 연결도 정리해줘서 깔끔합니다.

---

4. Trunk-Based 개발 흐름(핵심): “짧게 만들고 빨리 합치기”

아래는 팀이 매일 반복할 “표준 루틴”입니다.

---

A) 기능 개발(feature) 표준 루틴

Step 1) feature 폴더로 이동해서 작업

cd ../repo-feature-auth

Step 2) 작업(에이전트 사용 포함) → 커밋은 “작게”

AI 에이전트가 한 번에 많이 바꿔도 커밋은 쪼개는 게 이득입니다.

예:

• (1) API 스켈레톤
• (2) 비즈니스 로직
• (3) 테스트
• (4) 문서/리팩토링

git add -A
git commit -m "feat(auth): add refresh token endpoint"

Step 3) PR 열기 전, main 최신화(충돌 방지의 핵심)

git fetch origin
git rebase origin/main

충돌 나면 여기서 해결하고 계속 진행합니다.
(중요) rebase 후에는 보통:

git push --force-with-lease

--force-with-lease는 “내가 마지막으로 본 원격 상태와 다르면 강제 push를 막아주는 안전장치”라 팀에서 자주 씁니다.

Step 4) 원격 브랜치로 push

git push -u origin feature/JIRA-123-auth-refresh

Step 5) PR 생성 → 리뷰 → CI 통과 → Squash Merge

GitHub에서 “Squash and merge”를 기본으로.

---

B) 버그 핫픽스(fix) 표준 루틴(실전에서 가장 유용)

핫픽스는 “작업 중이던 feature를 멈추고도” 안전하게 처리해야 합니다. Worktree가 이걸 끝내줍니다.

Step 1) 핫픽스 worktree 생성(메인에서)

cd ../repo-main
git pull origin main
git worktree add -b fix/JIRA-201-null-crash ../repo-fix-crash main

Step 2) 핫픽스 폴더에서 수정/테스트/커밋

cd ../repo-fix-crash
# 수정...
git commit -am "fix: prevent null crash in payment flow"
git push -u origin fix/JIRA-201-null-crash

Step 3) PR → Squash Merge → main 업데이트

cd ../repo-main
git pull origin main

이제 feature 폴더에서도 main 반영이 필요하면:

cd ../repo-feature-auth
git fetch origin
git rebase origin/main

---

5. exp/* 브랜치 운영법: “실험은 빨리 버리고, 결과만 제품에 가져와라”

AI 협업에서 가장 큰 사고는 실험 코드가 자연스럽게 제품 코드에 섞이는 것입니다.
그래서 exp/*는 운영 규칙이 분명해야 합니다.

exp/*의 3가지 목적

1. 에이전트로 아이디어를 빠르게 검증
2. 대규모 변경 전 탐색(대체 구현 비교)
3. 프롬프트/설계/리팩토링 실험

exp/*에서 지켜야 할 규칙(추천)

• exp/*는 기본적으로 main에 머지하지 않는다
• 성공한 실험의 결과는:
  • (방법 1) 필요한 커밋만 cherry-pick
  • (방법 2) feature 브랜치에서 동일 변경을 “깨끗하게” 재구현
• exp/*는 짧게 살리고(worktree remove) 정리한다

방법 1) 실험에서 “필요한 커밋만” 가져오기(cherry-pick)

예를 들어 실험에서 커밋 abc1234가 유효했다면:

cd ../repo-feature-auth
git cherry-pick abc1234

이러면 실험 브랜치 전체가 섞이지 않고, 필요한 변경만 들어옵니다.

방법 2) 실험은 참고만 하고 feature에서 재작성

AI가 만든 코드가 “아이디어는 좋지만 품질이 애매”한 경우에 더 안전합니다.
실험 브랜치를 “레퍼런스”로 두고 feature에서 깔끔하게 구현하세요.

---

6. Squash Merge를 기본으로 쓰는 이유(특히 AI 팀에서)

Squash는 “커밋 여러 개를 하나로 합쳐서 main에 넣는 것”입니다.

AI 팀에서 Squash가 주는 장점

• 에이전트가 만든 잔 커밋/재시도 커밋이 main 히스토리를 더럽히지 않음
• main을 보면 “무슨 기능이 언제 들어왔는지” 한 눈에 보임
• revert도 쉬워짐(한 커밋만 되돌리면 됨)

팀 표준 커밋 메시지 템플릿(추천)

Squash 커밋 메시지는 “PR 제목 + 요약”으로 깔끔하게.

예:

feat(auth): add refresh token flow (JIRA-123)

- Add refresh endpoint + rotation
- Add unit tests
- Update docs

---

7. PR 템플릿(AI 협업에서 효과 큰 최소 양식)

.github/pull_request_template.md에 아래 정도만 넣어도 리뷰 품질이 크게 좋아집니다.

• 목적(무엇을/왜)
• 검증 방법(테스트/재현)
• 리스크(영향 범위, 롤백)

예시(복붙용):

## What
- 

## Why
- 

## How to test
- [ ] Unit tests
- [ ] Manual: 

## Risk / Rollback
- Risk:
- Rollback:

AI 에이전트 사용 시 추가로 한 줄만 더:

• “에이전트가 변경한 주요 파일/영역” 체크(리뷰어가 빠르게 감 잡음)

---

8. CI(자동화)는 “AI 협업의 안전벨트”

AI 팀에서 CI는 선택이 아니라 거의 필수입니다.

최소 권장:

• lint/format
• typecheck
• unit test
• (가능하면) e2e smoke

그리고 main 보호 규칙에서 “CI 통과 필수”를 걸어두면:

• 에이전트가 만든 미세한 오류가 main으로 들어오는 확률이 급감합니다.

---

9. 팀에서 자주 터지는 사고 7가지(예방 체크리스트)

1. 브랜치가 오래 살아남음 → 매일 rebase(또는 짧게 쪼개기)
2. 큰 PR → “한 목적/한 PR” + 변경량 상한
3. 실험 코드 섞임 → exp/*로 격리 + 결과만 cherry-pick
4. rebase 후 force push로 사고 → --force-with-lease 표준화
5. main에서 작업 → main direct push 금지
6. AI가 전체 리포맷 → 포맷 변경은 별도 PR
7. 테스트 없는 PR → CI 필수 + PR 템플릿에 “How to test” 강제

---

10. “하루 운영” 예시 시나리오(이대로 따라하면 됨)

오전: 기능 개발(에이전트 사용)

# feature worktree
cd repo-feature-auth
# 작업...
git commit -am "feat(auth): add refresh endpoint"
git fetch origin
git rebase origin/main
git push -u origin feature/JIRA-123-auth-refresh

PR 생성 → 리뷰 → Squash merge

오후: 갑자기 크래시 핫픽스

cd repo-main
git pull origin main
git worktree add -b fix/JIRA-201-null-crash ../repo-fix-crash main

cd ../repo-fix-crash
# 수정...
git commit -am "fix: prevent null crash"
git push -u origin fix/JIRA-201-null-crash

PR → Squash merge

마무리: feature 브랜치도 최신화

cd ../repo-feature-auth
git fetch origin
git rebase origin/main
git push --force-with-lease

---

11. 바로 적용 가능한 “팀 규칙” 한 장(요약)

• 브랜치: feature/*, fix/*, exp/*
• PR: 작게(≤ 500 lines), 한 목적
• 머지: 기본 Squash
• 동기화: PR 전 rebase origin/main
• 실험: exp/*에서 하고, 결과만 cherry-pick
• 작업공간: Worktree로 분리
• 안전: main 보호 + CI 필수

---