git-workflow-and-versioning

git-workflow-and-versioning 快速入门

用 Google 的 Git 规范管理你的代码,Trunk-based + 原子提交 + Conventional Commits。

这是什么?解决什么问题?

Git 工作流门派众多:Git Flow、GitHub Flow、GitLab Flow、Trunk-based Development……每种都有适用场景。但 Google 这样的大型工程组织,内部用的是相对简单的 Trunk-based,核心原则是:

• 主分支永远可发布:不存在”长期分支”
• 短生命周期特性分支:用完即删
• 原子提交:每次提交只做一件事,可独立 revert
• Conventional Commits:提交信息有规范,自动化友好 git-workflow-and-versioning 是 Addy Osmani 出品的 Skill,它把 Google 内部推荐的 Git 实践系统化,让 AI 在你写代码时:
• 自动按 Conventional Commits 规范生成提交信息
• 提示你拆分过大的提交
• 推荐合适的分支策略
• 自动生成 CHANGELOG
• 协助版本号管理(语义化版本) 适合中小型团队,尤其是希望简化 Git 流程、提升协作效率的团队。

准备工作

• Git 2.30+
• 一个支持 Agent Skill 的 AI 客户端
• 现有 Git 仓库(或新建)
• 基本的 Git 命令熟练度
• 至少 20 分钟时间

3 步快速上手

第 1 步:克隆仓库

git clone https://github.com/addyosmani/agent-skills.git
cd agent-skills
ls skills/git-workflow-and-versioning/

你会看到 SKILL.md、Conventional Commits 规范、提交模板。

第 2 步:加载 Skill

claude --skill git-workflow-and-versioning

第 3 步:让 AI 帮你规范化提交

修改了一些代码后,git status 看到一堆变更:

git status
# modified: src/api/users.py
# modified: tests/api/test_users.py
# new file: docs/api/users.md

输入:

“请帮我规范化这次提交。按 Conventional Commits 拆分成原子提交,并生成合适的提交信息。”

AI 会分析变更,建议拆分:

建议拆分成 3 个原子提交:
1. feat(api): add user creation endpoint
   - src/api/users.py: 新增 POST /users 接口
   - 验证: pytest tests/api/test_users.py::test_create_user
2. test(api): add tests for user creation
   - tests/api/test_users.py: 新增 test_create_user
3. docs(api): document user creation endpoint
   - docs/api/users.md: 接口文档

并给出每个提交的具体 git 命令:

git add src/api/users.py
git commit -m "feat(api): add user creation endpoint

POST /users accepts JSON body with email, password, name.
Returns 201 with user object on success, 409 on duplicate email.
Refs: #123"

git add tests/api/test_users.py
git commit -m "test(api): add tests for user creation

Cover happy path, duplicate email, validation errors."

git add docs/api/users.md
git commit -m "docs(api): document user creation endpoint"

常见踩坑

1. 巨型提交:一次提交改了 50 个文件、几千行,review 时根本看不懂。Skill 强制拆分。

2. 提交信息不规范:“fix bug”、“update”、“一些修改” 这种信息无用。Skill 强制 Conventional Commits。

3. 提交不独立 revert:一个提交里改了 3 件事,如果其中一件要回退,其他两件也被一起 revert。原子提交解决这个。

4. 长期分支:feature 分支开了 3 个月没合,合并冲突一大堆。Skill 推荐短生命周期分支。

5. 直接 push 到 main:没有 review、没有 CI 就合并,质量无法保证。Skill 强制 PR 流程。

6. 版本号混乱:手动改 package.json 版本号,经常出现多个分支版本不一致。Skill 推荐用 release-please 等自动化工具。

初级用法

• 提交信息自动化:用 Skill 让 AI 帮你写规范的 commit message。

• 分支命名规范:让 AI 帮你起分支名,如 feat/user-creation、fix/login-bug。

• PR 描述生成:Skill 自动生成结构化 PR 描述(做了什么、为什么、怎么测试)。

高级玩法

• 自动生成 CHANGELOG:Conventional Commits 提交可以用 release-please、standard-version 自动生成 CHANGELOG.md。

• 语义化版本:根据提交类型自动 bump 版本号:feat → minor,fix → patch,feat! → major。

• 提交即保存点:每个原子提交都是独立的”保存点”,可以单独 revert 而不影响其他工作。

小技巧

• 提交时用 git add -p(交互式暂存)更精细,Skill 会建议你拆分。

• 不要在提交信息里写”和 XXX 一起改”,这是把多个不相关变更打包的借口。

• Conventional Commits 类型:feat、fix、docs、style、refactor、test、chore、perf、build、ci。

• 重大变更用 feat!: 或 BREAKING CHANGE: footer 标注,会触发 major 版本 bump。

• 主分支保护:GitHub/GitLab 设置 main 分支需要 PR + CI 通过才能合并。

• 配合 git-commit-helper Skill 使用,提交信息质量更高。

常见问题 FAQ

Q1: 这个 Skill 跟 git-workflow-and-versioning 有什么关系?必须装吗?

A: Skill 是给 AI Agent 用的”技能包”,能告诉 Agent 怎么按特定规范工作。不是必须装——如果你的项目规模小、要求不高,不装也能用。但装上能让 Agent 输出的质量更高、更符合最佳实践,推荐装。

Q2: 这个 Skill 适合哪些 AI Agent?Cursor?Claude Code?其他?

A: git-workflow-and-versioning 来自 Google,主要面向支持 Skill 机制的 Agent。常见兼容 Agent 包括 Claude Code、Cursor、OpenCode、Windsurf 等。具体兼容性请查 Skill 官方文档。

Q3: 装了这个 Skill 后,会拖慢 Agent 响应吗?

A: 会的——Skill 通常会增加 prompt 长度,导致响应变慢、token 消耗增加。但质量提升明显。建议:1) 只装项目必需的 Skill;2) 用 Skill 启动/加载/卸载机制按需加载;3) 定期清理不用的 Skill。

Q4: 怎么验证 Skill 装对了?

A: 在 Agent 中输入”列出已加载的 Skill”或类似命令。如果 Skill 出现在列表里,说明装对了。然后用 Skill 跑一个相关任务,看输出是否符合 Skill 规范。

Q5: 这个 Skill 有许可证吗?能商用吗?

A: 取决于 git-workflow-and-versioning 的许可证。常见许可证包括 MIT(完全自由)、Apache-2.0(自由但有专利条款)、源可用(可看不能用)、GPL(强开源)。商用前请查仓库 LICENSE 文件。

参考链接

• 仓库
• Conventional Commits 规范
• Trunk-based Development
• Semantic Versioning
• release-please 自动化发布
• 经典书《Team Topologies》(Google 工程组织)