Claude Code 커스텀 명령어 가이드: Git 워크플로우 자동화

📖 예상 읽기 시간: 5분

개요

이 문서는 ~/.claude/commands에 정의된 두 가지 커스텀 명령어인 commit.md와 push.md를 소개합니다. 이 명령어들은 Claude Code에서 /commit, /push로 호출되어 반복적인 Git 작업을 자동화합니다.

1. commit.md - 스마트 커밋 자동화

기능 요약

/commit 명령어는 변경된 파일을 분석하고, 빌드를 검증한 후, 일관된 형식의 커밋 메시지를 자동 생성합니다.

실행 흐름

git status → 서브모듈 처리 → git diff 분석 → 파일 선택 확인 → 빌드 검증 → 커밋

핵심 기능

기능	설명
변경사항 자동 분석	`git status`와 `git diff`로 변경 내용을 파악
서브모듈 우선 처리	grpc-idl 같은 서브모듈이 있으면 먼저 커밋
설정 파일 필터링	`.yml`, `.yaml`, `.xml`, `.log` 파일은 포함 여부를 사용자에게 확인
빌드 검증 필수	`./gradlew compileKotlin compileTestKotlin` 성공 시에만 커밋 진행
커밋 메시지 자동 생성	브랜치명 기반으로 일관된 형식의 메시지 작성

커밋 메시지 형식

feat({브랜치명}): 커밋내용 요약
- 상세 커밋 내용

브랜치명에서 prefix는 자동 제거됩니다.

feature/news → news
bugfix/login-issue → login-issue

결과물

commit.md

변경된 파일들을 분석하고 자동으로 커밋해줘:

**중요**: 4번과 7번 과정을 제외한 나머지 과정(1~3, 5~6)은 사용자에게 질문 없이 자동으로 진행
**중요**: TodoWrite 도구 사용 금지 - 진행 상황은 최종 결과 테이블로만 표시

1. git status로 변경/추가된 파일 확인
2. 서브모듈(예: grpc-idl)에 변경 사항이 있으면 서브모듈 디렉토리에서 먼저 커밋
3. git diff로 변경 내용 분석
4. **파일 선택 확인**: 변경된 파일 중 `.yml`, `.yaml`, `.xml`, `.log` 파일이 있으면 커밋에 포함할지 사용자에게 질문
5. **빌드 확인 (필수)**: `./gradlew compileKotlin compileTestKotlin` 실행하여 빌드 성공 확인
   - 빌드 실패 시 오류를 먼저 수정하고 다시 빌드 확인
6. 빌드 성공 후 변경 내용을 기반으로 명확한 커밋 메시지 작성
7. git add 및 git commit 실행 (서브모듈 포인터 포함, 4번에서 제외한 파일은 커밋에서 제외)

브랜치명은 `git branch --show-current`로 확인하고, `feature/`, `bugfix/`, `hotfix/` 등의 prefix는 제외한 실제 이름만 사용해서 아래 커밋 메세지 형식을 토대로 커밋 메세지를 작성해줘.
예: `feature/news` → `news`, `bugfix/login-issue` → `login-issue`

커밋 메시지 형식:

feat({브랜치명}): 커밋내용 요약

