commit-summary

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Commit body writer

提交消息体生成工具

Produce the part of a commit message that is not recoverable from the diff. Whoever reads the commit later already has the diff; what they do not have is what the running code does that forced the change, which call reaches the broken path, what breaks for someone who updates, when the defect was introduced, and what was noticed and deliberately left alone.
Output the body text only — no subject line, no preamble, no commentary. The caller owns the subject.
生成提交消息中无法从diff中获取的内容。后续查看该提交的人已经能看到diff,但他们无法从diff中得知:是什么运行代码的行为驱动了此次变更、哪些调用会涉及到失效路径、更新后哪些功能会受影响、缺陷是何时引入的,以及哪些内容被发现后仍刻意保留原状。
仅输出消息体文本——不包含主题行、前言或评论。主题由调用者负责编写。

Arguments

参数

ArgumentBehavior
(empty)Analyze staged + unstaged changes
staged only
Analyze the index only
a commit refAnalyze that commit
anything elseTreat as additional instructions or context
参数行为
(空)分析已暂存和未暂存的变更
staged only
仅分析索引中的内容
提交引用分析指定提交
其他内容视为额外指令或上下文

Step 1: See the change

步骤1:查看变更

bash
git status --short
git diff
git diff --cached
Read the actual hunks, not just the stat. You need the semantics of the edit to weigh it.
bash
git status --short
git diff
git diff --cached
阅读实际的代码块(hunks),而不只是统计信息。你需要理解编辑的语义来评估变更类型。

Step 2: Weigh the change

步骤2:评估变更类型

Derive (Step 3) when the change alters behaviour, a contract, a public type, or a default, or when it fixes a defect.
Report (Step 4) when the change is mechanical (a rename, a mass import rewrite, a formatting pass), generated (lockfiles, build output, snapshots, regenerated trees), or purely additive scaffolding with no behaviour to describe.
Weight decides, not diff size. A one-line semantic fix derives. A rename across 30 files is one fact and reports.
A mixed change is weighed on its heaviest part: derive for the behaviour change, and give the mechanical remainder one line.
推导式生成(步骤3)适用于变更修改了行为、契约、公共类型或默认值,或是修复了缺陷的场景。
报告式生成(步骤4)适用于变更为机械性(如重命名、批量导入重写、格式调整)、生成式(如锁文件、构建输出、快照、重新生成的目录树),或是纯新增的脚手架代码且无行为可描述的场景。
评估依据是变更的性质而非diff的大小。一行语义修复属于推导式生成;跨30个文件的重命名属于报告式生成。
若为混合变更,则以最核心的部分为准:针对行为变更采用推导式生成,对剩余的机械性变更用一行描述。

Step 3: Derive

步骤3:推导式生成

Read
references/commit-body.md
and follow it. It carries the seven questions, the table of which code is authoritative for each kind of change, the evidence rules, the writing rules, and three worked bodies.
Three things from it that decide whether the output is worth its cost:
  • Answer against the code, not the diff. Open the implementation behind the declaration, the client behind the handler, the changelog behind the bump.
  • Skip any question with no real answer. Three honest paragraphs beat seven padded ones. Padding is the failure mode of this skill.
  • Never invent provenance. A hash appears only if a command returned it in this session; an enumerated call path is traced in the source or reproduced. No result means the paragraph is dropped, not softened.
  • Plain words, short sentences, in the register of the
    explain
    skill: trace the mechanism on real symbols instead of characterising it. Each paragraph opens on a past-tense verb, and the sentence after it is the reason, stated as behaviour.
When the caller hands over design rationale pulled out of source comments — a cleanup pass reporting "Suggested for commit message" — that text answers why the code is built this way. Fold it into the first paragraph. Do not append it as a block at the end.
Output paragraphs, blank-line separated, wrapped at 80.
阅读
references/commit-body.md
并遵循其中的规则。该文档包含七个问题、各类变更对应的权威代码表、证据规则、写作规则以及三个示例消息体。
其中有三点决定了输出内容的价值:
  • 基于代码而非diff作答。查看声明背后的实现、处理器背后的客户端、版本升级背后的变更日志。
  • 跳过无实际答案的问题。三段真实的描述胜过七段凑数的内容。凑数是本工具的失效模式。
  • 绝不编造来源信息。仅当本次会话中命令返回了哈希值时才添加哈希;枚举的调用路径必须是从源码中追踪或复现的。若无结果则直接省略该段落,而非含糊其辞。
  • 用词简洁、句子简短,遵循
    explain
    工具的风格:基于实际符号追踪机制,而非笼统描述。每段以过去式动词开头,紧随其后的句子说明行为层面的原因。
