约定式提交（Conventional Commits）与分支命名规范

分支名称和提交信息均须遵循 Conventional Commits v1.0.0 规范 —— 统一的命名方式可使工具自动生成功能变更日志（changelog）、强制执行语义化版本（SemVer）升级策略，并按关注点（concern）筛选提交历史。

分支命名

格式：/[issue-] —— 全小写，仅使用短横线（-）分隔单词，除斜杠（/）外不得包含其他特殊字符。

feat/user-authentication
feat/42-user-authentication
fix/login-race-condition
fix/87-login-race-condition
docs/api-reference-update
refactor/payment-module

若存在对应 issue，则应在分支名前缀中加入 issue 编号 —— GitHub 与 GitLab 会自动将其链接至 issue 系统，且能使 git log 输出立即追溯到问题追踪器。描述部分应控制在 50 个字符以内 —— 大多数 Git 图形界面在列表中显示分支名时即在此长度附近截断。请确保 type 准确反映当前工作内容 —— 这是读者快速理解分支意图的核心契约。

严禁 在分支名中包含 worktree —— Git worktree 是一种本地检出机制，不属于分支概念；将其混入分支名会将实现细节泄露至远程仓库，干扰其他协作者的理解。

Worktree 命名

Worktree 是本地检出目录，永远不会出现在远程仓库中。请统一将其置于 .claude/worktrees/ 目录下，并将分支名中的斜杠（/）替换为短横线（-）作为 worktree 目录名。

git worktree add .claude/worktrees/feat-user-authentication feat/user-authentication
git worktree add .claude/worktrees/fix-87-login-race-condition fix/87-login-race-condition

目录名与分支名保持镜像关系，以确保 git worktree list 输出清晰可读，且每个 worktree 可不依赖检出状态而直接追溯至其所属分支。创建新 worktree 前，请先运行 git worktree list —— 若已有 worktree 已覆盖相同分支，请复用该 worktree。

每个 worktree 应严格限定于单一分支。在他人 worktree 中开展无关工作，将导致变更归属模糊、清理操作易出错。

分支合并后请立即移除对应 worktree —— 可在本地完成合并后执行，也可在远程 Pull Request / Merge Request 关闭后执行。残留的 stale worktree 将不断累积，最终导致 git worktree list 输出难以阅读。

git worktree remove .claude/worktrees/feat-user-authentication   # 分支已在本地合并
git worktree prune                                                # 清理已删除目录的引用

提交信息格式

[optional scope]: 
[optional body]
[optional footer(s)]

类型（Types）：

规则：

• 主题行（subject line）长度 ≤ 72 字符 —— Git 日志及 GitHub/GitLab UI 会静默截断超长主题行
• 使用祈使语气（imperative mood）：写 add 而非 added —— 表达为指令而非历史记录
• 首字母不需大写，末尾不加句号 —— 确保变更日志（changelog）工具可统一解析
• 正文（body）须与主题行空一行分隔 —— 解析器依据首个空行切分 header/body
• 破坏性变更（breaking changes）：可在 type/scope 后添加 !，或在 footer 中添加 BREAKING CHANGE:（二者均触发 MAJOR 版本升级）—— 仅在正文中描述破坏性变更将无法被 changelog 工具识别
• revert 类提交 必须 在正文中包含 This reverts commit . —— git revert 命令自动生成此行，请勿手动删除
• 严禁 在提交信息中添加 Claude 签名、AI 代理署名，或为 Claude 或任何其他 AI 代理添加 Co-authored-by trailer

示例：

feat(auth): add JWT token refresh

fix: prevent race condition on concurrent requests

Introduce request ID and reference to latest request.
Dismiss responses from stale requests.

refactor!: drop support for Go 1.18

BREAKING CHANGE: Go 1.18 no longer supported; uses stdlib APIs from 1.21+

通过提交信息关闭 Issue

GitHub 与 GitLab 均支持识别提交信息中的关键词，并在该提交落地至默认分支（default branch）时自动关闭所引用的 issue。建议将 issue 引用置于 footer 区域（更优实践 —— 保持主题行简洁）。

关键词（不区分大小写）： close、closes、closed、fix、fixes、fixed、resolve、resolves、resolved

GitHub：

fix(auth): prevent token expiry race condition

Closes #42
Closes owner/repo#99

• 仅当合并至 默认分支（通常为 main）时触发
• 跨仓库引用：Closes owner/repo#42
• 批量关闭：Closes #42, closes #43
• 同样适用于 PR 描述（PR description）

GitLab：

feat: add dark mode support

Resolves #101
Closes group/project#42

• 仅当合并至 默认分支（各项目可单独配置）时触发
• 跨项目引用：Closes group/project#42
• 批量关闭：Closes #101, closes #102
• 同样适用于 MR 描述（MR description）

提示： 提交类型应与 issue 类型匹配 —— 如 fix: 用于关闭缺陷类 issue，feat: 用于关闭功能需求类 issue —— 此举可保障生成的 changelog 语义连贯、逻辑清晰。

常见错误

最佳实践

• 保持分支类型与提交类型一致 —— 如 feat/auth-* 分支 → 对应提交应为 feat(auth):
• 每一分支聚焦单一关注点 —— 在功能分支中混入修复类变更将导致 changelog 混乱难读
• 在单一分支内保持 scope 使用一致性 —— 如全程使用 feat(auth):，避免中途改为 feat(user):
• 合并且压缩（Squash merge）： 当对 PR/MR 执行 squash merge 时，该分支所有提交将被压缩为一条；此时 PR/MR 标题即成为最终提交信息。若标题未遵循 Conventional Commits 格式，changelog 生成将静默失败。因此，请务必在执行 squash 操作前设置好 PR 标题。