name	git-commit-writer
description	Git 提交信息智能生成工具。基于 Claude 对代码改动和用户意图的深度分析，自动生成符合项目规范的 commit message，支持四层验证机制确保质量。

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
提供简要的改动分析说明
标注验证通过的所有层级

四层验证机制

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

第一层：格式验证

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

通过条件：

类型有效（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 应在代码文件）

第三层：语言和语法验证

中文表述规范：

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

通过条件检查：

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

不通过示例：

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

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

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

通过条件：

message 描述的改动类型与 diff 内容一致
- feat: diff 中包含新增的函数/方法/接口
- fix: diff 中包含错误修复或逻辑调整
- refactor: diff 中主要是结构调整而非功能变化
message 指定的范围与 diff 中变更的文件路径一致
- scope 为 web: 变更文件应在 cmd/web/ 或相关
- scope 为 .claude/skills/*: 变更文件应在该路径下
message 描述的功能与 diff 内容匹配
- 描述"添加用户管理"：diff 应包含用户管理相关代码
- 描述"修复数据库连接"：diff 应包含数据库相关修复
没有遗漏重要信息
- 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 - 详细的决策流程和特殊场景处理

git-commit-writer

Install Skill

SKILL.md

Git Commit Writer

概述

使用场景

快速开始

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

未提交文件模式

分支对比模式

高级用法

最佳实践

工作流程

分析范围判断阶段

信息收集阶段

智能分析阶段

生成候选阶段

四层验证阶段

输出结果阶段

四层验证机制

第一层：格式验证

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

第三层：语言和语法验证

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

核心规范摘要

Commit 类型列表（11 种）

范围选择规则

中文表述基本要求

常见问题

参考资料