QA 서버 세 대를 돌려 쓰던 브랜치 전략, AI 에이전트와 일하는 지금 다시 짠다면
2024년에 노코드 웹 빌더 에디터팀에서 만든 브랜치 전략과 릴리즈 노트 자동화를, 코딩 에이전트와 일하는 지금 기준으로 다시 짜 봤습니다. 브랜치 구조는 거의 그대로 두고, 사람이 지켜야 했던 규칙을 어디까지 AI에게 넘길 수 있는지를 정리했습니다.
2024년 2월, 노코드 웹 빌더 에디터팀에서 브랜치 전략 문서를 썼습니다. feature에서 시작해 QA 브랜치 세 개, dev, stg, prod를 거쳐 운영에 나가는 흐름이었고, PR 제목으로 라벨을 붙이고 그 라벨로 릴리즈 노트를 자동으로 만드는 설정까지 넣었습니다. 문서 마지막 장에 자동으로 만들어진 v1.2.0 릴리즈 노트 캡처를 붙이면서 꽤 뿌듯했던 기억이 납니다.
얼마 전 그 문서를 다시 열어 봤습니다. 지금은 코드의 대부분을 코딩 에이전트와 함께 쓰는데, 문서에 적힌 규칙 대부분이 "사람이 지켜야 동작하는 규칙"이라는 게 눈에 들어왔습니다. 이 글에서는 2024년의 브랜치 전략을 돌아보고, AI 에이전트와 일하는 지금이라면 어떤 브랜치 전략이 괜찮아 보이는지, 그리고 AI를 어디에 붙이면 그 전략을 덜 수고롭게 굴릴 수 있는지를 다룹니다. 제가 아직 다 적용해 본 구성은 아니라서, 해 본 것과 제안하는 것을 구분해서 적었습니다.
1. 2024년에 만든 흐름은 이랬습니다
브랜치는 다섯 단계였습니다.
feature dev에서 분리, 각자 로컬에서 작업
qa1, qa2, qa3 기능 단위 테스트, 브랜치마다 별도 도메인의 서버
dev 단위 테스트가 끝난 코드를 모아 통합 테스트와 e2e
stg 운영에 바로 나갈 수 있는 릴리즈 후보
prod 운영 환경feature 브랜치는 feature/{이슈번호}-{기능이름} 형식으로 만들었습니다. 작업이 끝나면 비어 있는 QA 브랜치로 머지하고, 그 QA 서버에서 기능 테스트를 했습니다. 테스트가 끝나면 dev로 올리고, QA 브랜치는 초기화해서 다음 사람이 쓰게 했습니다. 급한 수정은 QA에서 dev를 건너뛰고 stg로 바로 가는 길도 열어 두었습니다.
버전은 유의적 버전(Semantic Versioning)을 따랐습니다. 정기 릴리즈는 마이너, 수시로 나가는 수정은 패치를 올리는 식이었습니다. 프리릴리즈(pre-release) 라벨도 쓸지 고민했는데, 문서에 취소선을 긋고 "사용할 필요가 있을까"라고 적어 둔 채로 끝났습니다.
자동화는 세 가지였습니다.
- PR 템플릿(
pull_request_template.md)에 변경 종류 체크박스, 주요 변경 사항, 이슈 링크, 테스트 체크리스트를 넣었습니다. - labeler-action이 PR 제목에서
Feature,Fix,Design,Hotfix같은 단어를 찾아 라벨을 붙였습니다. - release-drafter가 prod로 머지된 PR을 라벨별로 묶어 릴리즈 노트 초안을 만들고,
Release:minor같은 라벨을 보고 다음 버전 번호를 계산했습니다.
2. 잘 굴러갔지만, 사람이 메우던 빈틈이 있었습니다
흐름 자체는 잘 동작했습니다. 운영에 나간 기능이 어떤 PR에서 왔는지 릴리즈 노트에서 바로 찾을 수 있었고, 버전 번호를 손으로 올리는 일도 없어졌습니다.
하지만 자동화가 기대는 입력은 전부 사람이 만들어야 했습니다. 문서에도 "labeler 설정 항목에 포함되지 않는 제목에는 레이블이 붙지 않는다"고 적어 두었습니다. 누군가 PR 제목을 규칙과 다르게 쓰면 라벨이 빠지고, 라벨이 빠지면 그 PR은 릴리즈 노트에서 분류 없이 맨 위로 떠올랐습니다. PR 템플릿의 체크박스도 비슷했습니다. "변경 사항에 대한 테스트를 했습니다"에 체크가 되어 있어도, 무엇을 어떻게 테스트했는지는 본문을 읽어 봐야 알 수 있었습니다.
QA 브랜치 세 개도 관리 비용이 있었습니다. 어느 QA 서버가 비어 있는지 확인하고, 테스트가 끝나면 초기화하는 일을 사람이 했습니다. 서버를 따로 띄워 주신 분이 있었기에 가능한 구조였습니다.
릴리즈 노트는 PR 제목을 모아 놓은 목록이었습니다. 개발자끼리 보기에는 충분했지만, 운영 담당자나 고객에게 그대로 보여 줄 수 있는 문장은 아니었습니다.
3. 에이전트와 일하면서 전제가 바뀌었습니다
지금 이 블로그 저장소를 보면 최근 커밋 40개가 모두 Claude Code와 함께 쓴 커밋입니다. 커밋 메시지 끝에 Co-Authored-By 줄이 붙어 있어서 바로 셀 수 있습니다. 제목은 docs(posts): ..., fix(markdown): ...처럼 타입과 범위를 붙이고 앞에 gitmoji를 단 형식으로 맞춰져 있는데, 이 형식을 지키는 건 이제 제가 아니라 에이전트입니다.
작업 공간도 달라졌습니다. Orca라는 앱으로 저장소마다 워크트리(worktree)를 만들고, 워크트리마다 에이전트를 하나씩 붙여 씁니다. 워크트리는 같은 저장소의 다른 브랜치를 다른 폴더에 펼쳐 두는 git 기능이라, 에이전트 두 개가 동시에 일해도 서로의 파일을 덮어쓰지 않습니다. 그러다 보니 브랜치가 사람 수만큼이 아니라 작업 수만큼 생깁니다.
11년 차 회고에 적었듯이, 스퀘어스에서 만든 PR 템플릿과 커밋 컨벤션은 지금 에이전트와 일할 때 그대로 쓰이고 있습니다. 사람에게 지키라고 만든 규칙이 에이전트에게는 더 잘 지켜집니다. 에이전트는 귀찮아하지 않으니까요. 이 경험이 브랜치 전략을 다시 짜는 출발점이 됐습니다.
4. 브랜치 구조는 남기고, QA 브랜치는 PR 미리보기로 바꾸는 편이 낫습니다
제품(솔루션)을 만드는 일에서는 dev, stg, prod 세 단계가 여전히 의미가 있다고 봅니다. 고객사나 발주처에 나가기 전에 릴리즈 후보를 묶어 두고 검증하는 단계는 AI가 코드를 쓴다고 사라지지 않습니다. 오히려 코드가 빨리 늘어나는 만큼 stg에서 한 번 멈추는 단계가 더 중요해졌습니다.
바꾸는 게 좋아 보이는 건 QA 브랜치입니다. QA1, QA2, QA3처럼 고정된 브랜치와 서버를 돌려 쓰는 구조는 동시에 열리는 작업이 서너 개일 때까지만 버팁니다. 에이전트가 워크트리마다 브랜치를 만들기 시작하면 비어 있는 QA 서버를 찾는 일부터 병목이 됩니다. 그래서 고정 QA 브랜치 대신 PR마다 미리보기(preview) 환경을 하나씩 띄우고, PR이 닫히면 지우는 방식이 더 맞아 보입니다.
미리보기 환경을 만드는 방법은 배포 환경에 따라 크게 세 가지로 나뉩니다.
- 호스팅 플랫폼의 기본 기능을 쓰는 방법입니다. Vercel, Netlify, Cloudflare Pages 같은 서비스는 저장소를 연결해 두면 PR이나 브랜치마다 미리보기 주소를 자동으로 만들고, 그 주소를 PR에 코멘트로 달아 줍니다. 프론트엔드만 따로 배포하는 제품이라면 가장 손이 덜 갑니다.
- 정적 빌드 결과를 오브젝트 스토리지에 올리는 방법입니다. GitHub Actions에서 빌드한 결과를 S3 같은 저장소의
pr-123/경로에 올리고, CDN이나 웹 서버에서pr-123.preview.example.com처럼 PR 번호로 접근하게 합니다. API는 dev 서버를 같이 쓰고 화면만 PR별로 나누는 구성이라 비용이 적게 듭니다. - 컨테이너로 PR마다 환경을 통째로 띄우는 방법입니다. 쿠버네티스라면 PR 번호로 네임스페이스를 만들고, 그 안에 프론트엔드와 백엔드 이미지를 배포한 뒤 인그레스로 서브도메인을 연결합니다. 백엔드 변경까지 PR 단위로 확인할 수 있지만, 데이터베이스와 시드 데이터를 어떻게 줄지 정해야 해서 준비가 가장 많이 듭니다.
어느 방법이든 지켜야 할 것은 같습니다. PR이 열리거나 커밋이 올라오면 자동으로 배포하고, 주소를 PR에 남기고, PR이 머지되거나 닫히면 자동으로 정리하는 것입니다. 정리를 사람이 하게 두면 2024년의 "QA 브랜치 초기화"가 이름만 바꿔 다시 생깁니다.
미리보기 주소가 생기면 AI를 붙이기도 쉬워집니다. 배포가 끝난 뒤 에이전트가 그 주소에서 Playwright로 주요 화면을 열어 보고, 콘솔 오류와 스크린샷을 PR 코멘트로 남기게 할 수 있습니다. 예전에 QA 서버에서 사람이 하던 "일단 화면이 뜨는지" 확인을, 사람이 보기 전에 한 번 걸러 주는 역할입니다.
5. 규칙은 사람이 정하고, 지키는 일은 에이전트에게 맡깁니다
2024년 설정에서 가장 약했던 고리는 PR 제목이었습니다. AI 시대라면 정규식 labeler를 걷어 내고 AI가 PR 내용을 읽어 라벨을 고르게 하는 방법도 떠올릴 수 있습니다. 하지만 라벨은 버전 번호를 정하는 입력이라, 같은 PR에는 매번 같은 라벨이 붙어야 합니다. 그래서 반대 방향이 낫다고 봅니다. labeler와 release-drafter처럼 결과가 항상 같은 도구는 그대로 두고, 그 도구가 기대는 입력, 즉 브랜치 이름과 PR 제목과 본문을 에이전트가 규칙대로 만들게 하는 것입니다.
에이전트에게 규칙을 알려 주는 곳은 저장소 루트의 지침 파일입니다. Claude Code는 CLAUDE.md, 다른 에이전트들은 AGENTS.md를 작업 시작 때 읽습니다. 2024년 문서의 규칙에 에이전트와 일할 때 필요한 것을 더하면 이런 구성이 괜찮아 보입니다.
## 브랜치
- 작업 브랜치는 dev에서 만든다. 긴급 수정만 prod에서 만든다.
- 이름은 {종류}/{이슈번호}-{짧은-설명}. 종류는 feature, fix, refactor, chore, hotfix 중 하나.
예) feature/482-map-layer-toggle, hotfix/517-login-redirect
- 워크트리 하나에서는 브랜치 하나만 다룬다. 다른 작업이 생기면 새 워크트리를 만든다.
- 브랜치 하나는 PR 하나로 끝낸다. 작업 중 관련 없는 수정이 보이면 고치지 말고 이슈로 남긴다.
## 커밋
- 형식은 {타입}({범위}): {요약}. 타입은 feat, fix, refactor, style, docs, test, chore.
- 한 커밋에는 한 가지 이유의 변경만 담는다.
- 에이전트가 쓴 커밋에는 Co-Authored-By 줄을 남긴다.
## PR
- 제목은 [Feature], [Fix], [Design], [Refactor], [Hotfix] 중 하나로 시작한다. labeler가 이 단어로 라벨을 붙인다.
- 본문은 .github/pull_request_template.md 순서대로 채운다.
- 변경이 400줄을 넘으면 PR을 나눌 수 있는지 먼저 제안한다.
- 테스트 항목에는 체크만 하지 말고 실제로 실행한 명령과 결과를 붙인다.
- 화면 변경이 있으면 미리보기 주소에서 찍은 스크린샷을 붙인다.
## 하지 않는 일
- stg, prod 브랜치에 push하거나 머지하지 않는다. 릴리즈 PR은 사람이 연다.
- Release:major, Release:minor 라벨은 붙이지 않는다. 버전은 사람이 정한다.
- 강제 푸시(force push)와 다른 사람 브랜치의 히스토리 수정은 하지 않는다.
- hotfix는 prod에서 분리하고, prod로 가는 PR과 dev로 되돌리는 PR을 함께 연다.몇 가지는 이유를 덧붙여 둡니다.
브랜치 이름에 종류와 이슈 번호를 넣는 건 2024년 규칙 그대로입니다. 달라진 점은 이 이름을 사람이 아니라 에이전트가 짓는다는 것입니다. 이슈 번호만 알려 주면 에이전트가 이슈 제목을 읽고 짧은 설명을 붙일 수 있어서, 규칙이 조금 길어져도 부담이 없습니다.
"관련 없는 수정은 고치지 말고 이슈로 남긴다"는 에이전트 때문에 생긴 규칙입니다. 에이전트는 작업하다 눈에 띈 다른 문제까지 친절하게 고쳐 주는 경향이 있습니다. 그 친절이 쌓이면 PR이 커지고, 릴리즈 노트에 잡히지 않는 변경이 섞입니다.
PR 크기 기준은 숫자 자체보다 "나눌 수 있는지 먼저 묻는다"는 데 의미가 있습니다. 400줄은 사람이 한 번에 집중해서 리뷰할 수 있는 정도로 잡은 값이고, 저라면 처음 몇 주 PR 크기를 보고 다시 조정하겠습니다.
테스트 항목을 체크박스 대신 실행 결과로 바꾸는 이유도 있습니다. 에이전트는 "테스트했습니다"라고 쉽게 말합니다. 품질 게이트 글에서 정리한 것처럼 typecheck와 Playwright 결과를 직접 보는 게 가장 확실한데, PR 본문에 그 출력이 붙어 있으면 리뷰어도 같은 확인을 할 수 있습니다.
마지막 "하지 않는 일"은 지침 파일만으로는 부족합니다. 지침은 에이전트에게 하는 부탁이라, 7번에서 다룰 브랜치 보호 규칙으로 실제로 막아 두는 것까지 한 묶음으로 봐야 합니다.
6. PR 리뷰와 릴리즈 노트는 AI가 초안을 씁니다
라벨과 버전처럼 매번 같은 답이 나와야 하는 일은 기존 도구에 두고, 글을 쓰고 읽는 일은 AI에게 넘기는 구성이 괜찮아 보입니다. 붙일 곳은 두 군데입니다.
첫째는 dev로 들어오는 PR의 1차 리뷰입니다. Anthropic이 제공하는 Claude Code GitHub Action을 붙이면 PR이 열릴 때 에이전트가 변경 내용을 읽고 리뷰 코멘트를 남깁니다. 5번의 규칙과 묶으면 이런 설정이 됩니다.
name: AI Review
on:
pull_request:
branches: [dev]
types: [opened, synchronize]
jobs:
review:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
id-token: write
steps:
- uses: actions/checkout@v4
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: |
이 PR을 리뷰해 줘. CLAUDE.md의 브랜치와 PR 규칙을 지켰는지,
PR 본문의 테스트 결과가 실제 변경과 맞는지를 먼저 보고,
버그 가능성이 있는 곳만 코멘트로 남겨 줘.저도 아직 실제 저장소에 붙여 보지 않은 설정이라, 적용할 때 공식 문서와 입력값을 다시 맞춰 볼 예정입니다. 리뷰를 AI에게 통째로 넘기는 구성은 아닙니다. 사람이 리뷰하기 전에 규칙 위반과 눈에 띄는 실수를 걸러 주는 1차 필터로 두는 쪽이 맞다고 봅니다.
둘째는 릴리즈 노트입니다. release-drafter가 만든 초안은 PR 제목 목록이라 개발자용으로는 충분합니다. 여기에 한 단계를 더해, 같은 초안을 AI가 운영 담당자나 발주처가 읽을 문장으로 다시 쓰게 하는 방식이 괜찮아 보입니다. 예를 들어 "Fix: grid 이동 수정" 같은 항목을 "격자를 움직일 때 위치가 어긋나던 문제를 고쳤습니다"처럼 바꾸는 식입니다. 개발자용 릴리즈 노트는 GitHub에 그대로 두고, 사용자용은 따로 저장해 공지에 씁니다. 원문이 사람이 정한 라벨과 PR 제목이라 AI가 없는 내용을 지어낼 여지도 적습니다. PM을 하면서 발주처에 변경 내역을 설명할 일이 많아져서, 이 글의 제안 중 제가 가장 먼저 해 보고 싶은 부분입니다.
7. 머지 버튼과 운영 반영은 사람이 쥐고 있습니다
이틀 전에 이 블로그에 글을 올리면서 겪은 일이 있습니다. 에이전트가 글을 커밋하고 main에 푸시하는 것까지는 잘 진행됐는데, 운영 데이터베이스에 글을 반영하는 명령을 실행하려는 순간 Claude Code의 권한 확인에서 막혔습니다. 운영 배포에 해당하는 작업이라 사람이 직접 허락해야 한다는 이유였습니다. 제가 확인하고 실행을 허락한 뒤에야 반영이 끝났습니다.
처음엔 한 번 더 눌러야 해서 번거롭다고 생각했습니다. 하지만 돌아보면 브랜치 전략에서도 똑같이 지켜야 할 선이었습니다. 에이전트가 코드를 쓰고, PR을 열고, 리뷰 초안을 쓰는 것까지는 맡겨도 됩니다. stg와 prod로 머지하는 일, 그리고 메이저와 마이너 중 어떤 버전을 올릴지 정하는 일은 사람이 해야 합니다. 2024년 설정에서 Release:major, Release:minor 라벨을 사람이 직접 붙이게 한 것도 그대로 유지합니다.
그래서 이 선은 문서로만 두지 않고 GitHub의 브랜치 보호 규칙(branch protection)으로 걸어 두는 게 맞다고 봅니다. stg와 prod는 PR로만 머지되게 하고, 승인 한 명 이상과 4번의 미리보기 확인, 6번의 AI 리뷰 통과를 필수 조건으로 둡니다. CLAUDE.md에 "push하지 않는다"고 적는 것은 에이전트에게 하는 부탁이고, 브랜치 보호 규칙은 실제로 막는 장치입니다. 둘 다 있어야 마음이 놓입니다.
마치며
2024년 문서를 다시 읽으면서, 그때 만든 구조가 생각보다 오래 버틴다는 게 반가웠습니다. 다시 짜 봐도 브랜치 단계와 라벨, release-drafter는 대부분 그대로 남았습니다. 달라진 건 고정 QA 서버 대신 PR 미리보기를 쓰는 것과, 그 구조를 굴리는 손이었습니다. 제목 규칙을 지키고, 템플릿을 채우고, 릴리즈 노트를 다듬는 일은 사람이 늘 빠뜨리던 일이었는데, 이제는 에이전트에게 맡길 수 있게 됐습니다.
제가 지금 실제로 하고 있는 건 커밋 규칙을 에이전트에게 맡기는 것과 워크트리마다 브랜치를 나눠 쓰는 것까지입니다. 이 글에 적은 지침 파일 규칙, PR 미리보기 환경, AI 1차 리뷰, 사용자용 릴리즈 노트는 다음 사업 저장소에서 차례로 붙여 볼 계획이고, 써 본 뒤에 무엇이 그대로 남았는지 이 글에 덧붙이겠습니다.
Comments (0)