第01章：AI帮我写了commit message，但不符合Conventional Commits规范

第01章：AI帮我写了commit message，但不符合Conventional Commits规范

“AI 帮你生成了 commit message：‘fix bug’、‘update code’、‘add feature’——这种 message 在项目里存在了6个月之后，你需要找出3个月前那个让线上崩溃的变更是哪个，然后你发现 git log 完全帮不上忙。”

ℹ️ 版本说明：本章基于 Git 2.54.0 + Conventional Commits 1.0 规范。

1.1 AI默认会生成什么

你提交代码，让 AI 帮你写 commit message：

# AI 通常给你的 commit message
git commit -m "fix bug"
git commit -m "update user profile page"
git commit -m "add some changes"
git commit -m "WIP"

这些 message 不符合 Conventional Commits 规范，导致：

  • git log --oneline 完全看不出变更类型
  • 无法自动生成 CHANGELOG
  • CI/CD 无法根据 commit 类型触发不同流程（如只有 feat: 才触发版本升级）
  • 一年后你自己也不知道这个 commit 改了什么

1.2 AI通常遗漏的4个坑

⚠️ 坑1：Conventional Commits 规范 AI 默认不遵守

Conventional Commits 格式：

<type>[optional scope]: <description>

[optional body]

[optional footer]

常用 type：

  • feat: 新功能（对应 MINOR 版本升级）
  • fix: Bug 修复（对应 PATCH 版本升级）
  • docs: 文档变更
  • style: 代码格式（不影响逻辑）
  • refactor: 重构（既不是 feat 也不是 fix）
  • perf: 性能优化
  • test: 测试相关
  • chore: 构建工具/依赖管理（不涉及生产代码）
  • BREAKING CHANGE: 破坏性变更（对应 MAJOR 版本升级）

正确示例：

feat(auth): add OAuth2 login with GitHub

Implement GitHub OAuth2 flow using passport.js.
Users can now sign in with their GitHub account.

Closes #142

⚠️ 坑2：scope 不统一导致过滤失效

scope 的价值是让你能按模块过滤日志：

# 只看认证相关的提交
git log --oneline --grep="^feat(auth)"

# 只看API变更
git log --oneline --grep="^.*\(api\)"

如果同一个模块的 scope 写法不统一（auth、Auth、authentication、login），过滤就失效了。

应该在 .commitlintrc 里定义允许的 scope 列表：

{
  "rules": {
    "scope-enum": [2, "always", ["auth", "api", "ui", "db", "docs", "ci"]]
  }
}

⚠️ 坑3：没有 commitlint 强制规范

team 里定了规范，但没有工具强制执行——最终还是有人写 git commit -m "fix stuff"。

应该配置 commitlint + husky，在本地提交时检查 message 格式：

# 安装
npm install -D @commitlint/config-conventional @commitlint/cli husky
npx husky init

# .husky/commit-msg 文件
npx --no -- commitlint --edit $1

⚠️ 坑4：没有利用 commit message 自动生成 CHANGELOG

如果你的项目遵守 Conventional Commits，可以用工具自动生成 CHANGELOG：

# conventional-changelog-cli
npx conventional-changelog -p conventional -i CHANGELOG.md -s

# 或者用 semantic-release（CI/CD 自动发版）
npx semantic-release

1.3 更好的提示词

提示词 P01：生成规范的 commit message

使用时机：每次提交代码前，让 AI 帮你写符合规范的 message

比默认多了什么：

  • 遵守 Conventional Commits 格式
  • 根据变更内容选择正确的 type
  • 提供 body 和 footer（如有关联 issue）
根据以下 git diff，帮我写一个符合 Conventional Commits 1.0 规范的 commit message。

Git diff（或变更描述）：
[粘贴 git diff 输出，或描述你做了什么]

