commit

---
name: commit
description: Use when creating git commits with multiple changes, to structure messages with clear titles and concise details that make changes easy to understand
---

# 커밋 메시지 작성 기법

## 개요

**커밋 메시지는 변경사항을 5줄 이내의 한글로 명확하게 전달하는 문서입니다.**

핵심 원칙: 제목은 전체를 요약하고, 상세내용은 수정사항을 쉽게 파악할 수 있게 작성합니다.

## 모델 선택

메시지 초안은 기본적으로 경량 모델(claude-haiku)이 쓰고, 변경 규모가 기준을 넘으면 중급 모델(claude-sonnet)이 쓴다. 커밋(`git commit`)은 이 스킬을 실행한 세션(초안 서브에이전트가 아닌 쪽)이 한다. 메인 세션이든 롤 서브에이전트든 같다.

### 1. 규모 재기

대상은 커밋에 들어갈 변경이다. 재기 전에 커밋할 파일을 먼저 `git add` 한다. 새 파일(추적 안 된 파일)도 `git add` 해야 numstat에 잡힌다. 스테이징된 것이 있으면 그것을, 없으면 작업 트리의 추적 파일 변경 전체(`git diff HEAD`)를 잰다. 커밋이 하나도 없는 저장소(HEAD 없음)에서 스테이징도 없으면 잴 것이 없으므로 `files=0`이 나온다. 이때는 `git add` 후 다시 잰다.

```bash
if git diff --cached --quiet; then
  git rev-parse -q --verify HEAD >/dev/null && git -c core.quotePath=false diff HEAD --numstat || true
else git -c core.quotePath=false diff --cached --numstat; fi |
awk -F'\t' '
  { files++
    f = $3                                                 # 이름 변경 표기(a => b, dir/{a => b}/f)는 새 경로로 푼다
    if (f ~ /\{[^}]* => /) { sub(/\{[^}]* => /, "{", f); gsub(/[{}]/, "", f); gsub(/\/\//, "/", f); sub(/^\//, "", f) }
    else if (f ~ / => /) sub(/^.* => /, "", f)
    split(f, p, "/"); area[(length(p) > 1) ? p[1] : "(root)"] = 1
    if ($1 == "-") next                                    # 바이너리: 줄 수 제외
    if (f ~ /(^|\/)(package-lock\.json|pnpm-lock\.yaml|yarn\.lock|Cargo\.lock|poetry\.lock|go\.sum)$/) next   # 잠금 파일: 줄 수 제외
    lines += $1 + $2 }
  END { n = 0; for (a in area) n++
        printf "files=%d lines=%d areas=%d\n", files, lines, n }'
```

- 이름이 바뀐 파일은 numstat이 `a => b` 또는 `dir/{a => b}/f`로 적는다. 위 awk는 이를 새 경로로 풀어 영역을 센다 (`--no-renames`는 쓰지 않는다. 파일 수 셈이 바뀌어 모델 선택 경계가 움직인다).
- 생성물(빌드 산출물, 자동 생성 코드 등)도 줄 수에서 뺀다. 경로·헤더로 알아볼 수 있는 것만 뺀다. 판단이 서지 않으면 뺀 것으로 치지 않고 센다.
- `core.quotePath=false`는 한글 경로가 따옴표로 감싸져 영역이 따로 세지는 것을 막는다. 경로를 출력하는 git 호출에는 항상 붙인다.
- 커밋 대상인데 `git add` 하지 못한 새 파일이 남았다면(스테이징을 미루는 경우) `git -c core.quotePath=false ls-files --others --exclude-standard`로 찾아 파일 수와 영역 수에 더하고, 줄 수는 `wc -l`로 더한다.

### 2. 기준

아래 중 하나라도 해당하면 **sonnet**, 하나도 해당하지 않으면 **haiku**.

| 지표 | sonnet 기준 |
|------|-------------|
| 바뀐 파일 수 | 6개 이상 (잠금 파일·생성물·바이너리도 파일 수에는 센다) |
| 변경 줄 수 (추가+삭제) | 300줄 이상 (잠금 파일·생성물·바이너리 제외) |
| 최상위 영역 수 | 3곳 이상 (경로의 첫 폴더가 영역, 루트 파일은 "루트" 하나로 센다. awk에서는 `(root)`) |

예외: 사용자가 모델을 지정하면(예: "sonnet으로 써줘", "haiku로 커밋해") 기준과 상관없이 그것을 따른다. 요청문에 모델 이름이 있는지를 보고 판단한다.

### 3. 알리기

고른 모델과 근거를 한 줄로 사용자에게 알린다.

- 예: `커밋 메시지 모델: haiku (파일 3개, 120줄, 영역 1곳)`
- 예: `커밋 메시지 모델: sonnet (파일 8개, 420줄, 영역 3곳 - 3개 기준 해당)`
- 사용자가 지정했으면 `커밋 메시지 모델: sonnet (사용자 지정)`

### 4. 초안 쓰기

Agent 도구로 서브에이전트를 띄워 메시지 초안만 받는다. `model`에 `"haiku"` 또는 `"sonnet"`을 그대로 넣는다.

서브에이전트에게 넘길 것:
- diff를 읽는 명령: 1단계에서 쓴 대상과 같은 것(`git -c core.quotePath=false diff --cached` 또는 `git -c core.quotePath=false diff HEAD`)
- 이 스킬의 메시지 형식(구조, 제목 작성법, 상세내용 작성법, 검사 체크리스트)
- 요청: "메시지 초안 텍스트만 돌려준다. 커밋하지 않는다. 파일을 수정하지 않는다."

