AI용 Git 스킬

깃 브랜치 전략의 규칙(작업 브랜치에서 작업, master로 --no-ff 병합, deploy로 배포)을 AI(Claude Code)가 대신 실행할 수 있도록 모든 프로젝트에 같은 이름의 스킬 4개를 둔다. 스킬 문서는 각 저장소의 .claude/skills/git-*/SKILL.md에 있다.

한눈에 보기

스킬	용도	하는 일	하지 않는 일
`/git-start <브랜치명>`	오래 유지할 브랜치 만들기	`master`를 최신으로 맞춘 뒤 지정한 이름으로 브랜치를 만들어 전환	커밋, 병합, push
`/git-commit`	작업 브랜치에 커밋만 하기	변경 내용을 분석해 커밋 메시지를 작성하고, 맥락별로 나눠 커밋	브랜치 생성·전환, 병합, push
`/git-publish`	작업을 `master`에 올리기	커밋 → `master`에 `--no-ff` 병합 → 원격 `master`에 push	`deploy` 병합
`/git-deploy`	배포하기	`master`를 `deploy`에 `--no-ff` 병합 → 원격 `deploy`에 push(배포 트리거)	새 커밋 작성, `master` 변경

flowchart LR
  master["master"]
  work["작업 브랜치"]
  long["장기 유지 브랜치<br/>(release/… · env/…)"]
  deploy["deploy"]
  release["배포"]

  master -- "/git-start 브랜치명" --> long
  master -- "/git-publish<br/>(브랜치 자동 생성)" --> work
  work -- "/git-commit" --> work
  long -- "/git-commit" --> long
  work -- "/git-publish<br/>(--no-ff 병합 + push)" --> master
  long -- "/git-publish<br/>(--no-ff 병합 + push)" --> master
  master -- "/git-deploy<br/>(--no-ff 병합 + push)" --> deploy
  deploy --> release

스킬별 용도

`/git-start` — 오래 유지할 브랜치 만들기

병합한 뒤에도 지우지 않고 계속 쓸 브랜치(릴리스 브랜치, 특정 환경 전용 브랜치 등)를 만들 때 쓴다.
브랜치 이름을 반드시 인자로 받는다 — 이름을 자동으로 짓지 않는다. 이름이 규칙에 맞지 않거나 같은 이름이 로컬·원격에 이미 있으면 만들지 않는다.
master 위에서, 커밋되지 않은 변경이 없을 때만 동작한다.
평소의 짧은 작업에는 쓰지 않는다 — 그런 작업 브랜치는 /git-publish가 알아서 만들고 지운다.

`/git-commit` — 커밋만 하기

작업을 여러 번 나눠 커밋해두고, master 병합은 나중에 한 번에 하고 싶을 때 쓴다.
변경 내용을 읽고 Conventional Commits 형식의 한국어 커밋 메시지를 직접 작성한다. 서로 다른 맥락(예: 문서 수정과 설정 변경)이 섞여 있으면 커밋을 나눈다.
현재 브랜치에 그대로 커밋한다. master나 deploy 위에서는 커밋하지 않고 중단한다 — 이때는 작업 브랜치로 먼저 전환하거나 /git-publish를 쓴다.

`/git-publish` — 작업을 `master`에 올리기

작업을 마치고 master에 반영할 때 쓴다. 가장 자주 쓰는 스킬이다.
master 위에서 실행하면 변경 내용에 맞는 이름으로 작업 브랜치를 자동으로 만들고, 커밋 → 병합 → push까지 한 번에 진행한 뒤 그 브랜치를 지운다.
이미 작업 브랜치(/git-commit으로 커밋을 쌓아둔 브랜치, /git-start로 만든 브랜치 등) 위에서 실행하면, 남은 변경만 커밋하고(없으면 건너뛴다) 병합과 push를 진행한다. 이 경우 브랜치는 지우지 않는다.
병합 직전에 로컬 master를 원격 최신 상태로 맞춘다. 로컬과 원격이 갈라져 있으면 자동으로 처리하지 않고 중단한다.
어느 브랜치 위에서 실행하느냐에 따라 동작이 두 패턴으로 나뉜다 — 아래 /git-publish의 두 가지 병합 패턴 참고.

