conventional-commits

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Conventional Commits

When to Use

使用场景

The user asks for a commit message from currently staged changes.

当用户请求根据当前暂存的变更生成提交消息时。

When NOT to Use

不适用场景

The user wants a generic explanation of Conventional Commits — answer normally.

当用户想要了解Conventional Commits的通用解释时——正常作答即可。

Core Policies

核心规则

These rules MUST NOT be violated under any circumstance.

Act on the current state. Generate immediately from the current staged state on every invocation; never ask the user about type, scope, or body inclusion, and never reuse cached results.
Output language. Default to Korean. If the user explicitly requests a different language in this invocation, use that language instead. Type and footer keywords and the optional scope token always stay English.
Output discipline. Emit the message as a single
```
plaintext
```
fenced code block conforming to the reference spec, with content in the language from Policy 2 — no preamble, no analysis recap inside the block. Use imperative present tense in the description ("add", "fix", "remove" — not "added", "adds", "adding") for English output; for other languages, use the language's neutral, action-oriented register. The only exception to this block-only format is the empty-staging notice in Workflow step 2.

以下规则在任何情况下都不得违反。

基于当前状态操作：每次调用时都根据当前暂存状态立即生成消息；绝不询问用户关于类型、范围或是否包含正文的问题，也绝不复用缓存结果。
输出语言：默认使用韩语。若用户在本次调用中明确要求其他语言，则使用该语言。类型、页脚关键字以及可选的范围标记始终保持英文。
输出规范：将消息作为单个符合参考规范的
```
plaintext
```
代码块输出，内容采用规则2指定的语言——代码块内不得包含前言或分析总结。英文输出时描述部分使用祈使现在时（"add"、"fix"、"remove"——而非"added"、"adds"、"adding"）；其他语言则使用该语言中立、面向动作的语体。此纯代码块格式的唯一例外是工作流程步骤2中的空暂存提示。

Workflow

工作流程

Load the reference. Read
```
references/conventional-commits-1.0.0.md
```
(alongside this
```
SKILL.md
```
); defer to it when in doubt.
Scan staged scale (fail-fast). Run
```
git diff --staged --stat
```
.
- If empty, reply with the single line below (in the language from Core Policy 2) and stop:
  No staged changes found. Run
  git add
  and try again.
- Otherwise, record the list of changed files and classify the change as small / moderate / large.
Gather priors. Before reading the diff, collect interpretation signals: run
```
git branch --show-current
```
(a name like
```
feature/payment-retry
```
is a prior for type via the prefix
```
feature/
```
/
```
fix/
```
/
```
hotfix/
```
/
```
refactor/
```
/
```
docs/
```
, scope via the trailing slug, and footers via embedded issue keys like
```
PROJ-123
```
or
```
#456
```
becoming
```
Refs:
```
/
```
Closes:
```
candidates), then
```
git log -n 10 --stat
```
to learn the repo's commit conventions (header tone, common scopes, body style, footer usage); for commits that touch any file from step 2 or clearly share its feature area, inspect with
```
git show <sha>
```
to recover the "why" the diff alone cannot show, and skip commits with no overlap.
Read the diff.
- Small or moderate: run
```
git diff --staged
```
  and read it whole.
- Large: start with
```
git diff --staged
```
  for the overall picture, then drill into high-signal files via
```
git diff --staged -- <path>
```
  — prioritizing largest change volume; public APIs, configuration, schemas, or data models; and paths that reveal the primary intent. Stop drilling once you can answer every item in step 5; summarize the rest from
```
--stat
```
  .
Analyze intent.
- What and why. State the dominant behavioral or structural delta in one sentence, and the motivation behind it. Use this why-source priority (higher beats lower when they disagree): user's extra explanation in the current turn → branch name and embedded issue keys from step 3 → new comments, docstrings, or test descriptions added in the diff → recent related commit messages from step 3 → the code itself.
- Type. Pick exactly one from the de facto standard set enforced by
```
@commitlint/config-conventional
```
  :
```
build
```
  ,
```
chore
```
  ,
```
ci
```
  ,
```
docs
```
  ,
```
feat
```
  ,
```
fix
```
  ,
```
perf
```
  ,
```
refactor
```
  ,
```
revert
```
  ,
```
style
```
  ,
```
test
```
  . Apply these path-class heuristics first, then refine with diff semantics:
  - Only
```
*.md
```
    ,
```
docs/**
```
    ,
