형상관리 브랜치 규칙 정리

형상관리에서 규칙 정의가 필요한 항목

작업 브랜치 네이밍 룰 확정
커밋 메시지 형식 지정
브랜치 역할과 병합 규칙 확정

작업 브랜치 네이밍 룰

dictionary-app, dictionary-api 저장소에서 사용 중인 규칙을 기준으로 정리한다.

브랜치 이름은 {type}/{설명} 형식으로 짓는다. 날짜 토큰은 넣지 않는다 — 같은 이름이 이미 있으면 설명을 더 구체적으로 바꾼다.
{type}은 커밋 타입(아래 11개 타입)과 의미가 대응하되, 브랜치에서만 두 가지를 다르게 쓴다. 커밋 메시지의 type은 항상 원래 타입 그대로 쓴다.
- feat → feature (예: feature/guest-login)
- 긴급 수정 → fix 대신 hotfix (예: hotfix/prod-crash). 긴급하지 않은 버그 수정은 fix 그대로 쓴다.
- 나머지(build/chore/ci/docs/perf/refactor/revert/style/test)는 커밋 타입과 같은 이름을 쓴다.
{설명}은 소문자 케밥 케이스로, 핵심 변경 내용을 2~4단어로 요약한다(예: docs/branch-guide).
병합 후에도 삭제하지 않는 장기 유지 브랜치(/git-start로 생성)에는 브랜치 전용 타입 release·env도 쓸 수 있다(예: release/2026-q1, env/staging-mirror). 이 두 타입은 커밋 타입으로는 쓰지 않는다.

커밋 메시지 형식

Conventional Commits 형식(type(scope): subject)을 따른다. 허용 타입은 11개(build/ chore/ci/docs/feat/fix/perf/refactor/revert/style/test)다. commitlint 같은 검사 도구는 두지 않으므로 이 규칙을 직접 지킨다.
제목의 요약 부분(type(scope): 접두사 제외)은 50자 이내의 한국어 명령형으로 작성한다. scope는 선택 사항이다.
서로 다른 관심사(기능 추가/버그 수정/문서 정리 등)는 하나의 커밋에 섞지 않고 목적 단위로 분리해서 커밋한다.

브랜치 역할과 병합 규칙

master

평소 작업이 쌓이는 통합 브랜치. push해도 배포는 트리거되지 않는다.

작업 브랜치

기능 추가/버그 수정/문서 작성 등 목적이 있는 모든 작업은 master에서 분기해서 진행한 뒤 master로 병합한다. 삭제 기준은 아래 5번 규칙을 따른다.

deploy

실제 배포를 트리거하는 브랜치. 배포 시점은 사람이 판단하고, master를 deploy로 병합·푸시하는 실행은 /git-deploy 스킬로 AI에게 위임할 수 있다. 이 브랜치에는 직접 커밋하지 않는다.

flowchart LR
  work["작업 브랜치<br/>feature/… · fix/… · docs/…"]
  master["master"]
  deploy["deploy"]
  release["배포<br/>(GitHub Pages / Render)"]

  master -- "분기" --> work
  work -- "--no-ff 병합" --> master
  master -- "--no-ff 병합<br/>(배포 시점은 사람이 판단)" --> deploy
  deploy -- "push" --> release
  deploy -. "역병합 금지" .-x master
  work -. "직접 병합 금지" .-x deploy

병합은 항상 git merge --no-ff로 실행한다(fast-forward 금지). git rebase는 사용하지 않는다.
작업 브랜치는 오직 master로만 병합할 수 있다. deploy를 포함해 다른 브랜치로 직접 병합하는 것은 금지한다.
master에 변경이 반영되는 경로는 (1) 작업 브랜치의 --no-ff 병합, (2) PR 병합 이 둘뿐이다. master에 체크아웃한 채 직접 커밋/cherry-pick/revert/rebase하는 것은 금지한다.
병합 방향은 항상 master → deploy뿐이다. deploy에서 master로의 역병합·push는 예외 없이 금지한다.
병합을 진행한 실행 안에서 새로 분기한 작업 브랜치는 master에 병합한 뒤 바로 삭제한다. 병합 시점에 이미 있던 브랜치(/git-commit으로 커밋을 쌓아둔 브랜치, /git-start로 만든 장기 유지 브랜치 등)는 자동으로 삭제하지 않고 사용자가 판단한다.
“커밋해줘”와 “병합해줘”는 별개의 요청이다. 커밋 요청만으로는 master(또는 deploy)로 병합하지 않으며, 병합은 별도로 요청받았을 때만 진행한다.

AI용 Git 스킬

위 규칙은 .claude/skills/git-* 스킬 4개(/git-start·/git-commit·/git-publish·/git-deploy)로 AI가 실행한다. 네 스킬 모두 자동으로 호출되지 않고, 사용자가 /스킬명으로 직접 실행했을 때만 동작한다. 스킬별 용도와 사용 시점은 AI용 Git 스킬, 스킬을 만드는 방법은 하네스 개발 방법론 참고.