当调用者提供从源码注释中提取的设计依据(例如清理操作中标记为“建议用于提交消息”的内容)时,该内容解释了代码为何如此构建。需将其融入第一段,而非作为块内容附加在末尾。
输出段落以空行分隔,每行长度不超过80字符。

Step 4: Report

步骤4:报告式生成

For mechanical and generated changes, one sentence per line, two or three lines, past tense, no blank lines, no bullets:
Renamed `useToggle` to `useToggleGroup` across 31 call sites.
Regenerated the Codex wrapper symlink trees.
Name what a reader cannot see from the file list — the count, the mechanism, the tool that generated it. Do not invent a rationale paragraph for a change that has none.
对于机械性和生成式变更,每行一句话,共2-3行,使用过去式,无空行,无项目符号:
Renamed `useToggle` to `useToggleGroup` across 31 call sites.
Regenerated the Codex wrapper symlink trees.
说明读者无法从文件列表中得知的信息——数量、变更机制、生成工具。对于无理由的变更,请勿编造理由段落。

Repo conventions win

仓库优先原则

Check the project's
CLAUDE.md
,
AGENTS.md
, or
CONTRIBUTING.md
for commit conventions. A house style that caps body width, forbids paragraphs, prescribes a template, or requires another language overrides both formats above. Answer as many questions as it has room for, in order, and drop the rest.
查看项目的
CLAUDE.md
AGENTS.md
CONTRIBUTING.md
文件中的提交约定。若仓库风格规定了消息体宽度上限、禁止使用段落、指定了模板或要求使用其他语言,则以上两种生成格式均需遵循仓库约定。按顺序回答尽可能多的问题,超出空间的部分可省略。

Footer

页脚

Add only when it applies, after a blank line:
  • Fixes #123
    /
    Resolves #456
  • BREAKING CHANGE: <what changed>
  • Co-authored-by: <a human's name> <email>
仅在适用时添加,需放在空行之后:
  • Fixes #123
    /
    Resolves #456
  • BREAKING CHANGE: <what changed>
  • Co-authored-by: <a human's name> <email>

No attribution

无需署名

The body ends on its last paragraph. Emit no "Drafted with AI" or "Generated with" line, no session or transcript link, no
<sub>
line, no
---
rule, no badge, and no
Co-Authored-By
trailer crediting an assistant. Never copy one forward from an existing message — a trailer already in the log is not licence to repeat it.
This skill returns text and never runs
git commit
, so it cannot be the only guard. The skill that assembles the final message strips these on the way to the commit — see
build:commit
step 5 and
issue-flow
Step 3.
消息体以最后一段结尾。请勿添加“由AI草拟”或“由XX生成”的行、会话或转录链接、
<sub>
行、
---
分隔线、徽章,也请勿添加标注助手的
Co-Authored-By
尾部信息。切勿从现有消息中复制此类信息——日志中已有的尾部信息并非重复添加的许可。
本工具仅返回文本,从不执行
git commit
命令,因此无法作为唯一的校验机制。组装最终消息的工具会在提交前移除这些内容——详见
build:commit
步骤5和
issue-flow
步骤3。

Out of scope

超出范围的内容

  • Subject lines, conventional-commit types, and issue-number suffixes.
  • Running
    git commit
    . This skill returns text.
  • Splitting a change into multiple commits. Question 7 makes the seam visible; the caller decides what to do about it.
  • PR bodies and release notes. Different audience, different contract.
  • 主题行、规范提交类型和问题编号后缀。
  • 执行
    git commit
    命令。本工具仅返回文本。
  • 将变更拆分为多个提交。问题7会指出拆分点,但最终由调用者决定如何操作。
  • PR描述和发布说明。受众不同,要求也不同。