rhino-ty Commit Conventions (Korean prose variant)
Conventional Commits 1.0.0 + Tim Pope +
awesome-copilot/git-commit+ 200-commit 실측 분석을 통합한 보편 commit 컨벤션. 프로젝트 특화 dialect (도메인 고유명사, 커스텀 trailer, PDCA 같은 워크플로 통합)는<project>/docs/references/COMMIT.md에 — §15 Dialect Loading 참조.TL;DR:
type(scope): summary(≤100자, lowercase, imperative) + 1-2줄 컨텍스트 +-bullet body (평균 16줄).##헤더 X. body는 영문 default. atomic + leaves-repo-green + why-over-what.
0. Principles
Commit이 만족시켜야 할 4 reader — 사람 + AI 모두:
git log --oneline스캐너 — summary 한 줄로 컨텍스트 잡으려는 사람 (가장 많음)git blame <file>추적자 — "왜 이 줄이 여기 있나" 디버깅 중git bisect사냥꾼 — production fire 중, 깨진 commit 찾는 사람- AI agent —
/clear후 컨텍스트 복원, PR 리뷰, changelog 생성, NL 질의 → 코드 위치 매핑.grep+ 임베딩 검색 + 일관된 구조에 의존. atomic 단위 + 도메인 keyword + 영문 body + 명시 trailer가 결정적
5개 principle은 이 4 reader를 동시에 만족시키는 최소 룰. 의문 생기면 회귀.
0.1 Atomic — 한 commit = 한 의도
하나의 논리적 변경만 담는다. "fix + style + docs" 같이 묶지 말 것.
→ Bisect / revert / cherry-pick 모두 atomic 전제. AI도 mixed commit은 한쪽만 잡아 hallucinate.
판단: "이 commit을 revert해야 할 때 다른 변경까지 같이 revert하는가?" → YES면 split.
0.2 Leaves repo green — 모든 commit은 green build
각 commit 직후 tsc --noEmit + lint + build 통과해야 함. WIP / "next commit will fix this" 금지.
→ Bisect signal 신뢰성. broken-state commit이 끼면 "원인" 판정 부정확. AI 자동 분석도 같은 이유로 영향.
0.3 Why over what — diff가 못 알려주는 것만 본문에
diff는 WHAT을 보여줌. body는 WHY (motivation / trade-off / 어떤 대안 버렸나) 중심.
→ 6개월 후 blame 질답에 직답. AI는 diff context 없이도 commit body에서 의도 추출 가능 (diff 추론 비용 + 오해 위험).
❌ Body: "modify foo.ts to add bar method" (diff 중복)
✅ Body: "extract bar() out of inline closure — (WHY)
prevents re-allocation on every render
causing useMemo deps invalidation"
0.4 Imperative mood — "If applied, this commit will..."
Summary는 명령형. git 자체 메시지(Merge, Revert)와 통일.
→ 일관된 verb 패턴. git tooling + AI classification (changelog 생성, type 추정) 모두 동사 형태에 의존.
✅ add idempotency-key support to /v1/payments
✅ fix double-render in <Modal> on focus return
✅ migrate auth hashing from bcrypt to argon2id
❌ added idempotency-key support (과거형)
❌ adding idempotency-key support (진행형)
❌ idempotency-key support added (수동태)
0.5 Searchable — keyword-rich summary + body
도메인 명사 / 함수명 / 파일 경로 / SoT 이름 / 컴포넌트 이름을 명시. vague 동사(improve, update, enhance)는 대상 명사로 보강.
→ git log --grep + AI 임베딩 검색. 6개월 후 "Idempotency-Key 어디서 추가했지?" 같은 자연어 질의가 1번에 정답 commit으로 hit. AI는 vague keyword에 hallucinate, 구체 keyword에 정확.
❌ feat(api): improve checkout
✅ feat(api/payments): add Idempotency-Key header support with 24h replay window
❌ refactor: cleanup auth helpers
✅ refactor(auth): replace bcrypt with argon2id (memory-hard against GPU attackers)
영문 SKILL.md와의 관계
§1-§14 모든 룰은 영문 SKILL.md와 동일. 본 ko 변형은 prose 설명만 한국어. 룰 자체 (lowercase summary, imperative, English body 정책 등)는 변형 무관.
§1 Format / §2 Types / §3 Scopes / §4 Body Length / §5 Markdown / §6 Breaking Changes / §7 Workflow / §8 Trailers / §9 Amend/Fixup / §10 Reverts / §11 Anti-patterns / §12 Quick Reference / §13 Project Dialect / §14 Source Attribution — 영문 SKILL.md 참조.
본 변형은 §0 principle 본문만 한국어로 작성해 한국어 사용자가 founding rule 의도를 한 번에 이해하도록 함. 나머지는 매 trigger마다 한국어로 옮길 가치보다 영문 정합성이 더 큼 — git tooling, AI 모델, 외부 contributor 모두 영문 기대.
v0.1.5 추가 — 한국어 dialect 사용자 특히 주의
v0.1.5에서 §11 anti-patterns에 "Partial native-language drift" 행이 추가됨 (영문 SKILL.md 참조). 한국어 proper noun (친구톡 / 알림톡 / 발신번호 / 정통망법 등)이 dialect §1 화이트리스트에 등재된 상태에서, LLM이 recent git log만 보고 "한국어 prose OK"로 over-generalize → 책임 분리 / 진행중 발송 같은 비-whitelist 한글이 commit body로 흘러드는 회귀.
방어책 두 갈래 (§13.1 / §13.6):
- Dialect에 inverse rule 명시 — whitelist만 두지 말고 "default = English, native는 §1 whitelist만" 도 한 줄. v0.1.5의
templates/DIALECT.template.md가 §1 / §1.1 split으로 model. - 검증 3단계 — (a)
grep -Ei "default.*english" docs/references/COMMIT.md정적 체크, (b)git log --format='%h %s' -30 | LC_ALL=C grep -P '[^\x00-\x7f]'최근 commit drift symptom 확인, (c) 프로젝트 로컬 hook이 commit 키워드 감지 시 reminder 주입.
한국어 사용자는 whitelist 단어 수가 많고 (regulatory term 일치 비율 높음), drift 표면적이 가장 넓은 locale이라 §11 / §13.6 우선 적용 권장.
작성 시 마음가짐 — 4가지 압축
- Audience first: "6개월 후 내가 이 줄에
git blame찍었을 때 답이 나오나?" - Atomic test: "revert할 때 다른 변경까지 끌고 가나?" → YES면 split
- Why over What: diff가 보여주는 것 다시 쓰지 말 것
- Searchable: vague 동사 금지. 도메인 명사 / 함수명 / 컴포넌트 이름 적기
이게 §0의 본질. 룰 14개 모두 이 4가지의 구현 디테일.