`/git-deploy` — 배포하기

master에 쌓인 변경을 실제로 배포할 때 쓴다. 배포 시점은 사람이 정하고, 실행만 AI에게 맡긴다.
원격에 이미 push된 master만 배포한다. 로컬 master에 아직 push하지 않은 커밋이 있으면 중단하고 /git-publish를 먼저 하도록 안내한다.
병합 방향은 항상 master → deploy뿐이다. 이번에 deploy로 들어갈 커밋 목록을 보여준 뒤 병합하고, 끝나면 master로 돌아온다.

`/git-publish`의 두 가지 병합 패턴

/git-publish는 실행한 순간의 현재 브랜치를 보고 동작을 정한다. master 위에서 실행하면 작업 브랜치를 이번 실행 안에서 만들고 지우는 패턴 A, 작업 브랜치 위에서 실행하면 이미 있는 브랜치를 병합만 하고 남겨두는 패턴 B로 진행한다. deploy 위에서는 어떤 단계도 진행하지 않는다.

flowchart TD
  start["/git-publish 실행"] --> env{"gh 로그인과<br/>user.name/email이 준비됐는가?"}
  env -- "아니오" --> stop1["중단"]
  env -- "예" --> br{"현재 브랜치는?"}
  br -- "deploy" --> stop2["중단<br/>(직접 master로 전환한 뒤 다시 실행)"]
  br -- "master" --> patternA["패턴 A<br/>master 위에서 병합"]
  br -- "그 외" --> patternB["패턴 B<br/>작업 브랜치 위에서 병합"]

작업 브랜치인지는 이름 형식이 아니라 master·deploy가 아닌지로만 판단한다. feature/… 같은 자동 이름이든 /git-start로 만든 release/…든 직접 만든 브랜치든, 그 위에서 실행하면 모두 패턴 B다.

패턴 A — `master` 위에서 병합하는 경우

master에서 바로 작업하고, 한 번의 실행으로 커밋부터 push까지 끝내고 싶을 때의 패턴이다. 작업 브랜치는 이번 실행 안에서 잠깐 쓰고 지우는 임시 브랜치다.

flowchart TD
  a0{"커밋되지 않은<br/>변경이 있는가?"}
  a0 -- "없음" --> a1{"push되지 않은<br/>로컬 master 커밋이 있는가?"}
  a1 -- "없음" --> a2["'커밋할 변경사항이 없습니다'<br/>안내 후 종료"]
  a1 -- "있음" --> a3["git push origin master만 실행<br/>(브랜치 생성·커밋·병합 없음)"]
  a0 -- "있음" --> a4["git fetch<br/>git merge --ff-only origin/master"]
  a4 -- "실패 (로컬과 원격이 갈라짐)" --> a5["중단"]
  a4 -- "성공" --> a6["작업 브랜치 이름 결정<br/>(로컬·원격에 같은 이름이 있는지 확인)"]
  a6 --> a7["git switch -c 작업 브랜치<br/>(변경사항은 그대로 따라온다)"]
  a7 --> a8["git add -A<br/>맥락별로 나눠 커밋"]
  a8 --> a9["git switch master<br/>git merge --no-ff 작업 브랜치<br/>(기본 병합 메시지)"]
  a9 --> a10["git branch -d 작업 브랜치"]
  a10 --> a11["git push origin master"]

master를 먼저 원격에 맞춘다. 커밋되지 않은 변경이 있으면 git fetch 후 git merge --ff-only origin/master로 로컬 master를 최신 상태로 만든다. 로컬과 원격이 갈라져 fast-forward가 안 되면 자동으로 병합하지 않고 멈춘다.
작업 브랜치를 자동으로 만든다. 변경 내용을 보고 <type>/<설명> 형식으로 이름을 짓고, 로컬과 원격에 같은 이름이 없는지 확인한 뒤 git switch -c로 만든다. 커밋되지 않은 변경은 브랜치를 바꿔도 작업 트리에 그대로 남아 있으므로, 새 브랜치에서 이어서 커밋한다.
맥락별로 나눠 커밋한다. 문서 수정과 설정 변경처럼 목적이 다른 변경은 같은 브랜치 안에서 커밋만 나눈다 — 커밋마다 브랜치를 새로 만들지 않는다.
기본 병합 메시지로 병합한다. 이번 실행에서 만든 커밋들이라 내용이 분명하므로 git 기본 메시지 (Merge branch '<작업 브랜치>')를 그대로 쓴다.
브랜치를 지운다. 이번 실행에서 직접 만든 브랜치이므로 병합 후 git branch -d로 반드시 지운다.
변경이 없을 때의 예외. 커밋할 변경이 없는데 이전 실행에서 push에 실패해 남은 로컬 커밋이 있으면, 브랜치를 만들지 않고 그 커밋만 push한다. 그것도 없으면 할 일이 없다고 알리고 끝낸다.