받은 초안을 이 스킬을 실행한 세션이 검사 체크리스트로 확인하고, 필요하면 고친 뒤 `git commit`을 한다.

대체 경로: 아래 경우에는 서브에이전트 없이 이 스킬을 실행한 세션이 직접 쓴다.
- Agent 도구가 없을 때
- 이 스킬을 실행한 세션이 이미 고른 모델로 실행 중일 때 (이미 haiku인데 haiku가 필요하거나, 이미 sonnet 이상인데 sonnet이 필요한 경우)
- 서브에이전트 호출이 실패했을 때

## 구조

```
<타입>: <한글 요약 제목>

- 변경사항 1: 간단한 설명
- 변경사항 2: 간단한 설명
- 변경사항 3: 간단한 설명
```

**필수 요소:**
1. **제목** (첫 줄): 타입 + 전체 변경을 요약하는 한 줄
2. **공백줄** (두 번째 줄): 제목과 상세내용 분리
3. **상세내용** (3-5줄): `- ` 로 시작하는 bullet points, 수정사항별 1줄씩

**`Co-Authored-By:` 줄은 제거합니다.**

**관련 이슈가 있으면 제목 끝에 이슈 번호나 코드를 붙입니다.** (예: `fix: 로그인 오류 수정 (#123)`, `feat: 역할 요청 기능 추가 (PROJ-45)`)

## 제목 작성법

**형식:** `<타입>: <한글 요약>`

**타입:**
- `feat`: 새 기능
- `fix`: 버그 수정
- `refactor`: 코드 개선
- `perf`: 성능 최적화
- `docs`: 문서 수정
- `test`: 테스트 추가/수정
- `chore`: 빌드, 의존성 등

**제목 작성 팁:**
- 전체 변경을 한 문장으로 요약
- 동사로 시작 (예: "추가", "개선", "변경")
- 마침표 없음
- 50자 이내 (한글 기준)

### ❌ 나쁜 제목
- `fix: 버그` (너무 추상적)
- `refactor: 코드 리팩토링 및 에러 처리 개선 그리고 성능 최적화` (너무 길고 여러 개)
- `chore: 업데이트` (무엇을 업데이트?)

### ✅ 좋은 제목
- `fix: 로그인 폼 에러 메시지 표시 오류 수정`
- `feat: 사용자 역할 요청 기능 추가`
- `perf: API 응답 캐싱으로 로딩 속도 개선`

## 상세내용 작성법

**목표:** 3-5줄 이내에 각 수정사항을 명확하게 표시

**형식:**
```
- 변경 항목 1: 구체적인 변경 내용
- 변경 항목 2: 구체적인 변경 내용
- 변경 항목 3: 구체적인 변경 내용
```

**작성 팁:**
- 각 줄은 하나의 수정사항만 표현
- "무엇을 변경했는가"가 명확해야 함
- 도메인/기능명을 명시 (예: "역할 관리", "인증", "API 응답")
- 기술 용어는 필요한 경우만 사용 (Redux → Zustand 마이그레이션 같은 경우)
- 파일명 대신 기능/컴포넌트 이름 사용

### 예시

**예시 1: UI 수정**
```
fix: API 관리 상태 컬럼 너비 조정

- 상태 컬럼 너비: 80px → 90px로 증가
- 텍스트 표시 영역 확보로 레이아웃 개선
```

**예시 2: 기능 추가**
```
feat: 사용자 역할 요청 기능 추가

- 역할 요청 API 엔드포인트 구현
- 요청 현황 조회 화면 추가
- 승인/거절 상태 관리 로직 완성
```

**예시 3: 버그 수정**
```
fix: 대시보드 필터 초기화 버그 수정

- 필터 리셋 시 상태 값 미업데이트 문제 해결
- useCallback 의존성 배열 수정으로 재렌더링 최적화
- 테스트 케이스 추가 (필터 상태 검증)
```

## 사용 시점

- 수정사항이 2개 이상일 때: 각 항목을 bullet point로 표시
- 1개 수정사항만 있을 때: 상세내용 생략 가능, 제목만 작성
- 코드 리뷰 전: 커밋 메시지를 한 번 더 검토

## 자주 하는 실수

| 실수 | 문제점 | 해결책 |
|------|--------|--------|
| 제목이 너무 길다 | 50자 초과 | 요약을 더 간결하게 |
| 상세내용이 없다 | 변경사항 파악 어려움 | bullet point로 3-5줄 추가 |
| 상세내용이 5줄 초과 | 너무 상세 | 가장 중요한 항목만 표시 |
| 영어로 섞어 쓴다 | 일관성 없음 | 한글로 통일 |
| 마침표 붙인다 | 불필요 | 제목/bullet point 끝에 마침표 제거 |

## 검사 체크리스트

커밋 전에 확인:
- [ ] 제목이 50자 이내인가?
- [ ] 제목이 전체 변경을 요약하는가?
- [ ] 상세내용이 3-5줄 이내인가?
- [ ] 각 줄이 하나의 수정사항만 표현하는가?
- [ ] 한글로만 작성했는가?
- [ ] 제목과 bullet point에 마침표가 없는가?