깃 브랜치 전략

mintchoco-guid(이 사이트) 자신과 dictionary-api/dictionary-app(참조 프로젝트) 모두 같은 기본 원칙을 쓴다 — 세부 구현(강제 방법)만 프로젝트마다 다르다.

master는 통합 브랜치다 — 여기에 직접 커밋(일반 커밋, --amend, cherry-pick, revert 포함)하지 않는다. 반영 경로는 (1) 작업 브랜치를 병합하는 것과 (2) GitHub PR을 병합하는 것 둘뿐이다.
배포가 필요한 프로젝트는 deploy(또는 그에 준하는) 브랜치를 별도로 둔다 — master push가 배포를 트리거하지 않게 해서, 평소 작업과 “지금 배포한다”는 결정을 분리한다.
기능 추가/버그 수정/문서 정리 등 목적이 있는 모든 작업은 master에서 작업 브랜치를 분기해서 진행한 뒤 master로 병합하고, 병합 후 작업 브랜치를 삭제한다.
작업 브랜치는 오직 master로만 병합한다 — deploy를 포함해 다른 브랜치로 직접 병합하는 것은 금지한다. deploy에는 항상 master를 거친 변경만 들어가야 한다.
병합은 항상 git merge --no-ff로 실행한다 — fast-forward가 가능해도 항상 병합 커밋(부모 2개)을 남기도록 강제한다. git log --graph만 봐도 어떤 브랜치가 언제 병합됐는지 드러나고, git branch --merged로 병합 여부를 판별하기도 쉬워진다. git rebase는 쓰지 않는다 — rebase 없이는 fast-forward를 강제로 만들 수 없으므로, --no-ff를 쓰면 이 문제 자체가 생기지 않는다.

<type>/<설명> 형식 — <type>은 커밋 타입(Conventional Commits)과 의미가 대응한다.
<설명>은 소문자 케밥 케이스로, 핵심 변경 내용을 2~4단어로 요약한다.
프로젝트에 따라 날짜를 끼워 넣기도 한다 — 이 사이트(mintchoco-guid)는 같은 날 여러 작업 브랜치가 만들어질 수 있어 <type>/<YYYYMMDD>/<kebab-case-설명>(예: docs/20260913/session-guide)을 쓰고, dictionary-api/dictionary-app은 <type>/<설명>(예: feature/guest-login)만 쓴다 — feat 대신 feature로 풀어 쓰는 점만 다르다.

같은 “master 직접 커밋 금지 + --no-ff 병합” 원칙을, 프로젝트마다 다른 기술로 강제한다.

git 훅으로 강제 — dictionary-api는 pre-commit 훅이 .git/MERGE_HEAD 존재 여부로 “지금 이 커밋이 병합 중인가”를 판별해, 병합이 아닌데 현재 브랜치가 master면 커밋 자체를 차단한다. 자세한 스크립트는 깃훅 가이드 참고.
Claude Code 훅으로 강제 — dictionary-app은 .claude/hooks/block-master-direct-commit.sh를 PreToolUse(Bash) 훅으로 등록해, 현재 브랜치가 master일 때 AI가 커밋 계열 명령을 직접 실행하려 하면 기술적으로 차단한다(git merge/status/log/push 등 비커밋 명령은 막지 않는다). git 훅과 달리 “AI가 이 저장소에서 직접 커밋하는 것”만 겨냥한 방식이다.
스킬 문서로 안내 — mintchoco-guid(이 사이트)는 별도 기술적 차단 장치 없이, /git-publish 스킬(.claude/skills/git-publish/SKILL.md)이 커밋 전 현재 브랜치를 확인해 보호 브랜치면 작업 브랜치를 먼저 만들도록 안내한다.

master → deploy 병합은 사람이 직접 판단해서 그때그때 수행한다 — 정해진 주기 없이, “지금 배포한다”고 결정한 시점에만 진행한다.
이 병합도 --no-ff로 실행해 병합 이력을 남긴다.
병합 방향은 항상 master → deploy 하나뿐이다 — deploy에서 master로 역방향 병합하지 않는다.
Terminal window
```
git switch deploy
git merge --no-ff master
git push origin deploy
```