---
config:
  gitGraph:
    mainBranchName: master
---
gitGraph
  commit id: "이전 작업"
  branch docs/form-guide
  commit id: "docs(dev-guide): 폼 가이드 추가"
  commit id: "chore(config): 설정 변경"
  checkout master
  merge docs/form-guide id: "Merge branch docs/form-guide"

한 번의 실행으로 위 이력이 만들어지고, 병합 뒤 docs/form-guide 브랜치는 로컬에서 삭제된다(작업 브랜치는 원격에 push하지 않는다).

패턴 B — 작업 브랜치 위에서 병합하는 경우

이미 작업 브랜치가 있고, 거기에 쌓인 커밋을 master로 올릴 때의 패턴이다. 주로 /git-commit으로 커밋을 여러 번 나눠 쌓은 뒤, 또는 /git-start로 만든 장기 유지 브랜치에서 작업한 뒤 실행한다. 브랜치는 병합한 뒤에도 그대로 남긴다.

flowchart TD
  b0["git fetch origin master:master<br/>(브랜치 전환 없이 로컬 master만 갱신)"]
  b0 -- "성공" --> b3
  b0 -- "거부 (non-fast-forward)" --> b1{"origin/master가<br/>로컬 master의 조상인가?"}
  b1 -- "예 (로컬이 앞서 있을 뿐)" --> b2["갱신 건너뜀<br/>앞선 커밋은 이번 push에 함께 나감"]
  b2 --> b3
  b1 -- "아니오 (갈라짐)" --> b1stop["중단"]
  b3{"커밋되지 않은<br/>변경이 있는가?"}
  b3 -- "있음" --> b4["git add -A<br/>맥락별로 나눠 커밋"]
  b3 -- "없음 (커밋 단계 건너뜀)" --> b6
  b4 --> b6["git switch master"]
  b6 --> b7{"master에 없는<br/>브랜치 커밋 수"}
  b7 -- "1개" --> b8["git merge --no-ff 브랜치<br/>(기본 병합 메시지)"]
  b7 -- "2개 이상" --> b9["git merge --no-ff 브랜치 -m 요약 메시지<br/>(본문에 각 커밋 제목 나열)"]
  b8 --> b10["브랜치는 삭제하지 않음"]
  b9 --> b10
  b10 --> b11["git push origin master"]

브랜치를 벗어나지 않고 master만 맞춘다. 작업 브랜치 위에 있으므로 master로 전환하지 않고 git fetch origin master:master로 로컬 master 참조만 원격 최신 상태로 갱신한다.
- 거부되면 로컬 master가 원격보다 앞서 있을 뿐인지(원격이 로컬의 조상), 실제로 갈라졌는지 구분한다. 앞서 있을 뿐이면 그대로 진행하고 — 그 커밋들은 이번 push에 함께 나간다 — 갈라졌으면 멈춘다.
남은 변경만 커밋한다. 커밋되지 않은 변경이 있으면 패턴 A와 같은 방식으로 맥락별로 나눠 커밋한다. 변경이 전혀 없으면(이미 /git-commit으로 다 커밋해둔 경우) 커밋 단계를 건너뛰고 바로 병합한다 — 패턴 A와 달리 “커밋할 변경사항이 없습니다”로 끝내지 않는다.
병합 메시지를 커밋 수에 맞춘다. master로 전환한 뒤 git log master..<브랜치>로 병합될 커밋 수를 센다.
- 1개면 git 기본 병합 메시지를 쓴다.
- 2개 이상이면 type: 요약 형식의 제목과, 본문에 이번에 합쳐지는 각 커밋의 제목을 한 줄씩 적은 약식 메시지를 직접 지정한다. 이전 세션에서 쌓은 커밋들이라 병합 커밋만 보고도 무엇이 들어왔는지 알 수 있게 하기 위해서다.
브랜치를 지우지 않는다. 이름만으로는 /git-start로 만든 장기 유지 브랜치인지 알 수 없으므로, 실수로 지워 이력을 잃지 않도록 항상 남겨둔다. 지울지는 사용자가 따로 판단한다.

