tomevault-io Conventional Commits 메시지 생성기
Conventional Commits v1.0.0 규격을 따르는 커밋 메시지를 한국어와 영어로 생성합니다. 하나를 선택하여 커밋에 사용하세요.
저장소 상태 분석
- Git 상태: !git status --porcelain
- 현재 브랜치: !git branch --show-current
- 스테이징된 변경사항: !git diff --cached --stat
- 스테이징되지 않은 변경사항: !git diff --stat
- 최근 커밋: !git log --oneline -10
이 명령의 기능
- 현재 브랜치명을 확인하여 이슈 번호 감지 (예: develop/shlee/32 → #32)
- git status로 스테이징된 파일 확인
- git diff를 수행하여 커밋될 변경사항 파악
- 한국어와 영어로 Conventional Commits 형식의 커밋 메시지 생성
- 브랜치명이 숫자로 끝나면 "fix #N" 추가
- 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문장의 서술형 산문으로 다음에 답한다:
- 왜 이 문제/필요가 존재했는가? (맥락, 근본 원인)
- 어떤 접근으로 해결했고, 왜 그 방식인가? (접근 방식과 선택 근거를 한 흐름으로)
금지: 본문에 기술적 변경사항을 bullet list로 나열. 그건 git diff가 하는 일이다.
예외: 대규모 커밋(5개 이상 파일, 복수 관심사)에서만, 서술 본문 뒤에 "주요 변경:" 접두어와 함께 간결한 요약 목록 허용.
한국어 본문 문체 규칙
문장 종결: 명사형 종결(~함, ~됨, ~필요함, ~없음, ~있음) 사용. 서술형 종결(~한다, ~된다, ~했다) 금지.
| Bad (서술형) | Good (명사형) |
|---|---|
| 도메인 모델이 먼저 정의되어야 한다 | 도메인 모델이 먼저 정의되어야 함 |
| exact version으로 고정했다 | exact version으로 고정함 |
| 이 방식이 가장 적합하다고 판단했다 | 이 방식이 가장 적합하다고 판단함 |
개행 규칙: 문장이 종결된 후에만 줄바꿈. 문장 중간에서 절대 줄바꿈하지 않음 — 절이 이어지면 같은 줄에 유지.
| Bad (문장 중간 개행) | Good (문장 종결 후 개행) |
|---|---|
| 후속 커밋이 공유 타입 위에 빌드되려면도메인 모델이 먼저 정의되어야 한다. | 후속 커밋이 공유 타입 위에 빌드되려면 도메인 모델이 먼저 정의되어야 함. |
복잡도 기반 형식
매우 간단 (오타, 포매팅, 단순 설정):
type: 간결한 설명
간단:
type: 목적/문제
근본 원인 또는 맥락 한 문장.
어떤 접근으로 해결했고, 왜 그 방식인가 (자명하지 않은 경우).
표준:
type: 목적/문제
왜 이 문제가 존재했는가 (맥락).
어떤 접근으로 해결했고, 왜 그 방식인가 (근거).
fix #N
대규모 (예외 — 목록 허용되는 유일한 경우):
type: 상위 수준 목적
서술형 맥락, 접근 방식, 선택 근거 (2-4문장).
주요 변경:
- 간결한 항목 1
- 간결한 항목 2
fix #N
출력 형식
명령이 제공하는 내용:
- 스테이징된 변경사항 분석 (없으면 모든 변경사항)
- commit_message.md 파일 생성 — 한국어와 영어 버전 모두 포함
- 파일에서 원하는 버전을 복사하여 사용
중요 사항
- 이 명령은 커밋 메시지만 생성 — 실제 커밋은 수행하지 않음
- commit_message.md 파일에 두 버전 모두 저장 — 원하는 것 선택
- 목적을 쓴다, 변경 목록을 쓰지 않는다 — subject = 왜 중요한가, body = 맥락
- 브랜치 이슈 번호(예: develop/32)는 자동으로 "fix #N" 추가
- 생성된 파일에서 메시지 복사 후
git commit을 수동으로 실행
실행 단계
Phase 1: 목적 합성 (diff 분석 전에 먼저)
- 대화 기록에서 해결하려는 문제 또는 추구하는 목표를 파악
- 브랜치명, 변경 파일명, 테스트 설명에서 의도 추론
- 한 문장 목적 정립: "이 커밋은 ___을/를 위해 필요하다"
- 이 문장이 subject line의 씨앗이 된다
Phase 2: 변경사항 분석
- git 명령으로 스테이징된 변경사항 확인 (없으면 전체)
- Phase 1의 목적이 실제 변경사항과 일치하는지 검증, 필요시 조정
Phase 3: 메시지 작성
- Subject = Phase 1의 목적, 무엇을 했는지 나열이 아님
- Body = 서술문 — "왜 이 문제가?" + "왜 이 해결책?"에 답함
- 변경 범위에 따라 복잡도 템플릿 선택
- 타입 선택 — 목적과 본문 내용에서 결정 (파일 패턴이 아닌)
- 필요시 scope 결정 (예:
fix(api):,feat(ui):)
Phase 4: 자기검증 (Hard Gate)
- Subject 점검: 기술적 행위를 설명하는가, 목적을 설명하는가?
- 기술 명사 + "추가/수정/변경/개선"으로 끝남 → 재작성
- Body 점검: 서술형 산문인가, 변경사항 bullet list인가?
-로 시작하는 기술적 변경 나열 → 서술형으로 재작성- 예외: 대규모 커밋의 "주요 변경:" 섹션 (서술 본문 뒤)
- 히스토리 점검: "6개월 후 이 메시지만 읽고 왜 이 변경이 필요했는지 이해할 수 있는가?"
- No → 해결한 문제에 대한 맥락 추가
출력
- 한국어와 영어 버전 모두 생성
commit_message.md에 기록- 제안 타입과 근거 제시
Converted and distributed by TomeVault — claim your Tome and manage your conversions.