```
README*
```
    ,
```
LICENSE
```
    →
```
docs
```
    .
  - Only
```
*test*
```
    ,
```
tests/**
```
    ,
```
__tests__/**
```
    ,
```
*.spec.*
```
    →
```
test
```
    .
  - Only
```
.github/workflows/**
```
    ,
```
.gitlab-ci.yml
```
    ,
```
.circleci/**
```
    ,
```
Jenkinsfile
```
    →
```
ci
```
    .
  - Only build/dependency files (
```
package.json
```
    , lockfiles,
```
Dockerfile
```
    ,
```
pyproject.toml
```
    ,
```
go.mod
```
    ,
```
Cargo.toml
```
    ,
```
Makefile
```
    ) →
```
build
```
    .
  - Only formatting/whitespace/import-order changes with no behavior change →
```
style
```
    .
  - Diff is purely a revert of an earlier commit →
```
revert
```
    , with a
```
Refs: <sha>
```
    footer naming the reverted SHA(s).
  - Diff adds a new user-visible capability →
```
feat
```
    .
  - Diff repairs a stated or evident defect →
```
fix
```
    .
  - Same external behavior, restructured internals →
```
refactor
```
    .
  - Measurable speed, memory, or throughput improvement (with the diff showing the mechanism) →
```
perf
```
    .
  - Maintenance with no user-visible effect and none of the above →
```
chore
```
    .
  - When two types compete, prefer
```
fix
```
    >
```
feat
```
    >
```
perf
```
    >
```
refactor
```
    > any maintenance type (
```
test
```
    ,
```
docs
```
    ,
```
build
```
    ,
```
ci
```
    ,
```
style
```
    ) >
```
chore
```
    .
- Scope token. Add when nearly all changes fall within one clearly-named area (top-level directory, module, feature flag) or the branch-name slug from step 3 matches; omit when changes span multiple areas or no obvious name dominates.
- Breaking change. Flag if the change forces consumers to modify their code, configuration, schema, CLI usage, or deployment — e.g., removed/renamed public APIs; changed function or method signatures; removed/renamed configuration keys or environment variables; non-backward-compatible schema migrations; changed CLI flags or output formats. Indicate per the reference (
```
!
```
  after type/scope and/or a
```
BREAKING CHANGE: <description>
```
  footer). Otherwise record "none."
- Mixed intent. When changes mix unrelated types, pick the type for the dominant change by volume and significance, and mention the secondary changes briefly in the body. Do not ask the user.
- Body. Include when the "why" is non-obvious from the header, when there are secondary changes to mention, or when there is a breaking change to describe. Otherwise omit.
Compose and output. Write the message from the step-5 decisions and emit per Core Policy 3. For Korean output, also apply the Korean Writing Rules.

加载参考文档：读取
```
references/conventional-commits-1.0.0.md
```
（与本
```
SKILL.md
```
同级）；如有疑问以该文档为准。
扫描暂存规模（快速失败）：执行
```
git diff --staged --stat
```
。
- 若结果为空，回复以下单行内容（采用核心规则2指定的语言）并终止流程：
  未找到暂存变更。执行
  git add
  后重试。
- 否则，记录已变更文件列表并将变更分类为小型/中型/大型。
收集前置信息：在读取diff之前，收集解释信号：执行
```
git branch --show-current
```
（类似
```
feature/payment-retry
```
的分支名称可通过前缀
```
feature/
```
/
```
fix/
```
/
```
hotfix/
```
/
```
refactor/
```
/
```
docs/
```
推断类型，通过后缀推断范围，通过嵌入的问题编号如
```
PROJ-123
```
或
```
#456
```
推断
```
Refs:
```
/
```
Closes:
```
等页脚候选），然后执行
```
git log -n 10 --stat
```
了解仓库的提交规范（标题语气、常用范围、正文风格、页脚使用方式）；对于涉及步骤2中任何文件或明显属于同一功能领域的提交，通过
```
git show <sha>
```
查看以获取仅靠diff无法体现的“原因”，跳过无重叠的提交。
读取diff
- 小型或中型变更：执行
```
git diff --staged
```
  并完整读取内容。
- 大型变更：先执行
```
git diff --staged
```
  了解整体情况，再通过
```
git diff --staged -- <path>
```
  深入查看高信号文件——优先关注变更量最大的文件；公共API、配置、 schema 或数据模型；以及能揭示主要意图的路径。停止深入的条件是能够回答步骤5中的所有问题；其余内容通过
