# Commit

> Conventional Commits 규격(feat/fix/docs/chore)에 따라 한국어와 영어 커밋 메시지 생성 Use when this capability is needed.

- Skill: `tomevault-io/commit-83` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/commit-83`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/commit-83/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/commit-83

---


# Conventional Commits 메시지 생성기

[Conventional Commits v1.0.0](https://www.conventionalcommits.org/) 규격을 따르는 커밋 메시지를 한국어와 영어로 생성합니다. **하나를 선택하여 커밋에 사용하세요.**

## 저장소 상태 분석

- Git 상태: !git status --porcelain
- 현재 브랜치: !git branch --show-current
- 스테이징된 변경사항: !git diff --cached --stat
- 스테이징되지 않은 변경사항: !git diff --stat
- 최근 커밋: !git log --oneline -10

## 이 명령의 기능

1. 현재 브랜치명을 확인하여 이슈 번호 감지 (예: develop/shlee/32 → #32)
2. git status로 스테이징된 파일 확인
3. git diff를 수행하여 커밋될 변경사항 파악
4. 한국어와 영어로 Conventional Commits 형식의 커밋 메시지 생성
5. 브랜치명이 숫자로 끝나면 "fix #N" 추가
6. **commit_message.md 파일로 저장하여 복사하기 편리하게 제공**

## Conventional Commits 형식 (필수)

```
<type>[(optional scope)]: <description>

[optional body]

