git-commit-writer

name	git-commit-writer
description	Git 提交信息智能生成工具。基于 Claude 对代码改动和用户意图的深度分析，自动生成符合项目规范的 commit message，支持四层验证机制确保质量。 Use when this capability is needed.
metadata	{"author":"fsyyft-go"}

Git Commit Writer

概述

基于 Claude 智能分析的 Git 提交信息（commit message）生成工具，100% 大模型驱动，无需脚本。

核心特点：

• 🤖 Claude 驱动：完全依赖 Claude 的理解、分析和判断能力
• 🎯 智能分析：自动分析 git diff 和用户意图，识别改动类型和范围
• ✅ 四层验证：格式、一致性、语言、改动一致性严格验证
• 📝 直接输出：简洁高效，直接输出可用的 commit message

工作原理： Claude 分析 git diff + 用户上下文 → 自动判断类型和范围 → 生成符合规范的 commit message → 四层严格验证 → 输出最终结果

使用场景

• 日常开发提交
• 代码审查后修正
• 重构后的提交
• 多功能合并提交
• 紧急修复提交

快速开始

基本用法（默认暂存区模式）

# 默认：针对当前暂存区中的文件生成 commit message
"帮我为暂存的改动生成 commit message"
"分析暂存区并生成 commit"

未提交文件模式

# 如果没有暂存区，但有未提交的文件
"为未提交的改动生成 commit message"
"分析当前工作区的改动"

分支对比模式

# 指定分支：对比指定分支的所有变更
"为 develop 分支的变更生成 commit message"
"分析相对于 feature/skill 分支的所有改动"
"对比 master 分支，生成合并 commit message"

高级用法

# 结合 git diff 和用户上下文
"我为 web 服务添加了用户认证功能，帮我生成 commit message"
"修复了 data 层的数据库连接问题，生成 commit message"

最佳实践

• 明确指定分析范围（暂存区/未提交文件/分支）
• 提供简洁的改动意图说明
• 让 Claude 自主判断类型和范围

工作流程

分析范围判断阶段

用户输入分析
  ↓
判断用户是否指定分支？
  ├─ 是 → 进入分支对比模式
  │     ├─ 运行: git diff <target-branch> --name-only
  │     ├─ 运行: git diff <target-branch>
  │     └─ 获取所有变更文件和具体改动内容
  │
  └─ 否 → 进入默认模式
        ├─ 检查暂存区（git diff --staged --name-only）
        │     ├─ 有暂存文件 → 进入暂存区模式
        │     │     ├─ 运行: git diff --staged
        │     │     └─ 分析暂存的改动内容
        │     │
        │     └─ 无暂存文件 → 进入未提交文件模式
        │            ├─ 运行: git diff --name-only
        │            ├─ 运行: git diff
        │            └─ 分析未提交的改动内容
        │
        └─ 收集用户提供的上下文和意图说明

信息收集阶段

暂存区模式：

运行 git status → 确认暂存状态
运行 git diff --staged --name-only → 获取变更文件列表
运行 git diff --staged → 分析具体改动内容
识别文件类型和路径

未提交文件模式：

运行 git status → 确认工作区状态
运行 git diff --name-only → 获取变更文件列表
运行 git diff → 分析具体改动内容
识别文件类型和路径

分支对比模式：

运行 git status → 确认当前分支
运行 git diff <target-branch> --name-only → 获取变更文件列表
运行 git diff <target-branch> → 分析具体改动内容
识别文件类型和路径
识别变更涉及的 commit 数量和历史

共同步骤：

收集用户提供的上下文说明和改动意图
统计改动规模（文件数量、行数变化）
识别改动的关键特征

智能分析阶段

分析改动类型（新功能/bug修复/重构/文档等）
识别影响范围（web/task/api/internal 等）
提炼核心业务意图
判断改动的重要性和影响程度
识别与现有功能的关系

生成候选阶段

选择合适的 commit type（feat/fix/docs 等）
确定准确的 scope（标准范围或路径范围）
提炼简洁的中文描述（祈使句、首字母小写、不加句号）
生成完整的 commit message 格式

四层验证阶段

第一层：格式验证

• 检查 <类型>(<范围>): <描述> 格式
• 验证类型有效性（11 种之一）
• 验证范围可选性
• 验证描述非空

第二层：类型-范围一致性验证

• 检查类型与范围是否匹配
• 参考类型-范围映射表
• 验证逻辑合理性

第三层：语言和语法验证

• 检查中文表述规范性
• 检查语法正确性
• 避免口语化表达
• 验证长度要求（50 字以内）

第四层：代码改动一致性验证

• 对比 git diff 内容
• 验证 message 与改动是否一致
• 检查是否遗漏重要信息

输出结果阶段

直接输出最优的 commit message
提供简要的改动分析说明
标注验证通过的所有层级

四层验证机制

验证原则：四层验证必须全部通过，任何一层不通过都必须调整。

第一层：格式验证

验证规则：必须符合 <类型>(<范围>): <描述> 格式

正则表达式：^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([^)]+\))?: .+$

通过条件：

• 类型有效（11 种之一）
• 范围可选（如无范围，格式为 <类型>: <描述>）
• 描述不为空且以空格开头

不通过示例：

• ❌ 添加用户功能（缺少类型）
• ❌ Feat: 添加用户功能（类型大写）
• ❌ feat(web)（缺少描述）

第二层：类型-范围一致性验证

类型-范围映射表：

