dev-git-workflow

Git 工作流

使用此技能选择团队 Git 模型、设置合并和审查策略，并为人类与 AI 辅助协作定义安全默认值。本文假定读者了解 Git 命令；重点在于提供决策依据。

默认倾向：采用 GitHub Flow 或主干开发；每个仓库只使用一种合并方式；当 PR 经常在合并前变得过时时，启用合并队列；每个 Agent 使用一个工作树；仅在版本支持要求时使用发布分支。托管平台功能（堆叠式 PR、合并队列选项、规则集字段）和 Git 本身每年都会多次变化：在推荐受版本限制的 Git 功能之前，请查看 git-scm.com 上的发行说明；在推荐平台功能之前，请查看相应平台的文档，确认用户所用套餐是否提供该功能。

快速参考

需求	默认方案	参考
选择分支模型	GitHub Flow；合并并发量较高时，采用主干开发并搭配合并队列	references/branching-strategies.md
选择合并方式	小型 PR 流程采用 squash；发布分支采用合并提交	合并方式、references/pr-best-practices.md
并发工作时确保 main 保持绿色	合并队列或合并列车	合并队列、references/automated-quality-gates.md
快速合并存在依赖关系的变更	堆叠式 PR	references/stacked-diffs-guide.md
并行开展 Agent 或功能开发	每个 Agent 使用一个工作树和一个分支	references/ai-agent-worktrees.md
发布和热修复	优先向上游提交修复，从 main 创建标签	references/release-management.md
提交消息和变更日志	由 dev-git-commit-message 负责	dev-git-commit-message、references/commit-conventions.md
调试错误合并或回归	冲突处理规范、二分查找	references/conflict-resolution.md、references/git-bisect-debugging.md

转至其他技能：审查特定变更集 → software-code-review；超出合并门禁范围的 CI/CD 平台设计 → ops-devops-platform；提交消息格式、尾注和变更日志工具 → dev-git-commit-message。

工作流

1. 明确约束：同时处于开放状态的分支数（而非团队人数）、发布节奏和受支持版本数量、CI 时长和默认分支失败率、贡献者模式（共享推送还是 fork）、合规或审计要求。
2. 选择符合需求的最简单分支模型（见下表）。
3. 设置仓库基线：规则集、审批、必需检查、唯一的合并方式、CODEOWNERS、发布和标签规则。
4. 定义人类和 Agent 的本地工作循环，包括安全预检。
5. 根据参考资料和模板实施，而不是临时制定仓库策略。

分支策略选择

情况	默认策略
单条生产线、频繁部署	GitHub Flow
合并并发量高、CI 快速且稳定、main 必须保持绿色	主干开发加合并队列
未完成的工作必须尽早合并	主干开发加功能标志
仅支持一个版本并按计划发布	GitHub Flow 或带发布标签的主干开发
支持多个版本或需要长期稳定期	从 main 切出发布分支（仅当单独的集成分支有实际价值时才使用 GitFlow）

主干开发需要响应迅速的 CI（大约少于 10 分钟），且默认分支很少显示红色（大约少于 5% 的构建失败）；应将两者视为需要根据本地情况校准的经验参考，而非标准。

团队人数是合并并发量的替代指标，而非真正的影响因素：

• 以 Agent 为主的团队。 五名成员同时运行十个并行 Agent 工作树，其合并并发量相当于规模大得多的团队。应根据同时处于打开状态的分支数量确定工作模式和是否使用合并队列。
• 采用 Fork 的开源项目。 主干开发假定参与者拥有推送权限。对于通过 Fork 和 PR 贡献的项目，应使用 GitHub Flow，并只将核心维护者计为“团队”成员。
• 受监管或需审计的工作。 签名提交、强制独立审批和不可篡改的记录往往是决定性约束。四人的受监管团队可能需要比四十人的 SaaS 团队更严格的规则集。
• 分布式、异步团队。 不能假定当天就能完成审查。应优先使用草稿 PR、在必需检查通过后自动合并，以及堆叠 PR，而不是严格限制分支存续时间。

