第 06 期 | /caveman-commit — 让 Git 提交信息回归本质

🎯 学习目标

学完本期你将掌握：

1. /caveman-commit 的输出规则与格式规范
2. "Why over What" 原则——为什么比是什么更重要
3. 在五大平台上使用 caveman-commit 的方式
4. 与 Git Hook (prepare-commit-msg) 的自动集成

📖 核心内容

6.1 为什么 Commit Message 需要 Caveman？

你见过这样的 commit message 吗？

❌ 糟糕的 commit (真实案例):

"Updated the authentication middleware to properly validate token 
expiry by checking if the token's expiration timestamp is less than 
or equal to the current time instead of using a strict less-than 
comparison, which was causing tokens that expire at exactly the 
current second to not be properly caught and rejected"

这不是 commit message，这是一篇论文摘要。

Caveman 风格：

✅ fix(auth): token expiry use <= not <

13 个字符。同样的信息。git log --oneline 里完美显示。

6.2 caveman-commit 的三大规则

graph TD
    A["caveman-commit 规则"]
    
    A --> B["📏 长度约束
主题行 ≤ 50 字符"]
    A --> C["📋 格式规范
Conventional Commits"]
    A --> D["🧠 内容原则
Why over What"]
    
    B --> B1["git log --oneline 完美对齐
不会被截断"]
    C --> C1["type(scope): message
feat/fix/docs/chore/refactor"]
    D --> D1["说明'为什么做'
而非'做了什么'"]

规则 1：Conventional Commits 格式

<type>(<scope>): <description>

type 枚举:
  feat     → 新功能
  fix      → Bug 修复
  docs     → 文档变更
  chore    → 杂务 (依赖更新、配置等)
  refactor → 重构 (不改变行为)
  perf     → 性能优化
  test     → 测试
  ci       → CI/CD 变更
  style    → 代码格式 (不影响逻辑)

规则 2：主题行 ≤ 50 字符

✅ fix(auth): token expiry use <= not <       (38 chars)
✅ feat(api): add rate limiting per user       (39 chars)
✅ refactor(db): extract query builder         (40 chars)

❌ feat(api): add comprehensive rate limiting mechanism with sliding window (73 chars → 被截断!)

规则 3：Why over What

❌ What (描述做了什么 — 代码已经能看到):
"change < to <= in token check"

✅ Why (说明为什么做 — 代码看不到):
"fix(auth): token expiry use <= not <"
↑ 隐含了"因为边界条件导致 token 在过期瞬间被放行"

❌ What:
"add try-catch around database call"

✅ Why:
"fix(db): handle connection timeout gracefully"

6.3 使用方法

在 Claude Code 中

# 完成代码修改后
> /caveman-commit

# Claude 会分析你的 staged changes 并生成:
# fix(auth): token expiry use <= not <
#
# 然后你可以:
> 用这个 message 提交
# 或
> git commit -m "fix(auth): token expiry use <= not <"

在 Antigravity 中

# 自然语言触发
> 帮我用 caveman-commit 风格写一个 commit message

# 或者在 GEMINI.md 中配置了 caveman 规则后:
> 分析我的改动，写一个精炼的 commit message

在 Gemini CLI 中

> /caveman-commit
# Gemini 会分析当前 diff 并输出精炼的 commit message

在 Codex 中

> $caveman-commit
# Codex 使用 $ 前缀触发技能

在 OpenCode 中

# 自然语言触发 (无斜杠命令)
> 用 caveman 风格写 commit message，分析当前 staged changes

6.4 实战 Before / After 对比

6.5 与 Git Hook 自动集成

你可以将 caveman-commit 与 Git 的 prepare-commit-msg Hook 结合，实现自动化：

#!/bin/bash
# .git/hooks/prepare-commit-msg

# 如果是 merge commit 或 amend，跳过
case "$2" in
    merge|squash) exit 0 ;;
esac

# 如果 commit message 已经有内容（非模板），跳过
if [ -s "$1" ] && [ "$(head -1 "$1")" != "" ]; then
    exit 0
fi

# 获取 staged changes 的 diff
DIFF=$(git diff --cached --stat)

# 用 Claude Code 生成 caveman-style commit message
# (需要 claude CLI 在 PATH 中)
MSG=$(echo "Generate a caveman-commit message for this diff. Rules: Conventional Commits, ≤50 chars, why over what. Diff: $DIFF" | claude --print 2>/dev/null)

if [ -n "$MSG" ]; then
    echo "$MSG" > "$1"
fi

graph LR
    A["git commit"] --> B["prepare-commit-msg Hook"]
    B --> C["读取 staged diff"]
    C --> D["调用 Agent
生成 caveman-commit"]
    D --> E["写入 commit message"]
    E --> F["打开编辑器
(可修改)"]
    F --> G["✅ 提交完成"]

📊 五大平台 Commit 工作流对比

📝 本期要点回顾

1. /caveman-commit 生成 Conventional Commits 格式的精炼提交信息
2. 三大规则：≤50 字符主题行 + Conventional Commits + Why over What
3. 所有平台都支持，但触发方式不同（Claude Code 用 /，Codex 用 $，其他用自然语言）
4. 可与 Git 的 prepare-commit-msg Hook 集成实现自动化
5. 关键心法：commit message 应该告诉读者 "为什么" 而不是 "做了什么"

🔗 参考资料

• Caveman Commit Skill
• Conventional Commits 规范
• Git Hooks 文档