---
config:
  gitGraph:
    mainBranchName: master
---
gitGraph
  commit id: "이전 작업"
  branch feature/search-page
  commit id: "/git-commit ①"
  commit id: "/git-commit ②"
  checkout master
  merge feature/search-page id: "요약 병합 메시지"
  checkout feature/search-page
  commit id: "/git-commit ③"
  checkout master
  merge feature/search-page id: "기본 병합 메시지"

브랜치가 남아 있으므로 같은 브랜치에서 작업을 이어가다 다시 /git-publish로 병합할 수 있다. 위 예시에서 첫 병합은 커밋이 2개라 요약 메시지를, 두 번째 병합은 새 커밋이 1개라 기본 메시지를 쓴다.

두 패턴 비교

항목	패턴 A (`master` 위)	패턴 B (작업 브랜치 위)
주로 쓰는 경우	한 번에 끝나는 작업	`/git-commit`으로 나눠 쌓은 작업, 장기 유지 브랜치
작업 브랜치	이번 실행에서 자동으로 만듦	이미 있는 브랜치를 그대로 씀
`master` 동기화	`git merge --ff-only origin/master`	`git fetch origin master:master` (브랜치 전환 없음)
커밋할 변경이 없을 때	남은 로컬 커밋만 push하거나 종료	커밋을 건너뛰고 병합 진행
병합 메시지	항상 git 기본 메시지	커밋 1개면 기본, 2개 이상이면 요약 메시지
병합 후 브랜치	삭제 (`git branch -d`)	남겨둠

상황별 사용법

상황	순서
한 번에 끝나는 작업	`master`에서 작업 → `/git-publish`
여러 번 나눠 커밋하는 작업	작업 브랜치에서 `/git-commit` 반복 → 마지막에 `/git-publish`
오래 유지할 브랜치에서의 작업	`/git-start release/2026-q1` → `/git-commit` 반복 → `/git-publish`
배포	`/git-publish`로 `master` push 완료 → `/git-deploy`

모든 스킬에 공통인 원칙

사용자가 직접 실행할 때만 동작한다. 네 스킬 모두 AI가 스스로 판단해 호출하지 않고, 사용자가 /스킬명으로 실행해야 한다.
push는 /git-publish와 /git-deploy만 한다. 이 두 스킬 밖에서 AI가 git push나 gh pr merge처럼 GitHub 인증이 필요한 원격 쓰기를 하는 것은 금지한다. 두 스킬은 gh auth login으로 미리 인증된 환경을 전제로 하며, 토큰 값을 프롬프트에 붙여넣지 않는다.
실행 전에 환경부터 확인한다. git 사용자 정보(user.name/user.email)가 없거나, push하는 스킬인데 gh 로그인이 안 되어 있으면 아무것도 하지 않고 중단한다 — 로컬 작업을 다 끝낸 뒤 마지막 push에서야 실패하는 상황을 막기 위해서다.
master와 deploy에는 직접 커밋하지 않는다. 커밋은 항상 작업 브랜치에서 하고, 두 브랜치에는 병합 커밋만 생긴다.
병합은 항상 --no-ff, 원격과 맞추는 동기화는 항상 --ff-only로 한다. rebase와 squash 병합은 쓰지 않는다.
문제가 생기면 멈추고 알린다. 병합 충돌은 git merge --abort로 되돌린 뒤 충돌 파일을 보고하고, push가 거부되면 강제 push하지 않는다. 브랜치를 전환하는 스킬(/git-start, /git-deploy)은 커밋되지 않은 변경이 있으면 stash하거나 커밋하지 않고 중단한다.