dev-git-commit-message

Git 提交消息生成器

默认原则：优先使用主题行；只有在需要说明风险、原因或破坏性变更详情时才添加正文；除非仓库已定义自定义类型，否则只使用标准类型；绝不声称差异中未体现的行为。

规则：每次编码会话都会加载 rules/common/git.md 中的这项不变规则。

快速参考

需求	默认做法	参考
选择类型	feat/fix/perf/refactor/docs/test/build/ci/chore/style/revert	下方的类型选择表
编写主题行	type(scope): imperative summary，≤72 个字符（理想长度为 50），末尾不加句号	下方的仓库策略检查
标记破坏性变更	在类型/范围后加 !，或添加 BREAKING CHANGE: 页脚	下方的破坏性变更格式表
判断是否需要正文	仅在说明风险、不明显的原因或破坏性变更详情时添加	下方的正文是否必需？表
处理 AI 编写的提交	主题行和正文中均不标注归属；默认使用 Assisted-by: 页脚，也接受 Claude-Session: 和 Audit-*	下方的 AI 编写的提交
选择发布/变更日志工具	经审核的 PR 发布使用 release-please；全自动化使用 semantic-release；单体仓库使用 changesets	references/changelog-generation-guide.md
确定单体仓库提交范围	使用软件包/应用/服务目录名，深度一级，且长期保持稳定	references/monorepo-commit-conventions.md
在本地验证消息	python scripts/commit_validator.py validate --message "..."	下方的脚本部分

决策表

模式选择

触发条件	模式	操作
用户提供暂存的差异或要求提交	生成	检查暂存内容，生成首选项和备选项
用户提供现有消息字符串	验证	检查规则，返回 PASS/WARN/FAIL 和精确的改写版本
暂存的差异涉及互不相关的区域	拆分	建议先拆分为多个提交，再生成消息
没有暂存的更改	停止	报告“没有暂存的更改”

类型选择

feat 和 fix 在规范中具有 SemVer 含义；其他类型及其发布行为取决于仓库使用的工具。在声明版本升级前，请先阅读仓库的预设和发布规则。

更改	类型	备注
新增用户或 API 可见的功能	feat	触发 MINOR 升级
修正错误行为	fix	触发 PATCH 升级
可衡量的速度或内存改进	perf	按 semantic-release 的默认规则触发 PATCH 升级；请核实仓库规则
改进结构，行为不变	refactor	默认不发布
仅修改文档	docs	默认不发布
仅修改测试	test	默认不发布
构建工具或打包	build	默认不发布
CI/CD 工作流	ci	默认不发布
仓库维护，不涉及产品更改	chore	默认不发布
仅修改空白字符或格式	style	默认不发布
撤销先前的提交	revert	对发布的影响取决于工具；规范未明确规定撤销提交的处理方式
安全修复	fix(security):	优先使用标准类型加范围，而非自定义的 security: 类型
提示词/技能/YAML 行为更改	feat 或 fix	不要仅根据文件扩展名分类

范围选择

情况	操作
仓库在 config.yaml 中定义了范围映射	使用映射的范围
某个目录或软件包明显占主导	使用其名称，采用小写 kebab-case
更改同等涉及 2 个或更多稳定区域	使用更宽泛的父级范围，或省略范围
整个仓库范围内的更改	省略范围
包含独立版本化软件包的单体仓库	参见 references/monorepo-commit-conventions.md

是否需要正文？

条件	是否包含正文？
主题本身已清楚说明内容	否
主题无法明显说明原因	是 — 用一句话说明原因
涉及安全或有风险的更改	是 — 说明风险／回滚注意事项
破坏性更改	需要时包含迁移详情；如果主题已说明破坏性更改，仅使用 ! 也有效
调用方要求详细模板	是 — 使用 assets/template-commit-message.md

破坏性更改格式

标记	格式
行内标记	feat(api)!: change auth to OAuth2
页脚	BREAKING CHANGE: <migration summary>
两者	均可；页脚正文用于提供详情

前后示例

BAD:  update
GOOD: docs(readme): add deployment instructions

BAD:  fix stuff
GOOD: fix(cart): prevent negative quantity on rapid add

BAD:  feat: added user dashboard (past tense)
GOOD: feat(dashboard): add analytics overview panel

BAD:  feat: add search (generated by Copilot)
GOOD: feat(search): add full-text product search

BAD:  feat(api): add comprehensive user search endpoint with full-text search across all profile fields including bio and location
GOOD: feat(api): add full-text user search endpoint

