tomevault-io 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 应在代码文件）
第三层：语言和语法验证
中文表述规范：
- ✅ 使用标准现代汉语
- ✅ 语法正确，表述清晰
- ✅ 使用祈使句（添加、修复、更新、重构等）
- ✅ 首字母小写（除非专有名词）
- ✅ 结尾不加句号
- ❌ 避免口语化（"搞定"、"弄好"、"整一下"）
- ❌ 避免冗余（"了"、"一下"等）
通过条件检查：
- 是否使用中文？
- 是否使用祈使句？
- 是否首字母小写？
- 是否结尾无句号？
- 是否无口语化表达？
- 描述长度是否在 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 - 详细的决策流程和特殊场景处理
Converted and distributed by TomeVault — claim your Tome and manage your conversions.