```
--stat
```
  结果总结。
分析意图
- 内容与原因：用一句话说明主要的行为或结构变化及其背后的动机。原因来源优先级如下（优先级高的覆盖优先级低的）：用户在本次对话中的额外说明 → 步骤3中的分支名称和嵌入的问题编号 → diff中新增的注释、文档字符串或测试描述 → 步骤3中近期相关的提交消息 → 代码本身。
- 类型：从
```
@commitlint/config-conventional
```
  强制执行的事实标准集合中选择恰好一个类型：
```
build
```
  、
```
chore
```
  、
```
ci
```
  、
```
docs
```
  、
```
feat
```
  、
```
fix
```
  、
```
perf
```
  、
```
refactor
```
  、
```
revert
```
  、
```
style
```
  、
```
test
```
  。先应用以下路径分类启发式规则，再根据diff语义细化：
  - 仅修改
```
*.md
```
    、
```
docs/**
```
    、
```
README*
```
    、
```
LICENSE
```
    →
```
docs
```
  - 仅修改
```
*test*
```
    、
```
tests/**
```
    、
```
__tests__/**
```
    、
```
*.spec.*
```
    →
```
test
```
  - 仅修改
```
.github/workflows/**
```
    、
```
.gitlab-ci.yml
```
    、
```
.circleci/**
```
    、
```
Jenkinsfile
```
    →
```
ci
```
  - 仅修改构建/依赖文件（
```
package.json
```
    、锁文件、
```
Dockerfile
```
    、
```
pyproject.toml
```
    、
```
go.mod
```
    、
```
Cargo.toml
```
    、
```
Makefile
```
    ） →
```
build
```
  - 仅修改格式/空白字符/导入顺序且无行为变化 →
```
style
```
  - Diff纯粹是撤销之前的提交 →
```
revert
```
    ，并添加
```
Refs: <sha>
```
    页脚注明被撤销的SHA值
  - Diff添加了新的用户可见功能 →
```
feat
```
  - Diff修复了明确或明显的缺陷 →
```
fix
```
  - 外部行为不变，仅重构内部结构 →
```
refactor
```
  - 可测量的速度、内存或吞吐量提升（diff中体现了实现机制） →
```
perf
```
  - 无用户可见影响且不属于上述类型的维护工作 →
```
chore
```
  - 当两种类型冲突时，优先级为
```
fix
```
    >
```
feat
```
    >
```
perf
```
    >
```
refactor
```
    > 任何维护类型（
```
test
```
    、
```
docs
```
    、
```
build
```
    、
```
ci
```
    、
```
style
```
    ） >
```
chore
```
- 范围标记：当几乎所有变更都属于一个明确命名的区域（顶级目录、模块、功能标志）或与步骤3中的分支名称后缀匹配时添加；当变更跨多个区域或无明显主导名称时省略。
- 破坏性变更：如果变更迫使使用者修改其代码、配置、schema、CLI用法或部署方式，则标记为破坏性变更——例如：删除/重命名公共API；修改函数或方法签名；删除/重命名配置项或环境变量；非向后兼容的schema迁移；修改CLI标志或输出格式。按照参考规范标记（在类型/范围后添加
```
!
```
  和/或添加
```
BREAKING CHANGE: <description>
```
  页脚）。否则记录为“无”。
- 混合意图：当变更混合了不相关类型时，根据变更的规模和重要性选择主导类型，并在正文中简要提及次要变更。不得询问用户。
- 正文：当“原因”无法从标题中明显看出、存在次要变更需要提及或存在破坏性变更需要描述时添加。否则省略。
撰写并输出：根据步骤5的决策撰写消息，并按照核心规则3输出。若为韩语输出，还需遵循韩语书写规范。

Korean Writing Rules

韩语书写规范

Header: no trailing period; ending with an action noun (추가, 수정, 변경, 삭제, 개선) reads naturally; keep around 25–40 Korean characters.
Body: declarative endings (
```
-습니다
```
,
```
-합니다
```
); explain what and why, skip how; omit entirely for trivial changes.

标题：末尾不加句号；以动作名词（추가、수정、변경、삭제、개선）结尾更自然；长度保持在25–40个韩文字符左右。
正文：使用陈述式结尾（
```
-습니다
```
、
```
-합니다
```
）；解释内容和原因，省略实现方式；微小变更可完全省略正文。