BAD:  feat: add dashboard, fix auth bug, update deps  (mixed concerns)
GOOD: (3 separate commits)
      feat(dashboard): add analytics overview panel
      fix(auth): correct token refresh race condition
      chore(deps): update react to 18.3.0

工作流

1. 根据上方的模式选择表确定模式。
2. 对于生成模式，按以下顺序检查暂存的更改：
   • git diff --staged --name-status
   • git diff --staged --stat
   • 仅当类型、范围或风险不明确时，使用 git diff --staged --unified=1
3. 使用上方的表格判定类型和范围。
4. 首先从 config.yaml 检测范围，然后从最近的稳定目录检测。
5. 生成：提供一个主要建议；当范围或侧重点不明确时，最多提供两个备选方案，并附上简短理由。
6. 验证：应用仓库策略检查；返回 PASS/WARN/FAIL，若失败则提供准确的改写内容。随附的验证器会检查其默认规则；请另行检查目标仓库的覆盖规则。
7. 如果差异包含无关工作，在提供合并后的消息之前，建议拆分提交。

索引是提交边界

根据暂存区差异生成消息，而不是根据工作树差异。编写前，检查 git diff --cached --name-status 和 git diff --cached；另行检查 git diff --name-status，以免未暂存的编辑混入摘要。如果索引为空，请停止，不要描述未提交的工作。如果某个文件仅部分暂存，只描述已暂存的代码块，并指出同一路径仍有未暂存的更改。

对于生成文件、锁定文件和迁移文件，应说明导致这些文件变更的行为，而不是将它们列为独立成果。提交前，应立即再次根据暂存补丁验证拟定的主题，因为索引可能在起草和执行之间发生变化。

输出约定

生成

[NOTE] Suggested commit messages (3 files changed)

PRIMARY:
fix(auth): reject expired refresh tokens

ALTERNATIVES:
1. fix(api): reject expired refresh tokens
2. fix: reject expired refresh tokens during rotation

RATIONALE:
- Type: fix
- Scope: auth
- Signals: token validation path, regression test update, no new feature surface

验证

VALIDATION: WARN

Message:
feat: update stuff

Issues:
- `update stuff` is too vague
- summary should name the changed behavior or surface

Suggested fix:
feat(auth): add refresh token rotation

AI 编写的提交

提交消息应描述变更，而不是产出变更的工具。无论代码由人类还是 AI Agent 起草，都应遵循相同规则。

主题行和正文中禁止出现：generated by、via copilot、via claude、chatgpt、ai assistant、bot。署名只能放在最终的 trailer 块中。

AI 辅助工作需要审计记录时，推荐默认使用 Assisted-by: trailer。Co-authored-by: <ai-tool> 不是默认格式，且仍无法通过验证。不要将 trailer 放在主题行中。示例：

feat(search): add full-text product search

Assisted-by: LLM

接受的 AI trailer 都应放在同一个最终段落中，彼此之间不得有空行：

• Assisted-by: 推荐的默认格式；内核格式将工具列在模型之后（Assisted-by: LLM coccinelle sparse）
• Claude-Session: 某些 Agent 运行时会附加的会话链接
• Audit-*（例如 Audit-Batch: 和 Audit-Skill:）审计程序来源信息

任何其他提及 AI 工具的 trailer 都会验证失败。放在较早段落中的 trailer 对 git interpret-trailers 不可见，因此验证器会发出警告。

请使用目标项目文档规定的准确格式；各项目的格式各不相同。Assisted-by: 与 Co-Authored-By: 是不同的 trailer。上游项目尚未统一使用某一种格式，且其政策也会变化，因此添加任何 AI trailer 前，请阅读目标项目当前的贡献政策。值得查看的政策包括：Linux 内核的 coding-assistants 文档（要求使用列出大模型和工具的 Assisted-by: trailer；AI Agent 不得添加 Signed-off-by:，因为只有人类才能证明符合 DCO）、LLVM 的 AI 工具政策（将 Assisted-by: 列为 trailer 示例）、Apache 的生成式工具指导（Generated-by:），以及 QEMU 的代码来源政策（不接受 AI 生成的贡献）。如果仓库已按惯例使用 Co-Authored-By: <ai-tool>，不要擅自将其改写为 Assisted-by:——应指出两者的区别，由维护者决定；在已有提交历史后更改 trailer 惯例，会破坏通过 grep 搜索旧 trailer 的 blame/来源信息工具。

仓库政策检查

阻止或改写符合以下情况的消息：

• 缺少类型前缀（除非仓库的贡献指南或 AGENTS.md 声明其惯例是使用普通祈使式主题；此时生成不带前缀的 Imperative summary，并使用 --no-type-prefix 验证，该选项只跳过此规则）