상세 커밋 내용 ```

> subModule이 없는 프로젝트라면 2번 과정은 제외하는 것이 깔끔하다

---

## 2. push.md - 다중 브랜치 배포 자동화

### 기능 요약

`/push {브랜치명}` 명령어는 작업 브랜치를 dev, qa, qc 환경 브랜치에 순차적으로 머지하고 푸시합니다.

### 실행 흐름

브랜치 확인 → 작업 브랜치 푸시 → dev 머지/빌드/푸시 → qa 머지/빌드/푸시 → qc 머지/빌드/푸시 → 원래 브랜치 복귀

### 핵심 기능

| 기능 | 설명 |
|------|------|
| **브랜치 자동 감지** | 인자 미지정 시 현재 브랜치 사용 여부 확인 |
| **순차적 환경 배포** | dev → qa → qc 순서로 안전하게 진행 |
| **각 단계별 빌드 검증** | 머지 후 빌드 실패 시 자동 롤백 |
| **충돌 감지 및 알림** | 머지 충돌 발생 시 작업 중단 및 사용자 알림 |
| **진행 상황 시각화** | ✅ 성공 / ❌ 실패 / 🔄 진행 중 표시 |

### 안전장치

- 푸시할 커밋이 없으면 작업 즉시 종료
- 빌드 실패 시 `git reset --hard`로 롤백
- 충돌 시 수동 해결 요청

---

## 3. 왜 Git 워크플로우 자동화가 필요한가?

### 수동 작업의 문제점

개발자가 하루에 수행하는 Git 작업을 생각해보면, 커밋 한 번에 5~10분, 다중 브랜치 배포에 15~30분이 소요됩니다. 이 과정에서 여러 문제가 발생합니다.

**휴먼 에러 위험**: 빌드 확인 없이 커밋, 잘못된 브랜치에 푸시, 설정 파일 실수로 포함 등의 실수가 빈번합니다.

**일관성 부재**: 팀원마다 다른 커밋 메시지 스타일, 배포 순서 혼란 등이 발생합니다.

**컨텍스트 스위칭 비용**: 코딩 → Git 작업 → 코딩으로 돌아오는 과정에서 집중력이 분산됩니다.

### 자동화의 가치

| 측면 | 수동 작업 | 자동화 후 |
|------|----------|----------|
| **커밋 소요 시간** | 5~10분 | 1~2분 |
| **다중 브랜치 배포** | 15~30분 | 3~5분 |
| **빌드 검증 누락** | 가끔 발생 | 0% (강제 검증) |
| **커밋 메시지 일관성** | 팀원마다 상이 | 100% 통일 |

---

## 4. 이 명령어들의 장점

### 품질 보장

빌드 검증이 워크플로우에 내장되어 있어 컴파일 에러가 있는 코드가 커밋되거나 배포되는 것을 원천 차단합니다. 이는 CI/CD 파이프라인 실패를 사전에 예방합니다.

### 운영 안정성

push.md는 dev → qa → qc 순서를 강제하고, 각 단계마다 빌드를 검증합니다. 실패 시 자동 롤백되므로 환경이 오염되지 않습니다.

### 개발자 경험 향상

반복적이고 지루한 작업을 AI에게 위임하여 개발자는 비즈니스 로직에 집중할 수 있습니다. 특히 서브모듈 처리나 다중 브랜치 배포 같은 복잡한 작업에서 효과가 큽니다.

### 팀 표준화

커밋 메시지 형식과 배포 절차가 명령어에 정의되어 있어 팀 전체가 동일한 방식으로 작업하게 됩니다. 신규 팀원 온보딩 시간도 단축됩니다.
![](https://velog.velcdn.com/images/skysoo/post/6ebb49e5-e9ca-48e6-a350-1b220e3db387/image.png)
![](https://velog.velcdn.com/images/skysoo/post/c216caf1-ca6c-4f15-9f5b-d8b22b9bafe0/image.png)
![](https://velog.velcdn.com/images/skysoo/post/9f2a266e-a114-4814-a65e-88f328fe8aac/image.png)

## push.md
```markdown
브랜치를 dev, qa, qc에 머지하고 푸시해줘:

**사용법**: /push {브랜치명}
**예시**: /push feature/news

**주의**: news 레포지토리만 push 대상 (grpc-idl 서브모듈 제외)

**중요**: 0단계(브랜치 확인)를 제외한 나머지 과정(1~3단계)은 사용자에게 질문 없이 자동으로 진행
**중요**: TodoWrite 도구 사용 금지 - 진행 상황은 최종 결과 테이블로만 표시

## 실행 순서

### 0단계: 브랜치 확인 (ARGUMENTS가 비어있는 경우)
`$ARGUMENTS`가 비어있거나 지정되지 않은 경우:
1. `git branch --show-current`로 현재 브랜치 확인
2. AskUserQuestion 도구를 사용하여 사용자에게 질문:
   - 질문: "브랜치가 지정되지 않았습니다. 현재 브랜치 '{현재브랜치명}'를 사용하시겠습니까?"
   - 옵션: "예, 현재 브랜치 사용" / "아니오, 취소"
3. 사용자가 승인하면 현재 브랜치를 `$ARGUMENTS`로 사용
4. 사용자가 거부하면 작업 중단

### 1단계: 작업 브랜치 변경사항 확인 및 푸시
1. `$ARGUMENTS` 브랜치로 체크아웃
2. `git log origin/$ARGUMENTS..$ARGUMENTS`로 원격에 푸시되지 않은 커밋 확인
3. **푸시할 커밋이 있는 경우**:

git push origin $ARGUMENTS

4. **푸시할 커밋이 없는 경우** (원격과 동일):
   - "작업 브랜치에 푸시할 변경사항이 없습니다. 작업을 종료합니다." 메시지 출력
   - **작업 즉시 종료** (2단계로 진행하지 않음)

### 2단계: dev, qa, qc 브랜치 순차 처리
각 브랜치(dev → qa → qc)에 대해 아래 작업 수행:

1. **브랜치 업데이트**

git checkout {브랜치} git fetch origin {브랜치} git reset –hard origin/{브랜치}


2. **머지 수행**

git merge $ARGUMENTS –no-edit

   - 충돌 발생 시 사용자에게 알리고 중단

3. **빌드 확인 (필수)**

./gradlew compileKotlin compileTestKotlin

   - 빌드 실패 시 해당 브랜치 작업 중단하고 사용자에게 알림
   - `git merge --abort` 또는 `git reset --hard origin/{브랜치}`로 롤백

4. **푸시**

git push origin {브랜치}


### 3단계: 원래 브랜치로 복귀

git checkout $ARGUMENTS

## 에러 처리
- 머지 충돌: 충돌 내용 표시하고 수동 해결 요청
- 빌드 실패: 해당 브랜치 롤백 후 다음 브랜치로 자동 진행
- 푸시 실패: 원인 분석 후 사용자에게 알림


## 진행 상황 표시
각 단계마다 진행 상황을 명확히 표시:
- ✅ 성공한 브랜치
- ❌ 실패한 브랜치
- 🔄 진행 중인 브랜치

5. 개선 방향 제안

단기 개선 사항

테스트 실행 옵션 추가: 현재는 컴파일만 검증하지만, 단위 테스트 실행 옵션을 추가하면 품질을 더 높일 수 있습니다.

# 제안: commit.md에 추가
5-1. (선택) `./gradlew test` 실행 - 사용자 옵션으로 제공

커밋 타입 다양화: 현재 feat만 사용하는데, 변경 내용에 따라 fix, refactor, docs 등을 자동 판별하면 좋겠습니다.

Dry-run 모드: 실제 실행 전에 어떤 작업이 수행될지 미리 보여주는 모드가 있으면 안전성이 높아집니다.

중기 개선 사항

선택적 브랜치 배포: push.md에서 dev, qa, qc 중 원하는 브랜치만 선택할 수 있는 옵션이 필요합니다.

/push feature/news --only dev,qa

롤백 명령어 추가: 배포 후 문제 발생 시 빠르게 롤백할 수 있는 /rollback 명령어를 고려해볼 수 있습니다.

Slack/Teams 알림 연동: 배포 완료나 실패 시 팀 채널에 자동 알림을 보내면 협업 효율이 높아집니다.

장기 개선 사항

PR 자동 생성 연동: 커밋 후 GitHub/GitLab PR을 자동으로 생성하는 /pr 명령어와의 연계를 고려할 수 있습니다.

배포 이력 관리: 언제 어떤 브랜치가 어디에 배포되었는지 로그를 남기면 트러블슈팅에 도움이 됩니다.

커스텀 훅 지원: 팀별로 특수한 요구사항(예: 특정 파일 변경 시 추가 검증)을 플러그인 형태로 추가할 수 있는 구조면 확장성이 높아집니다.

6. 활용 팁

commit.md 활용

# 일반적인 사용
/commit

# 설정 파일이 많이 변경된 경우
# → 자동으로 .yml, .yaml 파일 포함 여부를 물어봄

push.md 활용

# 브랜치 지정
/push feature/test

# 현재 브랜치 사용 (확인 질문 표시)
/push

권장 워크플로우

기능 개발 완료
/commit 실행 → 빌드 검증 + 커밋
/push 실행 → dev/qa/qc 순차 배포
진행 상황 테이블로 결과 확인

마무리

commit.md와 push.md는 반복적인 Git 작업을 자동화하여 개발 생산성을 높이고, 빌드 검증을 강제하여 품질을 보장합니다. 특히 다중 환경 브랜치를 운영하는 팀에서 배포 실수를 줄이는 데 큰 도움이 됩니다.

이 명령어들은 시작점일 뿐입니다. 팀의 워크플로우에 맞게 지속적으로 개선하면서, 더 많은 반복 작업을 자동화해 나가시기 바랍니다.