合并方式

每个仓库选用一种方式，并在规则集的允许合并方式中强制执行。混用方式会导致 git log、bisect 和 revert 在不同 PR 中表现不一致。

方式	适用情况	代价
Squash	PR 较小；PR 内的提交不具备独立意义	每个 PR 成为一个可还原的单元，但中间历史会丢失；PR 标题会成为提交主题，因此应规范 PR 标题；对堆叠中的基分支执行 squash 会使后续分支中的对应提交副本变成孤儿
Rebase-merge	作者会整理提交，且每个提交都能构建并通过测试	历史线性且便于二分定位，但合并后的 SHA 与 CI 和审查者看到的 SHA 不同；将其与强制签名提交结合前，请查阅代码托管平台文档，了解 rebase-merge 如何处理提交签名
Merge commit	发布分支、回合并、长期存续的集成分支，或必须保留确切受测 SHA 的情况	历史更杂乱；在 log 和 bisect 中使用 --first-parent

无论仓库采用哪种 PR 合并方式，发布分支的回合并和向前移植都应使用合并提交或 cherry-pick -x。

合并队列

当 PR 通常需要多轮“更新分支”才能合并，或 main 因单独通过检查的 PR 之间存在语义冲突而被破坏时，应采用合并队列（GitHub）或合并列车（GitLab）。低于这一程度时，“要求分支保持最新”加自动合并更简单。

• 吞吐量上限 ≈ 构建并发数 × 平均组大小 ÷ CI 时长。若 CI 耗时 25 分钟且每次构建处理一个 PR，串行队列每小时可合并约 2.4 个 PR；如果团队提交 PR 的速度超过此上限，应先提高并发数或组大小，或缩短 CI 时长。
• 更大的组可以减少 CI 运行次数，但一次失败就会使整个组失效并迫使重新测试；不稳定的测试是吞吐量的主要杀手，因此应在启用队列前修复或隔离这些测试。
• 每项必需检查都必须在队列事件上运行（GitHub Actions 中为 merge_group；第三方 CI 中为队列的临时分支）。带路径筛选条件、且从不针对队列条目运行的必需工作流会阻塞队列。
• 必需检查按名称匹配：重命名 CI 作业会导致旧的必需检查永远处于待处理状态。

受保护的分支和规则集

• 如果托管平台支持规则集，请使用规则集：多个规则集可以叠加应用于同一分支，也可以在组织范围内定义。下次调整策略时，迁移经典分支保护规则。
• 要求向受保护分支提交 PR，由作者以外的人审批，新推送时撤销过期审批，对敏感路径要求 CODEOWNERS 审核，并要求通过状态检查。
• 禁止对 main、发布分支和发布标签执行强制推送和删除操作。保持绕过名单简短、明确，并进行审计；紧急绕过后仍须执行合并后 CI 和审核。
• 在支持的情况下，启用带推送保护的机密扫描。
• 同一账户上的两个 Agent 不等于两位审核者。对于个人账户仓库，明确记录允许的合并路径（第二个审核者账户、关闭必需审批并进行人工审核，或有意使用管理员绕过）。

发布和热修复流程

• 从 main（或发布该版本的发布分支）创建发布标签。保护发布标签。
• **先合并到上游：**先将修复合并到 main，再将其 cherry-pick -x 到每个受支持的发布分支。仅应用到发布分支的修复会在下个版本中再次成为回归问题。
• 如果 main 已经严重分歧，无法先在那里合并修复，就在发布分支上修复，并立即创建一个有跟踪记录的前向移植 PR。
• GitHub Flow 下的热修复：从 main 创建分支，快速审核，运行完整 CI。如果 main 中包含无法发布的未发布工作，则改为从发布标签创建分支。
• 版本方案、发布触发条件和回滚说明见 references/release-management.md。

本地安全预检

