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 文件。

进阶学习建议

如果想进一步用好 git-workflow-and-versioning,建议按以下路径学习:

第 1 周:熟练使用

• 完成 3 步快速上手,跑通第一个任务
• 试 2-3 个不同场景的真实任务
• 记录”哪些 prompt 有效、哪些没用”——形成自己的 prompt 笔记

第 2 周:理解机制

• 阅读 Skill 的官方文档(README、SKILL.md)
• 了解 Skill 的”触发关键词”和”输出格式”
• 学习”如何用更具体的描述触发 Skill”

第 3-4 周:组合使用

• 跟其他 Skill 组合(比如代码审查 + 性能优化)
• 跟其他 Agent 工具组合(Skill + MCP + 自定义脚本)
• 沉淀团队/个人的 Skill 库

长期:贡献社区

• 把自定义的 Skill 开源到 GitHub
• 提 PR 改进现有 Skill
• 写使用心得分享到 CSDN/掘金/知乎

推荐资源:

• 官方文档:https://github.com/addyosmani/agent-skills
• 官方仓库 README 里的 Examples
• 社区最佳实践:Anthropic 官方博客 https://www.anthropic.com/blog
• 国内社区:CSDN AI 板块、掘金 AI 板块

避免的坑:

• 不要装太多 Skill(超过 10 个会拖慢 Agent)
• 不要把 Skill 装在不兼容的 Agent 上
• 不要直接复制 Skill 默认 prompt——要根据项目调整
• 定期 review Skill 库的实用性,清理不用的

参考链接

• 仓库:https://github.com/addyosmani/agent-skills
• Conventional Commits 规范:https://www.conventionalcommits.org/
• Trunk-based Development:https://trunkbaseddevelopment.com/
• Semantic Versioning:https://semver.org/
• release-please 自动化发布:https://github.com/googleapis/release-please
• 经典书《Team Topologies》(Google 工程组织):https://teamtopologies.com/book

我的个人推荐(测试编辑 Mnet)

最常用的 1 个核心用法:每天打开 Agent 第一时间加载这个 Skill,既不消耗太多 token 也能规范输出。

最容易踩的坑:别把 Skill 提示词当”开箱即用”的最终答案——它只是给你一个”标准框架”,具体项目还得你自己调整。

适合人群:做过 3+ 个实际项目的开发者,而不是”看一遍文档就完事”的小白。

3 个月使用心得:刚开始用时觉得”规范是约束”,用了 3 个月后才发现”规范是省时间”——避免每次重新决策同样的细节。

推荐配合的工具:Claude Code / Cursor / OpenCode 任选一个主流 Agent 即可,不要在工具选择上纠结太久。

长期价值:这类 Skill 的核心价值不是”立竿见影的输出”,而是”持续一致的质量”——长期用下来,你的项目质量会稳定在专业水平。

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。