Back to Details

principled-git-commit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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.
这是整合了Conventional Commits 1.0.0 + Tim Pope + 
awesome-copilot/git-commit
+ 200次提交实测分析的通用提交规范。项目专属方言（领域专有名词、自定义trailer、PDCA等工作流整合）请参考
<project>/docs/references/COMMIT.md
——详见§15 方言加载。
TL;DR：
type(scope): summary
（≤100字符、小写、命令式）+ 1-2行上下文 + 
-
列表式正文（平均16行）。禁止使用
##
标题。正文默认使用英文。遵循atomic + leaves-repo-green + why-over-what原则。

0. Principles

0. 核心原则

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를 동시에 만족시키는 최소 룰. 의문 생기면 회귀.
提交需要满足的4类读者——人类 + AI 兼顾：
  1. git log --oneline
    浏览者     — 希望通过一行摘要快速了解上下文的人（占比最多）
  2. git blame <file>
    追踪者     — 正在调试“这行代码为什么在这里”的人
  3. git bisect
    调试者     — 生产环境出现故障时，寻找出问题的提交的人
  4. AI Agent — 恢复
    /clear
    后的上下文、PR评审、生成changelog、自然语言查询 → 代码位置映射。依赖
    grep
    + 嵌入搜索 + 一致的结构    。原子化提交单元 + 领域关键词 + 英文正文 + 明确的trailer是关键
5项核心原则是同时满足这4类读者的最低规则。有疑问时请回归这些原则。

0.1 Atomic — 한 commit = 한 의도

0.1 Atomic（原子化）——一次提交 = 一个意图

하나의 논리적 변경만 담는다. "fix + style + docs" 같이 묶지 말 것.
→ Bisect / revert / cherry-pick 모두 atomic 전제. AI도 mixed commit은 한쪽만 잡아 hallucinate.
판단: "이 commit을 revert해야 할 때 다른 변경까지 같이 revert하는가?" → YES면 split.
只包含一个逻辑变更。不要将“修复+样式+文档”这类内容合并提交。
→ Bisect / 回滚 / 拣选操作都基于原子化前提。AI对混合提交也只会抓取其中一部分，容易产生幻觉。
判断标准：“当我需要回滚这个提交时，是否会连带回滚其他无关变更？” → 如果是，就拆分提交。

0.2 Leaves repo green — 모든 commit은 green build

0.2 Leaves repo green（保持仓库可用）——每个提交都能构建成功

각 commit 직후 
tsc --noEmit
+ 
lint
+ 
build
통과해야 함. WIP / "next commit will fix this" 금지.
→ Bisect signal 신뢰성. broken-state commit이 끼면 "원인" 판정 부정확. AI 자동 분석도 같은 이유로 영향.
每个提交后必须通过
tsc --noEmit
+ 
lint
+ 
build
检查。禁止提交WIP（进行中）或“下一次提交会修复这个问题”的内容。
→ 保证Bisect信号的可靠性。如果存在损坏状态的提交，会导致“问题原因”的判定不准确。AI自动分析也会因此受到影响。

0.3 Why over what — diff가 못 알려주는 것만 본문에

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"
diff展示的是WHAT（做了什么）。正文要以**WHY（动机/权衡/放弃了哪些替代方案）**为核心。
→ 6个月后查看blame时能直接得到答案。AI无需diff上下文也能从提交正文中提取意图（减少diff推理成本和误解风险）。
❌ 正文: "modify foo.ts to add bar method"        (与diff重复)
✅ 正文: "extract bar() out of inline closure —    (原因)
        prevents re-allocation on every render
        causing useMemo deps invalidation"

0.4 Imperative mood — "If applied, this commit will..."

0.4 Imperative mood（命令式语气）——“如果应用此提交，它将……”

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     (수동태)
摘要使用命令式。与Git自带的消息（
Merge
、
Revert
）保持一致。
→ 一致的动词模式。Git工具和AI分类（生成changelog、推测类型）都依赖动词形式。
✅ 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

0.5 Searchable（便于搜索）——富含关键词的摘要和正文

도메인 명사 / 함수명 / 파일 경로 / 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)
明确写出领域名词/函数名/文件路径/权威来源名称/组件名称。模糊动词（
improve
、
update
、
enhance
）要补充对应的目标名词。
→ 支持
git log --grep
+ AI嵌入搜索。6个月后像“Idempotency-Key是在哪里添加的？”这类自然语言查询能直接命中正确的提交。AI对模糊关键词容易产生幻觉，对具体关键词则更准确。
❌ 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와의 관계

与英文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 모두 영문 기대.
§1-§14的所有规则与英文SKILL.md完全一致。本韩语变体仅将行文说明翻译成韩语。规则本身（小写摘要、命令式语气、英文正文政策等）不受变体影响。
§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原则的正文翻译成韩语**，以便韩语用户一次性理解核心规则的意图。其余部分相比每次触发时翻译成韩语，保持英文一致性更有价值——Git工具、AI模型、外部贡献者都默认使用英文。

작성 시 마음가짐 — 4가지 압축

撰写时的心态——4个要点

  1. Audience first: "6개월 후 내가 이 줄에 
    git blame
    찍었을 때 답이 나오나?"
  2. Atomic test: "revert할 때 다른 변경까지 끌고 가나?" → YES면 split
  3. Why over What: diff가 보여주는 것 다시 쓰지 말 것
  4. Searchable: vague 동사 금지. 도메인 명사 / 함수명 / 컴포넌트 이름 적기
이게 §0의 본질. 룰 14개 모두 이 4가지의 구현 디테일.
  1. 受众优先: "6个月后我对这行代码执行
    git blame
    时，能找到答案吗？"
  2. 原子化测试: "回滚时会连带其他变更吗？" → 如果是，就拆分提交
  3. 重原因轻内容: 不要重复diff已经展示的内容
  4. 便于搜索: 禁止使用模糊动词。要写上领域名词/函数名/组件名称
这就是§0原则的本质。14条规则都是这4个要点的具体实现细节。