在检出、合并、变基、修订提交、重置或推送之前：

1. 使用 git status --porcelain 检查工作树是否有未提交更改。明确决定：提交、更换到专属工作树，或停止。绝不要在其他 Agent 也共用的工作树中执行 git stash：它会收集所有 Agent 的未提交更改，而且所有工作树共用 refs/stash。
2. 如果存在 .git/index.lock，先确认没有 Git 进程正在运行，再将其移除。
3. 遇到冲突时，停止新编辑，逐个文件解决冲突，重新运行相关测试，然后继续。
4. 在由 Agent 驱动的工作中，只暂存预期文件。
5. 在多仓库或长期运行的 Shell 中，不要依赖 Shell 的 cwd：对变更操作使用 git -C <path>，并先通过 git -C <path> rev-parse --show-toplevel 和 branch --show-current 验证目标。如果变更操作影响了错误的仓库或分支，请停止并检查，再进行任何恢复操作。

历史重写风险判断

风险取决于还有谁依赖该引用，而非使用的命令：

• **默认安全：**只有你或一个 Agent 推送过该分支，且尚未创建 PR。
• **先检查：**该分支有一个包含审核或审批的开放 PR。强制推送（即使使用 --force-with-lease）在大多数配置中也会撤销审批，重新审核的成本往往高于清理历史所带来的收益。检查审核状态（gh pr view --json reviews,reviewDecision）；如果已有审批，就添加提交，而不是重写历史。如果无法避免重写，请向审核者提供 git range-diff 输出。
• 未经明确告知的例外，绝不操作：main、develop、发布分支、发布标签，或其他人或 Agent 正在基于其开展工作的任何分支。
• **历史中包含机密：**先轮换凭证，以此消除暴露风险。只有在仍有必要时才重写历史，并使用 git filter-repo（Git 官方文档已不建议使用 filter-branch）。克隆仓库、分叉仓库和托管平台端的 PR 引用仍会保留旧对象，因此凭证轮换绝非可选操作。
• **Agent 故障模式：**Agent 在“清理”历史时，可能会破坏自上次获取以来由人类推送的内容。要求使用 --force-with-lease，并以 Agent 记录的远程分支最新提交为基准；如果租约被拒绝，就必须停止：获取更新、检查情况并请人介入。绝不要改用裸 --force 重试。

经授权的历史重写交接记录中，应注明旧的最新提交、新的最新提交、分支、受影响的依赖分支或 PR，以及协作者用于重新对齐的命令。

Agent 编写的工作

• 保持 Agent 提交可区分。只有专用机器人作者身份会影响 git log --author 和 blame；Co-authored-by: 或 Assisted-by: 尾注不会。是否添加 AI 尾注以及添加哪一种，应遵循仓库政策和 dev-git-commit-message。未经本人知情，绝不要以他人的身份提交。
• 仓库要求提交签名时，务必为 Agent 提交签名；Agent 身份并非例外。
• Agent 对其更改的总结不等于审查；在仓库实际检查流程运行前，“测试通过”也未经验证。要求人工审查合入 main 的 Agent PR；AI 审查者可以发表评论，但不算批准者。唯一允许由 Agent 合并的路径是下一条规则中的 dev 合并。
• 绝不要让 Agent 批准自己的 PR。只有在用户于此任务中要求合并，且 adversarial-review 工作流对最终 PR 差异返回 CLEAN 时，Agent 才能合并 PR；绝不能合入 main，并且必须固定已审查的提交：gh pr merge <n> -R <owner/repo> --match-head-commit <head_sha>。
• 一个 Agent、一个工作树、一个分支。多个 Agent 共用工作树，会导致提交悄无声息地覆盖彼此的意图。

规则：每次编码会话都会加载 rules/common/git.md 中的这一不变量。

以工作树为先的循环与仓库本地约定

