git-workflow

全面的 Git 工作流技能，涵盖约定式提交、语义化分支命名、PR 模板和合并策略。在所有项目中强制保持一致，以减少评审摩擦并支持自动生成变更日志。

此技能与 worktree-manager-skill 互为补充（后者负责并行开发），为这些 worktree 中的提交和 PR 提供约定。

<quick_start> 约定式提交格式：

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

[optional body]

[optional footer(s)]

类型： feat、fix、docs、style、refactor、perf、test、build、ci、chore

示例：

git commit -m "feat(auth): add JWT refresh token rotation

Implements automatic token refresh 5 minutes before expiry.
Closes #123"

分支命名： <type>/<ticket>-<short-description>

git checkout -b feat/AUTH-123-refresh-tokens

</quick_start>

<success_criteria> 符合以下条件时，Git 工作流即为成功：

• 所有提交都遵循约定式提交格式
• 分支名称遵循 <type>/<ticket>-<description> 模式
• PR 使用统一模板，包含摘要、测试计划和检查清单
• 合并策略与分支类型相匹配（功能分支使用 squash，发布分支使用 merge）
• 提交历史清晰地呈现变更脉络
• 未经团队明确同意，不得强制推送到 main/master </success_criteria>

<conventional_commits>

约定式提交规范

基于 conventionalcommits.org

提交类型

类型	描述	变更日志章节	版本递增
feat	新功能	功能	Minor
fix	错误修复	错误修复	Patch
docs	仅修改文档	-	-
style	格式调整，不改动代码	-	-
refactor	代码变更，不涉及功能或错误修复	-	-
perf	性能优化	性能	Patch
test	添加或修复测试	-	-
build	构建系统变更	-	-
ci	CI 配置	-	-
chore	维护任务	-	-

破坏性变更

在类型后添加 !，或在页脚中添加 BREAKING CHANGE:：

# Method 1: Bang notation
feat(api)!: change response format to JSON:API

# Method 2: Footer
feat(api): change response format to JSON:API

BREAKING CHANGE: Response structure changed from { data } to { data, meta, links }

范围指南

范围是可选的，但建议填写。请在每个项目中保持范围一致：

# Good scopes
auth, api, ui, db, config, deps

# Examples
feat(auth): add OAuth2 support
fix(api): handle null response from external service
docs(readme): add installation instructions

提交消息结构

<type>(<scope>): <subject>
│       │         │
│       │         └─> Summary in present tense, no period, max 50 chars
│       │
│       └─> Component/area affected (optional)
│
└─> Type: feat, fix, docs, style, refactor, perf, test, build, ci, chore

[blank line]
[optional body - explain what and why, not how]
[blank line]
[optional footer(s) - breaking changes, issue references]

正例与反例

反例	正例	原因
fixed bug	fix(auth): prevent token expiry race condition	具体且有范围
updates	refactor(api): extract validation middleware	描述了变更
WIP	feat(ui): add loading skeleton (WIP)	意图明确
misc changes	chore: update dependencies to latest versions	类型明确且有意义
</conventional_commits>

<branch_naming>

分支命名约定

模式

<type>/<ticket-id>-<short-description>

分支类型

类型	用途	示例
feat/	新功能	feat/AUTH-123-oauth-login
fix/	错误修复	fix/API-456-null-response
hotfix/	紧急生产修复	hotfix/PROD-789-payment-failure
docs/	文档	docs/README-update
refactor/	代码重构	refactor/cleanup-legacy-api
test/	添加测试	test/add-auth-integration
chore/	维护	chore/update-deps
release/	发布分支	release/v2.1.0

命名规则

1. 仅使用小写字母 - feat/auth-login，不要用 feat/Auth-Login
2. 单词之间使用连字符 - fix/null-response，不要用 fix/null_response
3. 有工单 ID 时应包含 - feat/JIRA-123-description
4. 保持简短 - 最长 50 个字符，包括类型前缀
5. 描述清楚 - feat/user-profile，不要用 feat/feature1

受保护的分支

