커밋 메시지 생성기
이 파일은 유일한 진실 공급원(Single Source of Truth) 이며, 각 에이전트(Claude / opencode / codex)는 각자의 얇은 shim(어댑터)을 통해 이를 참조합니다.
절차
git diff --staged를 실행하여 스테이징된 변경 사항을 확인합니다. 스테이징된 내용이 없으면 "먼저git add를 실행하세요"라는 메시지를 표시하고 중단합니다.- 아래 규칙에 따라 메시지를 생성하고, 사용자에게 확인을 요청하며, 바로 커밋하지 않습니다. 사용자가 선택해야 할 경우, 그냥 질문만 하지 말고 선택 가능한 메시지를 직접 제시합니다.
- 사용자가 확인(예: "커밋", "ok"라고 응답)한 경우에만
git commit -m을 실행합니다. 사용자가 명시적으로 요청하지 않는 한git push를 실행하지 않습니다.
규칙
git diff --staged를 읽고, Conventional Commits 규칙에 따라 WHAT(무엇)과 WHY(왜)를 명확히 설명하는 메시지를 생성합니다.
- 제목
type(scope): 설명형식, 전체 길이 ≤ 74자, 끝에 마침표를 붙이지 않으며, 접두사/따옴표/코드 블록을 사용하지 않습니다. - type 은 가장 적합한 것 하나를 선택합니다:
feat새 기능 ·fix버그 수정refactor외부 동작을 변경하지 않는 리팩토링(새 기능이나 버그 수정이 아님) ·perf성능 최적화docs문서만 변경 ·style의미에 영향을 주지 않는 형식 조정(공백/형식/세미콜론 등)test테스트 추가 또는 수정 ·build빌드 시스템 또는 외부 의존성 변경 ·ciCI 구성 및 스크립트choresrc/test를 건드리지 않는 기타 잡일 ·revert이전 커밋 되돌리기
- scope (선택 사항) 영향을 받는 모듈 이름으로, 이 저장소의 규칙에 따라 결정합니다. — monorepo의 경우 app/package 디렉토리 이름을 사용합니다. 여러 모듈에 걸쳐 있거나 확실하지 않은 경우 생략합니다.
- 설명은 반드시 중국어를 사용합니다.: 한 문장의 동사-목적어 구문으로 "무엇을 했는지"를 명확히 설명하며, "여러 파일을 수정함", "이번 커밋", "이번 수정"과 같은 빈말을 사용하지 않습니다. 식별자(함수/파일/패키지 이름)는 영어를 유지합니다.
- 한 줄만 사용: 어떤 경우에도 커밋 메시지는 제목 한 줄만 있으며, 본문/footer를 작성하지 않습니다. 필요한 WHY(왜)는 이 한 줄에 압축합니다.
- Breaking change 는
type(scope)!: 설명형식의!로 표시하며, 한 줄을 유지하고BREAKING CHANGEfooter를 사용하지 않습니다. - 구두점은 영어 반각 구두점을 사용하고, 전각
,。:()를 사용하지 않습니다.
생성 전략
작성하기 전에 먼저 "이번 변경 사항이 해결하는 문제 / 핵심 내용이 무엇인지"를 명확히 파악한 후, 위 형식에 따라 작성합니다.
- 핵심 파악: 이 커밋을 이해하는 데 필요한 정보만 작성하고, 파일 이름/함수 이름/설정 이름(그 자체가 중요하지 않은 한)을 나열하지 않습니다.
- 중요 변경 사항 스캔: 로직, 계약, 빌드, 품질 게이트 또는 사용자에게 보이는 동작 변경이 있는지 확인합니다. 이를 기반으로 적절한 type을 선택하고,
!로 breaking change를 표시할지 판단합니다.
내용 규율 (WHAT의 출처)
위는 형식에 관한 내용입니다. 아래는 내용의 진실성을 관리합니다. — 메시지는 확인된 코드 사실만을陈述하며, 의도를 추측하거나 문서를 바탕으로 상상하여 작성하지 않습니다.
src/test의 동작 변경을 중심으로: docs는 보조 배경으로만 사용하며, WHAT을 추론하기 위해 docs를 사용할 수 없습니다 (문서는 종종 코드보다 앞서거나 뒤쳐집니다).- 대화 맥락이 문서보다 우선: 최근 사용자 프롬프트에서 명시적으로 언급된 목표는 WHY를 결정하고 더 적절한 표현을 선택하는 데 사용할 수 있습니다 (예: "전체 check/typecheck 수정"). 그러나 WHAT/scope는 여전히 staged diff를 기준으로 합니다. — 맥락에서 언급되었지만 diff에 반영되지 않은 내용은 메시지에 작성하지 않으며, 둘이 충돌할 경우 diff를 우선하고 확인을 요청합니다.
- 삭제 / 이름 변경과 같은 diff: 코드 호출 관계에서 목적을 확인할 수 없는 경우, 객관적으로만 서술합니다 (
X 삭제/X를 Y로 이름 변경). "대체 / 마이그레이션 / 변경"과 같은 강한 인과 관계를 작성하지 않습니다. - 여러 변경 지점이지만 동일한 목표인 경우 (예: 한 번의 코드 품질/빌드 수정) → 바로 하나의 요약 메시지를 제공합니다. 분할은 리뷰/롤백을 크게 개선할 수 있는 경우에만 선택적 제안으로 첨부하며, 기본적으로 분할을 요구하지 않습니다.
- 여러 개의 독립적인 기능/수정 목표가 명확히 혼합된 경우 → 한 번에 모두 제공합니다.: 각 단위의 분할 메시지 + 하나의 보수적인 요약 메시지를 제공하여 사용자가 분할 또는 요약을 직접 선택할 수 있게 하고, 요약을 다음 라운드로 미루지 않습니다. 전체 WHAT을 객관적으로 요약할 수 없는 경우에만 단위를 나열하고 억지로 요약하지 않습니다.
- 귀속/의도가 불확실한 변경 사항이 혼합된 경우 (병렬로 포함되어 왜 변경되었는지 알 수 없는 경우) → "이 파일들은 귀속/의도를 확인해야 합니다" 를 출력하고, 억지로 메시지를 만들지 않습니다. 불확실한 경우 "정리 / 조정"과 같은 모호한 단어를 사용하지 말고, 사용자에게 확인 또는 분할을 요청하는 것이 우선입니다.