commit-helper

커밋 메시지 생성기

staged 변경사항을 분석하여 프로젝트 컨벤션에 맞는 커밋 메시지 자동 생성

기본 원칙

• 반드시 git diff --staged 기준
• 타입 프리픽스(type)는 무조건 영어 (feat, fix, chore 등)
• 커밋 이름(요약)과 Body는 한글로 작성
• scope는 가능하면 한글 단어 사용, 애매하면 생략
• 요약 50자 이내
• 동사 현재형 (추가, 수정, 개선)
• 결과 중심 작성
• 코드 식별자/파일 경로/API 이름 등은 원문(영문) 유지 가능
• AI 표기 절대 금지: 커밋 메시지 어디에도 Co-Authored-By, Co-authored-by, 🤖, Generated with Claude, Claude, Anthropic 등 AI 관련 문구를 포함하지 않는다

실행 플로우

1. 컨벤션 감지

git log --oneline --format="%s" -50

확인 항목:

• Conventional Commits 여부 (feat:, fix:)
• scope 사용 패턴
• Body 사용 빈도

감지 결과 적용:

감지 결과	적용 방식
scope 없는 패턴 다수	scope 생략 우선
Body 없는 패턴 다수	간결 옵션 권장
커밋 이력 없음	Conventional Commits 기본 적용

타입 프리픽스는 이력과 무관하게 항상 영어 사용.

2. 변경사항 분석

git diff --staged --stat --name-status
git diff --staged

체크 포인트:

• 변경 파일 수
• 변경 영역 (기능/버그/문서/테스트/설정)
• rename/move 포함 여부
• 설정 파일 변경 여부

3. 타입 결정

기능:

• feat → 새 기능
• fix → 버그 수정
• perf → 성능 개선

구조:

• refactor → 구조 개선
• test → 테스트 추가
• docs → 문서 변경
• style → 포맷, 세미콜론 등 로직 무관 변경
• chore → 의존성, 기타 잡무
• build → 빌드 시스템, 패키지 설정 변경
• ci → CI/CD 파이프라인 설정 변경

4. Scope 추론

scope는 "어디가 바뀌었는지"를 나타내는 짧은 한글 명사를 사용.

추론 규칙:

1. 변경 파일의 상위 폴더/모듈명에서 핵심 의미를 추출
2. 길거나 모호하면 더 짧은 일반어로 변환
3. 여러 영역 변경 시 영향이 가장 큰 영역 하나만 선택
4. 적절한 scope가 없으면 scope 생략

예시:

src/<feature>/...           → (<기능명>)
src/components/...          → (컴포넌트)
docs/...                    → (문서)
infra/...                   → (인프라)
tests/...                   → (테스트)

여러 영역 변경 시:

• 주요 변경 영역 우선
• 애매하면 scope 생략

5. Body 포함 조건

다음 중 하나 이상:

• ✅ 파일 5개 이상, 또는 여러 영역에 걸친 변경
• ✅ rename/move 포함
• ✅ 설정/의존성 변경
• ✅ 핵심 로직(권한/데이터/외부연동) 변경
• ✅ 변경 이유 설명 필요

6. 브레이킹 체인지

다음 시 BREAKING CHANGE 명시:

• DB 스키마 변경
• 환경변수 키 변경
• 공개 API 시그니처 변경

출력 형식

옵션 1: 기본 (권장)

{type}({scope}): {요약}

- 변경사항 1
- 변경사항 2

scope를 생략하면 {type}: {요약} 형식 사용.

옵션 2: 간결

{type}({scope}): {요약}

옵션 3: 상세

{type}({scope}): {요약}

- 상세 변경사항 1
- 상세 변경사항 2
- 변경 이유

예외 처리

staged 없음

❌ staged 변경사항이 없습니다. 먼저 `git add`를 실행하세요.

lockfile만

chore(deps): lockfile 업데이트

대량 파일 (100개+)

⚠️ 100개 이상 변경. 커밋 분리 권장.

리네임 중심

refactor: {before} → {after} 리네임

커밋 전 출시 게이트

커밋 메시지 생성 전 아래 항목을 점검한다:

• 린트/빌드 통과 여부 확인
• 불필요한 파일(콘솔 로그, 임시 파일)이 staged 되어 있지 않은가?
• git diff --staged --name-only 결과가 의도한 파일만 포함하는가?

하나라도 문제가 있으면 커밋 전 사용자에게 안내한다.

---

사용 예시:

scope 있는 경우:

사용자: "커밋 메시지 만들어줘"

에이전트: (컨벤션 감지 → 프리픽스 영어 유지, 제목/Body 한글 작성)

## 🎯 권장 커밋 메시지

### 옵션 1: 기본 (권장)
feat(검색): 목록 필터 옵션 추가

- 필터 조건별 결과 정렬 로직 추가
- 선택된 필터 상태를 화면에 표시

### 옵션 2: 간결
feat(검색): 목록 필터 옵션 추가

### 옵션 3: 상세
feat(검색): 목록 필터 옵션 추가

- 필터 조건 조합 처리 로직 추가
- 필터 초기화 시 기본 정렬 복원
- 필터 변경 시 목록 재조회 타이밍 정리

변경 이유: 사용자 요청사항 반영

단일 레포 (scope 생략):

사용자: "커밋 메시지 만들어줘"

에이전트: (컨벤션 감지 → scope 없는 패턴 확인)

## 🎯 권장 커밋 메시지

### 옵션 1: 기본 (권장)
fix: 날짜 형식 검증 오류 수정

- 잘못된 날짜 입력 시 예외 처리 추가
- 검증 실패 메시지 문구 정리

### 옵션 2: 간결
fix: 날짜 형식 검증 오류 수정