[optional footer: fix #N]
```

### 사용 가능한 타입

스테이징된 변경사항을 분석하여 가장 적절한 타입을 제안:

| 타입         | 사용 시점                                   | SemVer 영향   |
| ------------ | ------------------------------------------- | ------------- |
| **feat**     | 새로운 기능이나 역량 추가                   | MINOR (0.x.0) |
| **fix**      | 사용자가 겪는 버그 수정                     | PATCH (0.0.x) |
| **ifix**     | 인프라/내부 버그 수정 (CI, 빌드, 배포)      | PATCH (0.0.x) |
| **perf**     | 성능 개선                                   | PATCH         |
| **docs**     | 문서만 변경 (README, 주석 등)               | PATCH         |
| **style**    | 코드 포매팅, 세미콜론 누락 (로직 변경 없음) | PATCH         |
| **refactor** | 동작 변경 없는 코드 구조 개선               | PATCH         |
| **test**     | 테스트 추가 또는 수정                       | PATCH         |
| **chore**    | 빌드 설정, 의존성, 도구 업데이트            | PATCH         |
| **ci**       | CI/CD 설정 변경                             | PATCH         |

**BREAKING CHANGE**: 반드시 type! 형식(타입 뒤에 느낌표)과 BREAKING CHANGE: footer에 마이그레이션 가이드를 함께 포함해야 함 (major 버전 증가).

### 헷갈리는 케이스: fix vs ifix vs chore 구분

**핵심 기준**: **사용자**에게 영향을 주는가, **개발자/인프라**에만 영향을 주는가?

| 상황                                                    | 타입       | 이유                                        |
| ------------------------------------------------------- | ---------- | ------------------------------------------- |
| 백엔드 GitHub Actions 테스트 워크플로우가 동작하지 않음 | `ifix`     | 개발을 막는 CI/CD 버그                      |
| OOM 에러로 배포 실패                                    | `ifix`     | 릴리스를 막는 인프라 버그                   |
| E2E 테스트가 불안정하여 오탐 발생                       | `ifix`     | 테스트 인프라 버그                          |
| Vite 프로덕션 빌드 시 타임아웃 발생                     | `ifix`     | 빌드 시스템 버그                            |
| API가 정상 요청에 500 에러 반환                         | `fix`      | 사용자가 에러 응답을 경험함                 |
| 페이지 로딩 속도가 3초에서 0.8초로 개선                 | `perf`     | 사용자가 직접 체감하는 개선                 |
| 프로필 페이지 접근 시 앱 종료                           | `fix`      | 사용자가 크래시를 경험함                    |
| 내부 데이터베이스 쿼리 최적화 (사용자 무체감)           | `refactor` | 코드 개선, 사용자에게 측정 가능한 이점 없음 |
| 의존성 보안 패치 (CVE 수정)                             | `chore`    | 빌드/도구 업데이트 (버그 수정 아님)         |
| 새로운 기능을 위한 React 버전 업그레이드                | `chore`    | 의존성 업데이트 (버그 수정 아님)            |

**판단 플로우차트:**

```
버그(고장난 것)인가?
├─ 아니오 → chore/refactor/docs 등 사용
└─ 예 → 최종 사용자에게 영향을 주는가?
    ├─ 예 → fix (사용자 대면 버그)
    └─ 아니오 → ifix (인프라/개발자 버그)
```

## 커밋 메시지 작성 규칙

**커밋 메시지는 프로젝트 히스토리다.** "왜 이 변경이 필요했는가?"에 답한다. "무엇을 수정했는가?"가 아니다.

### Subject Line: 목적 중심, 기술적 행위 나열 금지

`<description>`에는 **목적 또는 해결한 문제**를 쓴다. 기술적으로 무엇을 했는지 나열하지 않는다.

| 안티패턴 (기술적 행위 나열)                         | 올바른 예 (목적/문제 중심)                         |
| --------------------------------------------------- | -------------------------------------------------- |
| `getUser 함수에서 null 체크 누락 수정`              | `로그인 직후 프로필 페이지 접근 시 화면 깨짐 수정` |
| `상품 목록 API에 Redis 캐시 레이어 추가`            | `상품 목록 페이지 초기 로딩 속도 개선`             |
| `UserService를 UserRepository와 UserUseCase로 분리` | `사용자 도메인 로직과 DB 접근 책임 분리`           |
| `프로필 페이지에 비밀번호 변경 폼 컴포넌트 추가`    | `사용자가 직접 비밀번호를 변경할 수 있도록 지원`   |

**리트머스 테스트**: subject가 기술 명사 + "추가/수정/변경/개선"으로 끝나면 — WHAT을 쓴 것이다. WHY로 재작성한다.

### Body: 서술형 산문, 기술적 나열 목록 금지

본문은 1-4문장의 **서술형 산문**으로 다음에 답한다:

1. **왜 이 문제/필요가 존재했는가?** (맥락, 근본 원인)
2. **어떤 접근으로 해결했고, 왜 그 방식인가?** (접근 방식과 선택 근거를 한 흐름으로)

**금지**: 본문에 기술적 변경사항을 bullet list로 나열. 그건 `git diff`가 하는 일이다.

**예외**: 대규모 커밋(5개 이상 파일, 복수 관심사)에서만, 서술 본문 **뒤에** "주요 변경:" 접두어와 함께 간결한 요약 목록 허용.

### 한국어 본문 문체 규칙

**문장 종결**: 명사형 종결(`~함`, `~됨`, `~필요함`, `~없음`, `~있음`) 사용. 서술형 종결(`~한다`, `~된다`, `~했다`) 금지.

| Bad (서술형)                       | Good (명사형)                    |
| ---------------------------------- | -------------------------------- |
| 도메인 모델이 먼저 정의되어야 한다 | 도메인 모델이 먼저 정의되어야 함 |
| exact version으로 고정했다         | exact version으로 고정함         |
| 이 방식이 가장 적합하다고 판단했다 | 이 방식이 가장 적합하다고 판단함 |

**개행 규칙**: 문장이 종결된 후에만 줄바꿈. 문장 중간에서 절대 줄바꿈하지 않음 — 절이 이어지면 같은 줄에 유지.

| Bad (문장 중간 개행)                                                         | Good (문장 종결 후 개행)                                                |
| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| 후속 커밋이 공유 타입 위에 빌드되려면<br>도메인 모델이 먼저 정의되어야 한다. | 후속 커밋이 공유 타입 위에 빌드되려면 도메인 모델이 먼저 정의되어야 함. |

### 복잡도 기반 형식

**매우 간단** (오타, 포매팅, 단순 설정):

```
type: 간결한 설명
```

**간단**:

```
type: 목적/문제

근본 원인 또는 맥락 한 문장.
어떤 접근으로 해결했고, 왜 그 방식인가 (자명하지 않은 경우).
```

**표준**:

```
type: 목적/문제

왜 이 문제가 존재했는가 (맥락).
어떤 접근으로 해결했고, 왜 그 방식인가 (근거).

fix #N
```

**대규모** (예외 — 목록 허용되는 유일한 경우):

```
type: 상위 수준 목적

서술형 맥락, 접근 방식, 선택 근거 (2-4문장).

주요 변경:
- 간결한 항목 1
- 간결한 항목 2

fix #N
```

## 출력 형식

명령이 제공하는 내용:

1. 스테이징된 변경사항 분석 (없으면 모든 변경사항)
2. **commit_message.md 파일 생성** — 한국어와 영어 버전 모두 포함
3. 파일에서 원하는 버전을 복사하여 사용

## 중요 사항

- 이 명령은 커밋 메시지만 생성 — 실제 커밋은 수행하지 않음
- **commit_message.md 파일에 두 버전 모두 저장** — 원하는 것 선택
- **목적을 쓴다, 변경 목록을 쓰지 않는다** — subject = 왜 중요한가, body = 맥락
- 브랜치 이슈 번호(예: develop/32)는 자동으로 "fix #N" 추가
- 생성된 파일에서 메시지 복사 후 `git commit`을 수동으로 실행

## 실행 단계

### Phase 1: 목적 합성 (diff 분석 전에 먼저)

1. 대화 기록에서 해결하려는 문제 또는 추구하는 목표를 파악
2. 브랜치명, 변경 파일명, 테스트 설명에서 의도 추론
3. **한 문장 목적 정립**: "이 커밋은 \_\_\_을/를 위해 필요하다"
   - 이 문장이 subject line의 씨앗이 된다

### Phase 2: 변경사항 분석

4. git 명령으로 스테이징된 변경사항 확인 (없으면 전체)
5. Phase 1의 목적이 실제 변경사항과 일치하는지 검증, 필요시 조정

### Phase 3: 메시지 작성

6. **Subject = Phase 1의 목적**, 무엇을 했는지 나열이 아님
7. **Body = 서술문** — "왜 이 문제가?" + "왜 이 해결책?"에 답함
8. 변경 범위에 따라 복잡도 템플릿 선택
9. **타입 선택** — 목적과 본문 내용에서 결정 (파일 패턴이 아닌)
10. 필요시 scope 결정 (예: `fix(api):`, `feat(ui):`)

### Phase 4: 자기검증 (Hard Gate)

11. **Subject 점검**: 기술적 행위를 설명하는가, 목적을 설명하는가?
    - 기술 명사 + "추가/수정/변경/개선"으로 끝남 → 재작성
12. **Body 점검**: 서술형 산문인가, 변경사항 bullet list인가?
    - `- `로 시작하는 기술적 변경 나열 → 서술형으로 재작성
    - 예외: 대규모 커밋의 "주요 변경:" 섹션 (서술 본문 뒤)
13. **히스토리 점검**: "6개월 후 이 메시지만 읽고 왜 이 변경이 필요했는지 이해할 수 있는가?"
    - No → 해결한 문제에 대한 맥락 추가

### 출력

14. 한국어와 영어 버전 모두 생성
15. `commit_message.md`에 기록
16. 제안 타입과 근거 제시

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/kubrickcode) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->