1. 为每项功能或每个 Agent 创建一个工作树（确认其目录已被忽略）。
2. 编辑前，在该工作树中验证依赖项并运行基线测试。
3. 将编辑限制在分配的文件内。
4. 打开 PR 前，从工作树运行仓库检查流程。
5. 按照仓库政策合并；合并后移除工作树并删除分支。

如果用户希望在真实仓库中采用这一流程，应将其规范为仓库本地脚本（start <slug>、gate、pr、finish <slug>），在 AGENTS.md 中记录准确命令以及审查／合并政策；对于多仓库功能，应在每个仓库使用相同的 slug，并为每个仓库创建一个 PR，先合并拥有约定的仓库。完整约定、多仓库会话命令、环境变量覆盖模式及验证步骤： references/ai-agent-worktrees.md。

失败模式

• 根据理念而不是发布支持负担、合并并发量和 CI 能力选择分支模型。
• 没有发布原因却长期保留分支；dev／staging／prod 等环境分支彼此偏离，而不是逐步发布同一构建产物。
• 在必需检查不稳定、按路径筛选或耗时的情况下启用合并队列；队列会放大这三类问题。
• 在没有约定政策的情况下，于审查期间变基或强制推送，导致审查者上下文和批准状态丢失。
• 将依赖顺序不明确的更改堆叠在一起；独立更改应放在并行 PR 中。
• 使用工作树和堆叠更改，却没有仓库本地脚本，导致清理和验证方式不一致；自动化则假设同级目录路径固定。
• 为了“更快合并”而跳过 CI 或审查；绕过流程最终会成为常态。

导航

• references/branching-strategies.md：模型选择、各模型的热修复路径、迁移
• references/pr-best-practices.md：PR 大小、描述规范、评审礼仪、合并方式详情
• references/stacked-diffs-guide.md：何时使用堆叠式差异、工具选择、压缩合并后的恢复、合并顺序
• references/automated-quality-gates.md：必需检查、合并队列和合并列车设置、紧急绕过
• references/release-management.md：版本方案、发布触发条件、热修复、回滚
• references/ai-agent-worktrees.md：工作树设置、并行 Agent、清理、仓库本地交付规范
• references/interactive-rebase-guide.md：自动压缩、--update-refs、range-diff、恢复
• references/conflict-resolution.md：预防、解决陷阱、rerere、撤销合并
• references/git-bisect-debugging.md：自动二分查找、退出代码、第一父提交
• references/git-hooks-automation.md：钩子管理器、推送前的精确顶端提交检查、绕过策略
• references/monorepo-workflows.md：部分克隆、稀疏检出、CODEOWNERS、仅针对受影响内容运行 CI
• references/validation-checklists.md：PR 前、合并前、热修复、变基、堆叠、发布检查清单
• references/common-mistakes.md：错误与修复索引
• references/commit-conventions.md：指向 dev-git-commit-message 的链接，以及原子提交和模板
• 资源：PR 模板、工作流指南模板、发布工作流模板、GitHub 检查、GitLab 检查
• data/sources.json

相关技能：software-code-review、qa-debugging、ops-devops-platform、qa-testing-strategy、docs-codebase、dev-git-commit-message、ai-coding-agents。

查询

• 在介绍平台功能状态（堆叠式 PR、合并队列设置、规则集选项）之前，请先查阅平台官方文档和变更日志进行核实；优先采用这些资料和 git-scm.com，而非博客。
• 在用户所安装版本的发行说明中核实 Git 功能是否可用；将实验性命令标记为实验性。

经验反馈循环

当以往的决策或陷阱与当前情况相关时，如果存在 learnings.consolidated.md，请查阅该文件；仅在需要了解历史记录或将其作为可用的备选资料时，才查阅 learnings.md。否则跳过这两个文件。

应用后，如果你遇到了值得记住的模式、值得避免的错误，或令你惊讶的领域事实，请通过 agents-skills-feedback-loop/scripts/append_learning.py 向 learnings.md 追加一条带日期的项目。不要修改 SKILL.md 本身。