멀티 에이전트로 PR 나누기, 브랜치 규칙을 어떻게 정하나
멀티 에이전트 PR 워크플로의 핵심은 “한 작업 = 한 브랜치 = 한 PR”을 에이전트 단위로 유지하고, 머지 권한은 사람(또는 명시된 게이트) 에 두는 것입니다. 브랜치 이름·소유 경로·리베이스 규칙을 문서에 고정하면 병렬 작업이 충돌로 무너지지 않습니다.
이 글은 브랜치·리뷰·충돌 예방만 다룹니다. 특정 IDE 요금제, 벤치마크 숫자, 개인 사용 후기는 넣지 않습니다.
에이전트별 브랜치?
한 줄 답: 에이전트마다 base에서 갈라진 전용 브랜치를 쓰고, 브랜치 이름에 역할·티켓·짧은 목적을 넣습니다. 한 브랜치에 여러 에이전트가 push하지 않습니다.
권장 패턴:
main
└─ feat/TICKET-123-api-auth ← agent-A 전용
└─ feat/TICKET-123-ui-login ← agent-B 전용
└─ chore/TICKET-123-ci-cache ← agent-C 전용이름 규칙 예:
feat/<ticket>-<area>-<verb>fix/<ticket>-<symptom>chore/<ticket>-<tool>
에이전트에게 줄 지시(프롬프트·AGENTS.md·룰)에 넣을 항목:
- 기준 브랜치 — 보통
main또는 통합용integration/*.origin/main을 fetch한 뒤 분기합니다. - 본인 브랜치만 checkout — 다른 에이전트 브랜치에 commit하지 않습니다.
- 작업 범위(path allowlist) — 예:
src/api/**만,src/ui/**는 금지. - PR 크기 — 리뷰 가능한 단위(파일 수·관심사)로 자르라고 명시합니다.
- force-push 정책 — 공유 브랜치에는
--force금지. 본인 전용 브랜치 리베이스만 허용할지 팀에 맞게 적습니다.
여러 에이전트가 같은 워킹트리에서 돌면 체크아웃이 서로 덮어씁니다. 가능하면 워킹트리/워크트리 분리(git worktree add) 또는 에이전트별 클론·샌드박스를 씁니다. Cursor Agent / CLI 에이전트를 쓸 때도 “어느 브랜치에서만 편집할지”를 세션 시작 시 고정하는 것이 안전합니다.
한 PR에 여러 관심사를 몰아넣지 않습니다. API·UI·CI를 한 에이전트가 한꺼번에 바꾸면 리뷰도, 되돌리기도, 다른 에이전트와의 경계도 흐려집니다.
리뷰는 누가?
한 줄 답: 에이전트는 초안·셀프체크·제안까지, 승인·머지는 사람(또는 CODEOWNERS + 필수 검사) 이 합니다. 에이전트끼리만 Approve 하는 구조는 사고로 이어지기 쉽습니다.
역할 분리:
| 역할 | 하는 일 | 하지 않는 일 |
|---|---|---|
| 작성 에이전트 | 브랜치에서 구현, 테스트 실행, PR 본문 초안 | main에 직접 push, 필수 리뷰 우회 |
| 리뷰 에이전트(선택) | diff 요약, 누락 테스트·보안 체크리스트 지적 | 최종 Approve를 “사람 대신” 확정 |
| 사람 / CODEOWNERS | 의도·경계·비밀·데이터 영향 확인 후 Approve | 에이전트 출력만 믿고 스킵 머지 |
| CI | lint·test·build 게이트 | 제품 의도 판단 |
실무 게이트 예:
- PR 템플릿에 범위·비범위·테스트 방법·위험 칸을 둡니다. 에이전트가 초안을 채우고 사람이 고칩니다.
- GitHub/GitLab에서 필수 리뷰어 1+, 해당 경로
CODEOWNERS를 켭니다. main은 protected branch — 직접 push 금지, PR + status check만.- 리뷰 에이전트를 쓰더라도 “Approve 버튼은 사람” 규칙을 문서에 한 줄로 박습니다.
리뷰 코멘트는 파일·줄 단위로 남기고, 작성 에이전트에게 “코멘트 반영 전용 커밋”으로 고치게 하면 이력이 읽기 쉽습니다. 무관한 리팩터를 같은 PR에 끼워 넣지 않게 다시 한 번 범위를 상기시킵니다.
충돌 예방은?
한 줄 답: 경로·레이어를 나누고, 공유 파일은 한 에이전트만 건드리며, 머지 전에 main을 자주 rebase/merge 합니다. 충돌이 난 뒤에는 한 에이전트(또는 사람) 가 통합 브랜치에서만 해결합니다.
예방 체크리스트:
- Path ownership —
api//web//infra/처럼 디렉터리로 소유권을 나눕니다. 두 에이전트가 같은 파일에 쓰게 시키지 않습니다. - 공유 파일 락 —
package-lock.json,pnpm-lock.yaml, 생성 코드, 라우트 테이블, i18n 카탈로그는 한 주인만 수정합니다. 필요하면 짧은 “lock PR”을 먼저 머지합니다. - 작은 수직 슬라이스 — “스키마 + 핸들러 + 테스트”처럼 의존 방향이 맞는 묶음으로 PR을 자릅니다. 가로로 모든 레이어를 동시에 열면 충돌 면적이 커집니다.
- 동기화 주기 — 작업 시작·중간·PR 직전에
git fetch origin후rebase origin/main(또는 merge). 에이전트 프롬프트에 “PR 열기 전 rebase”를 넣습니다. - 통합 순서 — 충돌 위험이 낮은(또는 의존되는) PR부터 머지합니다. API 계약 PR → 구현 PR → UI PR 순이 흔합니다.
- 충돌 발생 시 — 작성자 에이전트에게 “상대 브랜치를 merge해서 추측 해결”을 맡기지 말고, 통합 담당이
main최신 + 두 diff를 보고 해결합니다. 해결 커밋은 한 브랜치에만 남깁니다.
에이전트에게 유용한 금지 문구 예:
- “
main에 commit/push 하지 말 것” - “allowlist 밖 파일을 수정하지 말 것”
- “lockfile·생성물을 임의로 재생성하지 말 것”
- “다른 에이전트 PR에 push하지 말 것”
- “충돌 마커를 남긴 채 PR을 열지 말 것”
마무리
멀티 에이전트로 PR을 나누려면 에이전트별 전용 브랜치 + 경로 경계, 사람은 승인 게이트, 공유 파일 단일 소유·잦은 rebase 세 축이면 충분합니다. 도구 이름보다 브랜치·리뷰·충돌 규칙이 문서에 있는지가 병렬 속도를 좌우합니다.