类型	推荐范围	可接受范围	不可接受范围
feat	api, web, task, internal, .claude/skills/*	docs	test, build
fix	data, biz, service, server, web, task	internal	docs, build, ci
docs	任意范围（包含具体路径）	-	-
style	internal, biz, service, data	-	api, docs
refactor	internal, biz, service, data, server	-	docs, test
perf	data, biz, service	internal	docs, test
test	biz, service, data	internal	docs, api
build	Makefile, go.mod, dockerfile	-	internal, biz
ci	.github/, .gitlab-ci.	-	internal, biz
chore	任意范围（维护性工作）	-	-
revert	与原 commit 相同的范围	-	-

通过条件：类型和范围必须在上表中匹配

不通过示例：

• ❌ test(api): 添加接口测试（test 不应在 api）
• ❌ feat(docs): 添加新功能（feat 应在代码文件）

第三层：语言和语法验证

中文表述规范：

• ✅ 使用标准现代汉语
• ✅ 语法正确，表述清晰
• ✅ 使用祈使句（添加、修复、更新、重构等）
• ✅ 首字母小写（除非专有名词）
• ✅ 结尾不加句号
• ❌ 避免口语化（"搞定"、"弄好"、"整一下"）
• ❌ 避免冗余（"了"、"一下"等）

通过条件检查：

1. 是否使用中文？
2. 是否使用祈使句？
3. 是否首字母小写？
4. 是否结尾无句号？
5. 是否无口语化表达？
6. 描述长度是否在 50 字以内？

不通过示例：

• ❌ feat: 添加了用户管理功能（使用"了"）
• ❌ fix: 修复数据连接的问题（"的"字冗余）
• ❌ feat: 添加用户功能。（结尾有句号）
• ❌ feat: 搞定数据库连接（口语化）

第四层：代码改动一致性验证

验证方法：对比生成的 message 与实际 git diff 内容

通过条件：

1. message 描述的改动类型与 diff 内容一致

   • feat: diff 中包含新增的函数/方法/接口
   • fix: diff 中包含错误修复或逻辑调整
   • refactor: diff 中主要是结构调整而非功能变化

2. message 指定的范围与 diff 中变更的文件路径一致

   • scope 为 web: 变更文件应在 cmd/web/ 或相关
   • scope 为 .claude/skills/*: 变更文件应在该路径下

3. message 描述的功能与 diff 内容匹配

   • 描述"添加用户管理"：diff 应包含用户管理相关代码
   • 描述"修复数据库连接"：diff 应包含数据库相关修复

4. 没有遗漏重要信息

   • Breaking change: 必须在 message 中体现
   • 重大功能: 必须准确描述
   • 安全修复: 必须明确说明

不通过示例：

• ❌ diff 显示修改了 10 个文件，但 message 只提到"添加用户功能"（过于笼统）
• ❌ message 说"修复 web 服务崩溃"，但 diff 主要改动在 data 层（范围不符）
• ❌ diff 包含 API 接口变更，但 message 未提及（遗漏重要信息）

验证流程控制：

第一层验证 → 通过 → 第二层验证 → 通过 → 第三层验证 → 通过 → 第四层验证 → 通过 → 输出
   ↓              ↓              ↓
 不通过          不通过          不通过
   ↓              ↓              ↓
 调整格式      调整类型/范围   优化语言      完善描述
   ↓              ↓              ↓
 重新验证       重新验证       重新验证       重新验证

核心规范摘要

Commit 类型列表（11 种）

• feat: 新功能
• fix: bug 修复
• docs: 文档变更
• style: 代码格式（不影响功能）
• refactor: 重构（不是新功能也不是修复）
• perf: 性能优化
• test: 测试相关
• build: 构建系统或外部依赖
• ci: CI 配置和脚本
• chore: 其他不修改 src 或 test 文件
• revert: 回退之前的 commit

范围选择规则

标准范围：web, task, api, internal, docs, build, ci, chore

路径范围：点号分隔的路径（如 .claude/skills/go-import-enforcer）

中文表述基本要求

• 必须使用中文
• 祈使句，首字母小写
• 结尾不加句号
• 简洁明了（50 字以内）
• 避免口语化表达

常见问题

Q: 如何处理多种类型的改动？

A: 识别主要改动类型：

• 70% 以上为一种类型 → 使用该类型
• 功能为主，修复为辅 → 拆分提交（feat + fix）
• 重构为主，新功能为辅 → 拆分提交（refactor + feat）
• 无法明确区分 → chore (需在描述中详细说明)

Q: 改动涉及多个范围怎么办？

A: 分析改动涉及的模块：

• 单一职责改动 → 选择最直接的范围
• 跨层改动 → 选择最上层的范围
• 全局性改动 → 不使用范围
• 配置性改动 → build 或 ci

Q: 如何描述重构性改动？

A: 判断改动本质：

• 主要是修复 bug → fix
• 主要是改进设计 → refactor
• 修复 + 轻微重构 → fix (在描述中说明)
• 重构 + 顺便修复 → refactor (在描述中说明)

Q: 如何避免描述过于笼统或过于细节？

A: 提炼核心意图：

• ✅ "添加用户管理功能"（适中）
• ❌ "添加功能"（过于笼统）
• ❌ "添加了包含增删改查的用户管理功能"（过于细节）

参考资料

详细的 commit 规范、丰富示例和决策流程，请参考：

• commit-standards.md - 完整的 commit message 规范定义
• examples.md - 项目实际示例和通用示例
• decision-workflows.md - 详细的决策流程和特殊场景处理

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.