• : 后缺少空格，或作用域为空；作用域默认为小写 kebab-case

• 使用含糊的摘要：update、fix stuff、change code、WIP、misc

• 在接受的 trailer 之外包含助手/工具署名（见上文）

• 夸大差异中看不出来的影响

• 类型前缀后使用过去时或动名词

• 主题行超过 72 个字符

• 主题行以句号结尾

• 使用 !、BREAKING CHANGE: 或 BREAKING-CHANGE: 标记破坏性变更；使用 ! 时，footer 可省略。

• 参考规范为 Conventional Commits v1.0.0。

• commitlint 支持的 Node 版本范围和配置格式会随主版本变化；编写配置文件前，请查阅其文档（见 data/sources.json）。

• 对于旧版 standard-version 配置，在提出迁移建议前，请阅读其仓库声明；其中推荐使用 release-please 或社区分支 commit-and-tag-version。

• release-please-action 会发布存在破坏性变更的主版本（运行器运行时和输入项变更）。固定工作流版本前，请查看其发布页面，确认当前主版本及其运行时要求，并使用提交 SHA 固定版本。

• 不要凭记忆引用 semantic-release 或任何发布工具的主版本；请先查看其发布页面。

脚本

脚本	用途
scripts/commit_validator.py	验证单条消息、检查历史记录文件，或生成 Markdown 质量报告

# Validate one message
python scripts/commit_validator.py validate --message "feat(auth): add refresh token rotation"

# Lint a batch history file
python scripts/commit_validator.py lint --input data/sample-commit-history.json

# Generate a full Markdown report
python scripts/commit_validator.py report --input data/sample-commit-history.json --output report.md

完整的快速入门、输入格式和规则参考，请参阅 scripts/README.md。

历史记录输入必须是非空对象数组，每个对象都包含字符串类型的 message；可选的 hash、author 和 date 也必须是字符串。两种历史记录命令都会在生成输出前拒绝空输入和格式错误的记录；文件错误会指出输入或输出路径。验证器使用随附的策略默认值，不会加载 config.yaml。

工作树 PR 循环

将此技能用作更广泛的工作树优先交付循环中的提交步骤；该循环定义于 ../dev-git-workflow/SKILL.md。

在该循环中：创建或进入功能工作树 → 修改代码 → 有意暂存 → 使用此技能 → 运行仓库门禁 → 发起 PR。

如果暂存的差异混合了多个互不相关的方面，请停止操作，并建议在发起 PR 前拆分提交。

已知陷阱

• 仅根据文件名推断范围，导致范围与仓库的有界上下文映射不符。
• 将互不相关的更改压缩到一条“整洁”的约定式提交中，破坏其对回滚和发行说明的实用性。
• 当差异中仍包含隐藏的迁移或破坏性更改时，将 AI 生成的摘要视为权威内容。
• 为通过 lint 检查而优化格式，却丢失维护者在事故追溯时需要的操作意图。
• 随意使用 ! 或 BREAKING CHANGE，造成下游自动化产生过多噪声。

导航

• config.yaml — 仓库专用的范围映射和验证默认值
• assets/template-commit-message.md — 面向复杂提交的可选详细正文模板
• assets/template-security-commits.md — 涉及安全的提交措辞指南
• references/conventional-commits-guide.md — 完整规范 v1.0.0、类型定义、破坏性更改和工具配置
• references/commit-message-antipatterns.md — 反模式目录、正则检测模式、commitlint 配置和 CI 示例
• references/monorepo-commit-conventions.md — 范围策略、按包生成变更日志、受影响包的 CI 路由
• references/changelog-generation-guide.md — 发布工具对比（standard-version 已弃用；GitHub 发布 PR 默认使用 release-please，按包生成 monorepo 变更日志则使用 changesets）
• data/sources.json — 用于工具验证的精选一手来源
• data/sample-commit-history.json — 包含 20 条提交的示例数据集，供 lint 和报告子命令使用
• 相关内容：../dev-git-workflow/SKILL.md — 分支、钩子、PR 工作流和发布自动化；分支/PR 策略请使用 dev-git-workflow，本技能用于提交消息规范

经验循环

当先前的决策或陷阱与当前情况相关时，如果存在 learnings.consolidated.md，请查阅该文件；仅在需要查看历史记录或其为可用备用文件时，才使用 learnings.md。否则跳过这两个文件。

应用后，如果遇到值得记住的模式，请通过 agents-skills-feedback-loop/scripts/append_learning.py 向 learnings.md 追加一条带日期的项目。不要修改 SKILL.md 本身。