名称: git-storytelling-commit-messages 描述: 使用于编写清晰传达变更并讲述开发故事的提交消息。帮助创建信息丰富、结构良好的提交消息，作为文档。 允许工具:
- Bash
- Read
Git故事化 - 提交消息
这个技能指导您如何编写清晰、信息丰富且讲述开发过程的提交消息。良好的提交消息是伴随代码的文档。
核心原则
提交消息的用途
提交消息服务于多个受众和目的：
- 未来开发者（包括您自己）理解为什么进行更改
- 代码审查者评估更改的意图和范围
- 项目经理跟踪进度和理解交付内容
- 自动化工具生成变更日志和发布说明
- Git工具如blame、log和bisect用于调试
三部分结构
有效的提交消息遵循一致的结构：
- 主题行：简短摘要（50字符以内）
- 正文（可选）：详细解释什么和为什么
- 页脚（可选）：问题引用、重大更改、合作作者
主题行格式
<类型>: <描述>
示例:
feat: 添加用户认证系统
fix: 解决支付处理中的竞态条件
docs: 更新v2端点的API文档
提交消息解剖
主题行规则
应该：
- 以类型前缀开头（feat、fix、docs等）
- 使用祈使语气（“添加”而不是“已添加”或“添加了”）
- 保持在50字符以内
- 不以句号结尾
- 冒号后首字母大写
- 具体和描述性
不应该：
- 使用模糊术语如“更新东西”或“修复问题”
- 包含文件名除非必要
- 描述如何完成（代码显示细节）
- 使用过去时
- 太通用
正文指南
正文应解释：
- 什么改变了（简要，代码显示细节）
- 为什么需要更改
- 任何副作用或影响
- 考虑的替代方案
- 不明显的上下文
格式：
- 每行换行在72字符
- 使用项目符号表示多个项目
- 与主题行用空行分隔
- 使用适当段落进行复杂解释
页脚元素
引用: #123, #456
关闭: #789
重大更改: API端点/用户现在需要认证
合作作者: Jane Doe <jane@example.com>
🤖 由 [Claude Code](https://claude.com/claude-code) 生成
合作作者: Claude <noreply@anthropic.com>
提交类型
feat: 新功能
用于添加新功能或能力。
feat: 添加密码重置功能
实现带邮箱验证的密码重置流程：
- 生成安全重置令牌
- 发送带过期的重置邮件
- 在允许密码更改前验证令牌
- 记录密码重置事件用于安全审计
🤖 由 [Claude Code](https://claude.com/claude-code) 生成
合作作者: Claude <noreply@anthropic.com>
fix: 错误修复
用于纠正缺陷或意外行为。
fix: 防止重复订单提交
添加客户端去抖和服务器端幂等检查
以防止用户在快速点击时意外提交相同订单
多次。
关闭: #234
🤖 由 [Claude Code](https://claude.com/claude-code) 生成
合作作者: Claude <noreply@anthropic.com>
docs: 文档
用于仅文档更改。
docs: 添加数据库选择的架构决策记录
记录为什么我们选择PostgreSQL而不是MongoDB作为
主要数据存储，包括性能基准和
团队专业知识考虑。
🤖 由 [Claude Code](https://claude.com/claude-code) 生成
合作作者: Claude <noreply@anthropic.com>
refactor: 代码重构
用于改进代码而不改变行为。
refactor: 将认证逻辑提取到中间件
将认证检查从单独的路由处理程序
移动到可重用中间件以减少重复并改进
可维护性。
认证行为无功能更改。
🤖 由 [Claude Code](https://claude.com/claude-code) 生成
合作作者: Claude <noreply@anthropic.com>
test: 测试更改
用于添加或修改测试。
test: 添加支付流程的集成测试
添加端到端测试覆盖：
- 成功支付处理
- 失败支付处理
- 退款处理
- Webhook事件处理
测试覆盖率从65%提高到82%。
🤖 由 [Claude Code](https://claude.com/claude-code) 生成
合作作者: Claude <noreply@anthropic.com>
perf: 性能改进
用于改进性能的更改。
perf: 优化用户仪表板中的数据库查询
替换N+1查询模式为单个JOIN查询，减少
对于100+项目的用户，仪表板加载时间从2.3s到0.4s。
在user_id和created_at列添加数据库索引。
🤖 由 [Claude Code](https://claude.com/claude-code) 生成
合作作者: Claude <noreply@anthropic.com>
style: 格式化更改
用于空白、格式化、缺少分号等。
style: 用prettier格式化代码
在所有TypeScript文件中应用prettier格式化
以保持一致的代码风格。无功能更改。
🤖 由 [Claude Code](https://claude.com/claude-code) 生成
合作作者: Claude <noreply@anthropic.com>
chore: 维护任务
用于例行任务、依赖更新、构建更改。
chore: 升级依赖到最新稳定版本
更新所有npm包以解决安全漏洞：
- express: 4.17.1 -> 4.18.2
- axios: 0.21.1 -> 1.4.0
- jest: 27.0.6 -> 29.5.0
升级后所有测试通过。
🤖 由 [Claude Code](https://claude.com/claude-code) 生成
合作作者: Claude <noreply@anthropic.com>
代码示例
示例1: 带上下文的功能
feat: 实现Webhook签名验证
添加入站Webhook的HMAC-SHA256签名验证
以确保请求是真实的且未被篡改。
实现细节：
- 从X-Webhook-Signature头部验证签名
- 使用时序安全比较以防止时序攻击
- 无效签名返回401
- 记录可疑Webhook尝试
生产启动前所需的安全措施。
引用: #567
🤖 由 [Claude Code](https://claude.com/claude-code) 生成
合作作者: Claude <noreply@anthropic.com>
示例2: 带根本原因的修复
fix: 解决事件监听器清理中的内存泄漏
事件监听器在组件挂载时添加但未在
卸载时移除，导致内存积累和浏览器
在多次导航循环后变慢。
根本原因: useEffect钩子中缺少清理函数。
解决方案: 返回清理函数以在组件卸载时移除所有事件监听器。
此错误影响广泛导航应用而不刷新的用户，
特别在10+页面转换后明显。
关闭: #892
🤖 由 [Claude Code](https://claude.com/claude-code) 生成
合作作者: Claude <noreply@anthropic.com>
示例3: 带动机的重构
refactor: 用async/await替换回调地狱
转换嵌套回调式错误处理为async/await
模式以提高可读性和可维护性。
之前: 5层嵌套回调
之后: 线性async/await流程
好处：
- 更容易理解错误处理
- 阅读代码时减少认知负担
- 更简单地向流程添加新步骤
- 调试时更好的堆栈跟踪
无行为更改，所有现有测试通过。
🤖 由 [Claude Code](https://claude.com/claude-code) 生成
合作作者: Claude <noreply@anthropic.com>
示例4: 重大更改
feat: 迁移到带重大更改的v2 API
更新API客户端以使用改进错误处理
和响应格式的v2端点。
重大更改: 响应格式已更改
- 旧: { data: {...}, status: "ok" }
- 新: { result: {...}, success: true }
迁移指南:
1. 更新响应处理程序以使用'result'而不是'data'
2. 检查'success'布尔值而不是状态字符串
3. 错误响应现在包括'error.code'字段
所有内部服务已更新。第三方集成者
需要更新其代码。
引用: #1001
🤖 由 [Claude Code](https://claude.com/claude-code) 生成
合作作者: Claude <noreply@anthropic.com>
示例5: 性能优化
perf: 为频繁访问数据实现Redis缓存
为不常更改但每次请求访问的用户配置文件数据
添加Redis缓存层。
指标：
- 缓存命中率: 1小时流量后94%
- 平均响应时间: 450ms -> 45ms
- 数据库负载: 减少80%
缓存失效策略:
- 1小时后过期
- 配置文件更新时失效
- 缓存未命中时回退到数据库
通过REDIS_URL环境变量配置。
引用: #445
🤖 由 [Claude Code](https://claude.com/claude-code) 生成
合作作者: Claude <noreply@anthropic.com>
示例6: 安全修复
fix: 净化用户输入以防止XSS攻击
在渲染前转义用户生成内容中的HTML实体
以防止跨站脚本攻击。
漏洞: 用户可以在配置文件
bio字段注入<script>标签，这会在其他用户浏览器中执行。
修复: 使用DOMPurify库净化所有用户输入
在存储和渲染前。
受影响字段:
- 用户配置文件bio
- 评论内容
- 自定义状态消息
安全严重性: 高
生产中无已知利用。
关闭: #778
🤖 由 [Claude Code](https://claude.com/claude-code) 生成
合作作者: Claude <noreply@anthropic.com>
示例7: 配置更改
chore: 配置自动依赖更新
设置Dependabot以自动检查和创建
依赖更新的PR，按每周计划。
配置:
- 每周检查npm依赖
- 测试通过后自动合并补丁更新
- 次要/主要更新需要手动审查
- 按依赖类型分组更新
这将帮助我们保持安全补丁最新
并减少手动维护负担。
🤖 由 [Claude Code](https://claude.com/claude-code) 生成
合作作者: Claude <noreply@anthropic.com>
示例8: 回滚
revert: 回滚Redis缓存实现
回滚“perf: 为频繁访问数据实现Redis缓存”
由于缓存失效错误导致向用户提供过时数据，回滚。
缓存策略需要重新设计以正确处理所有更新场景。
发现问题:
- 部分配置文件更新未失效缓存
- 缓存写入和数据库写入之间的竞态条件
- 高负载下的缓存踩踏
将在后续PR中重新实现并修复。
引用: #445
🤖 由 [Claude Code](https://claude.com/claude-code) 生成
合作作者: Claude <noreply@anthropic.com>
何时使用此技能
使用此技能当：
- 为任何代码更改编写提交消息
- 在开发工作流中创建提交
- 准备代码审查的提交
- 为开源项目贡献
- 在具有共享git历史的团队项目中工作
- 记录重要技术决策
- 创建发布说明或变更日志
- 使用git bisect调试问题
- 教导他人git最佳实践
- 建立团队git约定
最佳实践
-
提交前编写提交消息 - 思考消息有助于澄清提交内容
-
使用祈使语气 - “添加功能”而不是“已添加功能”或“添加了功能”
-
用空行分隔主题和正文 - 许多git工具所需
-
限制主题行在50字符 - 迫使您简洁和周到
-
正文在72字符换行 - 保持消息在各种工具中可读
-
解释为什么，而不是什么 - 代码显示什么改变了，消息解释为什么
-
引用问题和PR - 在代码和需求之间创建可追溯性
-
使用约定提交格式 - 实现自动化变更日志生成
-
在页脚中包含重大更改 - 对语义版本控制关键
-
提及副作用 - 提醒他人非明显后果
-
配对时列出合作作者 - 给予应有信用
-
具体范围 - “fix: 解决登录错误”而不是“fix: 认证中的错误”
-
描述解决的问题 - 不仅仅是实施的解决方案
-
包括相关指标 - 性能改进、测试覆盖率等
-
使用一致术语 - 匹配代码库和文档中使用的术语
常见陷阱
-
模糊主题行 - “修复错误”无任何有用信息
-
主题行中包含过多细节 - 细节保存到正文
-
使用过去时 - “已修复错误”而不是“修复错误”
-
缺少正文解释 - 非明显更改需要上下文
-
仅为自己编写 - 记住其他人会阅读
-
描述实现而不是意图 - 专注于为什么
-
忘记引用问题 - 破坏可追溯性
-
不一致的提交类型 - feat/feature/add混合使历史混乱
-
主题和正文之间无空行 - 在许多工具中破坏格式
-
主题行以句号结尾 - 不必要且浪费字符限制
-
编写文章长度的提交消息 - 简洁但完整
-
修正时未更新提交消息 - 旧消息可能不再准确
-
通用消息如“更新”或“更改” - 这些提供零价值
-
将文件名放入主题 - 通常从差异中明显
-
缺少重大更改警告 - 可能破坏下游消费者
资源
Git文档
工具
git commit- 标准提交命令git commit --amend- 修改最后一次提交消息git log --oneline- 查看缩写提交历史git log --format=fuller- 查看完整提交信息git show <commit>- 查看完整提交详情git rebase -i- 编辑历史提交消息
检查您的消息
# 查看最近提交消息
git log --oneline -10
# 查看带差异的完整提交消息
git show HEAD
# 检查主题行是否太长
git log --format="%h %s" | awk 'length($0) > 52 { print }'
# 查看当前分支的所有提交消息
git log main..HEAD --format="%B"
# 按作者查看提交
git log --author="您的名字" --format="%h %s"
消息模板
创建提交消息模板：
# 创建模板文件
cat > ~/.gitmessage << EOF
# <类型>: <主题>
# <正文>
# <页脚>
# 类型可以是:
# feat (新功能)
# fix (错误修复)
# refactor (重构代码)
# style (格式化、缺少分号等)
# test (添加缺少测试)
# docs (文档更改)
# chore (更新构建任务、依赖等)
# perf (性能改进)
EOF
# 配置git使用模板
git config --global commit.template ~/.gitmessage
预提交钩子
使用commit-msg钩子强制执行消息格式：
#!/bin/bash
# .git/hooks/commit-msg
commit_msg=$(cat "$1")
pattern="^(feat|fix|docs|style|refactor|test|chore|perf):"
if ! echo "$commit_msg" | grep -qE "$pattern"; then
echo "错误: 提交消息必须以类型前缀开头"
echo "示例: feat: 添加新功能"
exit 1
fi
# 检查主题行长度
subject=$(echo "$commit_msg" | head -n1)
if [ ${#subject} -gt 50 ]; then
echo "警告: 主题行超过50字符"
echo "长度: ${#subject}"
fi
exit 0
相关技能
- git-storytelling-commit-strategy: 何时提交和频率
- git-storytelling-branch-strategy: 为清晰开发叙事管理分支
- code-reviewer: 良好提交消息如何改进代码审查
高级模式
多组件更改
当更改影响多个组件时：
feat: 添加用户通知系统
实现跨应用的实时通知：
后端更改:
- 添加推送通知的WebSocket服务器
- 在数据库中创建通知存储
- 实现通知API端点
前端更改:
- 向头部添加通知铃图标
- 创建通知面板组件
- 连接到WebSocket以获取实时更新
更改跨越客户端和服务器以交付完整
通知功能。
引用: #234, #235, #236
🤖 由 [Claude Code](https://claude.com/claude-code) 生成
合作作者: Claude <noreply@anthropic.com>
带测试的错误修复
修复错误时，包括测试信息：
fix: 处理日期格式化中的null值
日期格式化器在传递null时会抛出异常，
导致整个页面崩溃。
修复: 添加null检查并为null日期返回空字符串。
测试: 添加单元测试以验证null处理和边缘情况
对于undefined、空字符串和无效日期格式。
之前: 应用在null日期上崩溃
之后: 优雅处理所有无效日期输入
关闭: #567
🤖 由 [Claude Code](https://claude.com/claude-code) 生成
合作作者: Claude <noreply@anthropic.com>
带迁移说明的依赖更新
chore: 升级React 17到React 18
更新React到版本18以改进并发渲染
和自动批处理功能。
执行的迁移步骤:
1. 更新react和react-dom到18.2.0
2. 替换ReactDOM.render为createRoot
3. 更新新渲染API的测试配置
4. 验证所有组件与新并发功能兼容
解决的重大更改:
- 更新enzyme到React 18兼容版本
- 替换弃用的生命周期方法
- 修复依赖于同步渲染的测试
所有测试通过，无视觉回归检测。
引用: #789
🤖 由 [Claude Code](https://claude.com/claude-code) 生成
合作作者: Claude <noreply@anthropic.com>
结论
精心编写的提交消息是对项目未来的投资。它们作为文档，帮助调试，促进代码审查，并讲述软件如何演变的故事。通过遵循这些指南并使周到的提交消息成为习惯，您将创建一个有价值、可搜索且可维护的git历史。
记住: 您的提交消息是伴随代码永久的文档。让它们有意义。