用途
Git 工作流与版本管理技能用于指导任何代码改动过程中的版本控制实践，包括提交、分支、解决冲突，以及把混乱工作区中未提交的改动拆分为干净的原子提交。其定位是：Git 是安全网，提交是存档点，分支是沙盒，历史是文档。在 AI 代理高速生成代码的场景下，纪律化的版本控制是让改动保持可管理、可审查、可回滚的机制。技能声明：每次代码改动都应经过 git。
主要能力
核心原则
- 主干开发（推荐）：保持 main 始终可部署，在 1-3 天内合并回主干的短生命周期特性分支中工作。长期开发分支是隐性成本，会分叉、产生合并冲突并延迟集成。DORA 研究持续表明主干开发与高绩效工程团队相关。发布分支在需要稳定发布而 main 继续前进时可以接受。特性开关优于长期分支：不完整的工作应放在开关后面部署，而不是留在分支上数周。
- 尽早提交、频繁提交：每个成功增量单独提交，不要累积大量未提交改动。工作模式为“实现切片 → 测试 → 验证 → 提交 → 下一个切片”，而非“实现全部 → 期望能跑 → 巨型提交”。
- 原子提交：每个提交只做一件逻辑上的事。技能给出正例（分别添加端点、表单组件、连接 API、测试）与反例（把特性、侧边栏修复、依赖更新、工具重构混在一起）。
- 描述性提交信息：解释“为什么”而非仅“是什么”。格式为
<type>: <short description>，可选正文解释原因。类型包括 feat（新功能）、fix（缺陷修复）、refactor（既不修缺陷也不加功能的代码改动）、test（新增或更新测试）、docs（仅文档）、chore（工具、依赖、配置）。 - 关注点分离：不要把格式化改动与行为改动混在一起，不要把重构与功能混在一起；每类改动应单独提交，理想情况下单独 PR。
- 控制改动规模：目标约 100 行/提交或 PR；约 300 行对单一逻辑改动可接受；超过约 1000 行应拆分。
分支策略
- 特性分支从 main（或团队默认分支）拉出，每个分支一个特性，保持短生命周期（1-3 天内合并），合并后删除分支。
- 分支命名：
feature/<short-description>、fix/<short-description>、chore/<short-description>、refactor/<short-description>。 - Worktree：为并行 AI 代理工作使用 git worktree 同时运行多个分支，例如
git worktree add ../project-feature-a feature/task-creation，完成后git worktree remove ../project-feature-a。好处包括多个代理可同时处理不同特性、无需切换分支、实验失败可直接删除 worktree、改动在显式合并前保持隔离。
存档点模式
代理开始工作后，每次改动若测试通过则提交并继续，若测试失败则回退到上次提交并调查；特性完成后所有提交形成干净历史。该模式意味着最多只丢失一个增量的工作，代理失控时可用 git reset --hard HEAD 回到上次成功状态。
变更摘要
任何修改后提供结构化摘要，包含三部分：CHANGES MADE（改了什么）、THINGS I DIDN'T TOUCH (intentionally)（有意未触碰的内容）、POTENTIAL CONCERNS（潜在问题）。
提交前卫生检查
每次提交前：git diff --staged 检查将要提交的内容；用 grep 检查是否含 password、secret、api_key、token 等密钥；运行 npm test、npm run lint、npx tsc --noEmit。
生成文件处理
仅当项目期望时才提交生成文件（如 package-lock.json、Prisma 迁移）；不要提交构建输出（dist/、.next/）、环境文件（.env）或 IDE 配置（除非共享的 .vscode/settings.json）。.gitignore 应覆盖 node_modules/、dist/、.env、.env.local、*.pem。
用 Git 调试
使用 git bisect 定位引入缺陷的提交；用 git log --oneline -20、git diff HEAD~5..HEAD -- src/ 查看近期改动；用 git log --grep="validation" --oneline 搜索提交信息。
发布与版本管理
- 语义化版本：MAJOR.MINOR.PATCH。MAJOR 为破坏性变更（使用者必须改代码才能升级），MINOR 为向后兼容的新功能，PATCH 为向后兼容的缺陷修复。不确定是否为破坏性变更时，假定是。
- 打标签：发布是不可变的历史点，不是移动的分支。使用
git tag -a v1.4.0 -m "Release 1.4.0"和git push origin v1.4.0，版本号应从标签派生而非手工编辑散落文件。 - 面向人类的变更日志：变更日志不是 git log，而是按 Added / Changed / Fixed / Deprecated / Removed / Security 分组、最新在上、每条围绕用户影响表述的精选内容。应在做出改动的同一次变更中写入条目。
适用场景
适用于任何代码改动流程，尤其是 AI 代理高速生成代码、需要并行处理多个特性、需要把混乱工作区拆分为原子提交、需要可回滚的存档点、以及有下游使用者的发布与版本管理场景。
限制与注意事项
技能列出常见合理化借口及其现实反驳，例如“功能完成再提交”“信息不重要”“以后再 squash”“分支是额外开销”“以后再拆分”“不需要 .gitignore”“小修复就升 patch”“变更日志就是提交日志”“发布时再写变更日志”。同时列出红旗信号：大量未提交改动累积、提交信息如 fix/update/misc、格式化与行为改动混合、项目无 .gitignore、提交 node_modules/.env/构建产物、长期分支严重分叉、对共享分支强推、破坏性变更以 minor 或 patch 发布、发布无标签或版本号与标签不同步、面向用户的发布无变更日志条目。验证清单覆盖每次提交与每次发布。