分支	保护规则	合并策略
main	要求 PR 和评审	Squash 合并
develop	要求 PR	Merge commit
release/*	要求 PR 和 CI 通过	Merge commit

示例

# Feature work
git checkout -b feat/PROJ-123-user-authentication

# Bug fix
git checkout -b fix/PROJ-456-login-redirect-loop

# Hotfix (from main)
git checkout main
git checkout -b hotfix/PROJ-789-payment-timeout

# Documentation
git checkout -b docs/api-endpoint-reference

# Chore
git checkout -b chore/upgrade-node-20

</branch_naming>

<pr_templates>

Pull Request 模板

标准 PR 模板

## Summary

-

## Type of Change

- [ ] feat: New feature
- [ ] fix: Bug fix
- [ ] docs: Documentation
- [ ] refactor: Code restructuring
- [ ] test: Test coverage
- [ ] chore: Maintenance

## Test Plan

- [ ] Unit tests added/updated
- [ ] Integration tests pass
- [ ] Manual testing completed

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Documentation updated (if needed)
- [ ] No console.log or debug code
- [ ] No sensitive data exposed

## Related Issues

Closes #

## Screenshots

精简 PR 模板（适用于小型变更）

## What


## Why


## Test


Closes #

发布 PR 模板

## Release v{VERSION}

### Changes Since Last Release


### Breaking Changes


### Migration Guide


### Deployment Notes


### Rollback Plan

</pr_templates>

<merge_strategies>

合并策略

按分支类型选择策略

分支类型	策略	理由
feat/*	Squash	在 main 中保留一条整洁的提交记录
fix/*	Squash	在 main 中保留一条整洁的提交记录
hotfix/*	Merge	保留热修复历史记录
release/*	Merge	保留发布提交记录
refactor/*	Squash 或 Rebase	视提交数量而定

Git 命令

# Squash merge (recommended for features)
git checkout main
git merge --squash feat/my-feature
git commit -m "feat(scope): description"

# Merge commit (for releases)
git checkout main
git merge --no-ff release/v2.0.0

# Rebase (for clean linear history)
git checkout feat/my-feature
git rebase main
git checkout main
git merge feat/my-feature

# Interactive rebase (clean up before PR)
git rebase -i HEAD~5

Squash 与 Merge 决策树

Is this a feature or fix branch?
├── Yes → Squash merge
└── No → Is this a release or hotfix?
    ├── Yes → Merge commit (preserve history)
    └── No → Consider context

</merge_strategies>

<commit_hooks>

提交钩子（可选强制执行）

commitlint 配置

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [2, 'always', [
      'feat', 'fix', 'docs', 'style', 'refactor',
      'perf', 'test', 'build', 'ci', 'chore'
    ]],
    'scope-case': [2, 'always', 'lowercase'],
    'subject-case': [2, 'always', 'sentence-case'],
    'subject-max-length': [2, 'always', 72],
    'body-max-line-length': [2, 'always', 100],
  }
};

Husky 设置

# Install
npm install -D husky @commitlint/cli @commitlint/config-conventional

# Initialize
npx husky init

# Add commit-msg hook
echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg

提交前检查

# .husky/pre-commit
#!/bin/sh
npm run lint
npm run test -- --run

</commit_hooks>

## 语义化版本

版本格式

MAJOR.MINOR.PATCH
  │     │     │
  │     │     └─> Bug fixes (fix:)
  │     │
  │     └─> New features (feat:)
  │
  └─> Breaking changes (feat!: or BREAKING CHANGE:)

版本升级规则

提交类型	示例	版本变更
fix:	fix: null check	1.0.0 → 1.0.1
feat:	feat: new endpoint	1.0.1 → 1.1.0
feat!:	feat!: new API format	1.1.0 → 2.0.0

自动版本管理

# Using standard-version
npx standard-version

# Using semantic-release (CI)
npx semantic-release

<workflow_examples>

完整工作流示例

功能开发

# 1. Create feature branch
git checkout main
git pull origin main
git checkout -b feat/PROJ-123-user-profile

# 2. Make commits (conventional format)
git add .
git commit -m "feat(ui): add profile avatar component"
git commit -m "feat(api): add profile update endpoint"
git commit -m "test(profile): add integration tests"

# 3. Rebase if needed
git fetch origin
git rebase origin/main

# 4. Push and create PR
git push -u origin feat/PROJ-123-user-profile
gh pr create --title "feat(profile): add user profile page" \
  --body "## Summary\n- Add profile avatar\n- Add update endpoint\n\nCloses #123"

# 5. After approval, squash merge
gh pr merge --squash

热修复流程

# 1. Create from main
git checkout main
git pull origin main
git checkout -b hotfix/PROD-456-payment-timeout

# 2. Fix and commit
git commit -m "fix(payment): increase timeout to 30s

Production payments timing out during high load.
Closes PROD-456"

# 3. Push and merge (no squash to preserve hotfix history)
git push -u origin hotfix/PROD-456-payment-timeout
gh pr create --title "hotfix: payment timeout" --body "Emergency fix"
gh pr merge --merge

发布流程

# 1. Create release branch
git checkout develop
git checkout -b release/v2.1.0

# 2. Version bump
npm version minor
git commit -am "chore(release): v2.1.0"

# 3. Merge to main
git checkout main
git merge --no-ff release/v2.1.0
git tag v2.1.0

# 4. Back-merge to develop
git checkout develop
git merge release/v2.1.0

</workflow_examples>

## Git 工作流检查清单

每次提交前：

• 提交信息符合约定格式
• 类型准确（feat/fix/docs 等）
• 作用范围与受影响的组件相符
• 主题使用祈使语气和现在时
• 重大变更通过 ! 或页脚标记

创建 PR 前：

• 分支名称符合约定
• 已基于最新的 main/develop 进行变基
• 所有提交都有意义（合并修正提交）
• 已完整填写 PR 模板
• 已关联相关问题

合并前：

• 所有 CI 检查均已通过
• 已获得所需审查
• 没有合并冲突
• 已选择正确的合并策略

如需了解详细规范，请加载相应参考资料：

主题	参考文件	加载时机
提交信息示例	reference/commit-examples.md	需要更多示例时
PR 模板变体	reference/pr-templates.md	需要项目专用模板时
Git 钩子设置	reference/git-hooks.md	设置强制执行机制时

加载方式： 请求特定主题，或根据上下文判断是否需要加载。

输出结果旁文件

写入 ~/.claude/skill-analytics/last-outcome-git-workflow.json： {"ts":"[UTC ISO8601]","skill":"git-workflow","version":"1.0.0","variant":"default","status":"[success|partial|error]","runtime_ms":[ms],"metrics":{"commits_created":[n],"prs_opened":[n],"branches_managed":[n]},"error":null,"session_id":"[YYYY-MM-DD]"}