规范要求：
- 格式：<type>(<scope>): <description>
- type 必须是：feat/fix/docs/style/refactor/perf/test/chore 之一
- scope 使用我们项目的模块名（auth/api/ui/db/ci 之一）
- description：动词开头，英文，不超过72字符
- body（可选）：解释为什么这么做，不是做了什么
- footer（可选）：关联 issue（Closes #N）或 BREAKING CHANGE 说明

给我3个候选 message（从简到详），我来选一个。

示例格式：
fix(auth): prevent session fixation on login
feat(api): add rate limiting to /users endpoint  
docs(readme): update local development setup guide

提示词 P02：配置 commitlint + husky

使用时机：为项目配置 commit message 格式强制检查

比默认多了什么：

  • 完整的安装配置步骤
  • 自定义 scope 规则
  • CI 集成
帮我为一个 Node.js 项目（Next.js）配置 commitlint + husky，强制执行 Conventional Commits 规范。

项目信息：
- Node.js v24.16.0
- 使用 npm
- 项目的模块：auth, api, ui, db, docs, ci

需要完成：
1. 安装依赖：
   - @commitlint/config-conventional
   - @commitlint/cli
   - husky
   
2. 配置 .commitlintrc.json：
   - extends conventional
   - scope-enum 限制为我的模块列表
   - description 最大长度 72 字符
   
3. 配置 .husky/commit-msg hook：
   - 在本地提交时检查 message 格式
   - 格式错误时显示友好的错误提示

4. GitHub Actions 集成（CI 里也检查）：
   - 在 PR 时检查所有新 commit 的 message 格式

5. 给我测试命令，验证配置正确：
   - 用一个错误 message 触发报错（确认 hook 生效）
   - 用一个正确 message 通过检查

基于 Node.js v24.16.0 + Git 2.54.0。

提示词 P03：整理已有仓库的 commit 历史

使用时机：接手一个 commit message 混乱的老项目，需要了解历史

比默认多了什么：

  • 从混乱的 commit 历史里提取关键变更
  • 生成模块化的 CHANGELOG
帮我分析以下 Git 仓库的 commit 历史，整理出关键变更记录。

Git log 输出（git log --oneline -50 或更多）：
[粘贴 git log 输出]

帮我：
1. 从这些不规范的 commit message 里提取关键信息：
   - 哪些是功能变更（feat 类）？
   - 哪些是 Bug 修复（fix 类）？
   - 有没有破坏性变更（BREAKING CHANGE）？

2. 生成一份结构化的 CHANGELOG（按时间倒序）：
   ## [unreleased]
   ### Added
   - ...
   ### Fixed  
   - ...
   ### Changed
   - ...

3. 建议：
   - 这个项目的 commit 规范问题在哪里？
   - 如何避免未来继续积累混乱的历史？

基于 Git 2.54.0。

1.4 验收清单

检查项 验证方法 AI辅助
commit message 遵守 Conventional Commits git log --oneline 最近20条都符合格式 用 P01 生成 message
commitlint 已配置 用错误格式提交，确认被拒绝 用 P02 配置
scope 列表已定义 查看 .commitlintrc.json 里的 scope-enum 让 AI 检查配置
husky hook 生效 错误 message 提交被本地拦截 让 AI 测试 hook
CI 也检查 commit message PR 提交后，CI 检查所有新 commit 用 P02 的 GitHub Actions 配置
CHANGELOG 可自动生成 运行 changelog 工具有输出 让 AI 配置 conventional-changelog

1.5 本章小结

如果你只记一件事：让 AI 每次帮你写 commit message 时，都在提示词里说"遵守 Conventional Commits 规范，type 是 feat/fix/docs/refactor/chore 之一"。这一个习惯，让你的 git log 从垃圾场变成可查询的文档。

Commit 规范的三个层次：

  1. 有规范意识（知道要写好 commit message）：随机写好的，随机写烂的，没有强制
  2. 工具强制（commitlint + husky）：本地提交被检查，不符合规范无法提交
  3. 自动化收益（semantic-release / conventional-changelog）：release 自动判断版本号，CHANGELOG 自动生成

→ 第2章：AI帮我解决了 merge conflict，但搞乱了 commit history