📖 예상 읽기 시간: 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→newsbugfix/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에게 위임하여 개발자는 비즈니스 로직에 집중할 수 있습니다. 특히 서브모듈 처리나 다중 브랜치 배포 같은 복잡한 작업에서 효과가 큽니다.
팀 표준화
커밋 메시지 형식과 배포 절차가 명령어에 정의되어 있어 팀 전체가 동일한 방식으로 작업하게 됩니다. 신규 팀원 온보딩 시간도 단축됩니다.
push.md
브랜치를 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 작업을 자동화하여 개발 생산성을 높이고, 빌드 검증을 강제하여 품질을 보장합니다. 특히 다중 환경 브랜치를 운영하는 팀에서 배포 실수를 줄이는 데 큰 도움이 됩니다.
이 명령어들은 시작점일 뿐입니다. 팀의 워크플로우에 맞게 지속적으로 개선하면서, 더 많은 반복 작업을 자동화해 나가시기 바랍니다.
