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 모두:

1. `git log --oneline` 스캐너 — summary 한 줄로 컨텍스트 잡으려는 사람 (가장 많음)
2. `git blame <file>` 추적자 — "왜 이 줄이 여기 있나" 디버깅 중
3. `git bisect` 사냥꾼 — production fire 중, 깨진 commit 찾는 사람
4. 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):

1. Dialect에 inverse rule 명시 — whitelist만 두지 말고 "default = English, native는 §1 whitelist만" 도 한 줄. v0.1.5의 templates/DIALECT.template.md가 §1 / §1.1 split으로 model.
2. 검증 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가지 압축

1. Audience first: "6개월 후 내가 이 줄에 git blame 찍었을 때 답이 나오나?"
2. Atomic test: "revert할 때 다른 변경까지 끌고 가나?" → YES면 split
3. Why over What: diff가 보여주는 것 다시 쓰지 말 것
4. Searchable: vague 동사 금지. 도메인 명사 / 함수명 / 컴포넌트 이름 적기

이게 §0의 본질. 룰 14개 모두 이 4가지의 구현 디테일.