1820 字 7 分钟阅读
Agentic Coding 标准 Worktree 流程
vibe coding 标准 Worktree 流程
此文档介绍了在 vibe coding 标准下,如何使用 Git Worktree 进行多分支开发和管理的流程,可写入到 AGENTS.md 作为操作规范的参考。
1. 授权与安全
提交、合并、推送和部署须有用户授权。
2. 项目上下文与工作区
工作区遵循以下原则:
- 优先级上遵循:
AGENTS.md>项目/docs参考文档 > 本文件,如有矛盾或冲突,请求用户明确指示。
仓库的工作模式遵循 Git WorkTree 模式,即:
- 普通开发默认使用
linked worktree模式,除非AGENTS.md或用户明确授权例外。 - 开始前确认默认分支、当前分支及 staged、unstaged、untracked 状态,保留无关修改。
- 工作区保持默认分支,不直接开发。从本地默认分支已提交的 HEAD 创建唯一的
work/<slug>和.worktrees/<slug>,项目命名约定优先。 - 创建前检查已有分支、Worktree 和路径,冲突则换唯一名称,不接管或重置其他任务。记录任务、绝对路径、分支及开发基线 SHA。
- 独立任务从默认分支起步;依赖未合并任务时记录上游与依赖基线,按依赖分支流程整合。
- 不默认复制或共享
.env、本地配置、数据及用户未提交内容,采用 link 方式引用让分支可用。
3. 计划与执行
执行前确保工作区和分支符合要求。三个以上独立步骤或跨模块任务使用任务清单告知用户,形成明确的 TODO 列表。
Plan
讨论、调查与正式规划的边界遵循共同规则,Plan 要遵循以下规则:
- 与用户充分讨论,明确需求直到你认为已经了解需要实现的每一个细节,沟通过程保持高效,减少对话轮次和避免信息密度低,减少对用户的精神消耗。
- 独立设计 plan 并在完成后,过一遍原始讨论来审核 plan,确保 plan 简洁、清晰且可执行,规模小,易于验证和调整。
- plan 绝对禁止:为未来可能扩展性抽象、平台化、过度设计。
- 向用户展示 plan,减少 plan 里的黑话、无关展开,确保 plan 内容是简洁清晰不遗漏细节。
4. 开发验证
验证遵循以下规则:
- 运行适用的格式化、lint、静态/类型检查、聚焦及全量测试和构建。
- 检查最终 diff 和 Git 状态,重点核对接口兼容、错误处理及多余抽象。
5. 合并、推送与清理
明确获准合并后执行完整流程,无需逐步确认。任一步有未解决冲突、验证失败、主线变化或 Git 状态不明,暂停推进、清理并保留现场报告。禁止 reset、强制移动主分支、覆盖主工作区或复制功能工作树伪造整合结果。
仓库级互斥
默认分支更新、整合、推进和清理必须串行;其他独立 Worktree 可继续开发,但不在主工作区或其他任务 Worktree 临时整合。遵循项目合并队列/互斥约定;否则在 git rev-parse --git-common-dir 的共享目录原子创建 agent-integrate.lock,记录任务、会话和开始时间。所有会话用同一把锁,不在各 Worktree 分别加锁;git worktree lock 不是整合互斥。取得锁才更新默认分支,持有至整合、检查及获准清理结束;占用时报告持有信息,不争抢、不因超时删锁,疑似遗留须核实持有者已结束,无法确认则询问。仅释放本会话持有的锁;异常保留可辨认现场。锁不能约束其他克隆或人工操作,仍须核对实际 SHA。
冻结与整合
-
冻结源内容。 确认任务、源分支/Worktree、开发基线与全部 Git 状态;代码、测试、文档须已提交。有遗漏仅在授权内提交本任务内容,否则报告阻塞;无关改动留原处并排除清理。停止本任务写入,确认执行者已结束,记录
source_sha。 -
更新基线。 主工作区须在默认分支,且无 staged、unstaged、untracked 改动;有 upstream 则先 fetch,仅 fast-forward 更新,不改写历史。更新及最终快进前均检查待写路径与 ignored 文件/目录是否碰撞,只查名称和用途,不读凭证;需保留或不明则停止,不搬走或覆盖。快进使用
--no-overwrite-ignore,干净状态不能替代此保护。 -
隔离整合。 记录更新后的
base_sha,从它创建唯一的integrate/<slug>和.worktrees/integrate-<slug>。仅在此 Worktree squash 冻结的source_sha,不使用可变源分支名或复制未提交文件。名称冲突不覆盖。 -
处理冲突。 调查双方意图,仅在整合 Worktree 解决;不整体选 ours/theirs 或用旧文件覆盖主线。不确定则询问,解决后重新审查并完整验证。
-
审查与验证。 相对
base_sha审查最终差异,只包含本任务及必要文档;对照开发基线至base_sha的变化,核对共享接口、调用链和业务约束,保留后来进入主线的功能,而非追求与旧功能树一致。在整合 Worktree 完整验证“最新主线 + 本任务”,包括受影响既有功能回归;无文本冲突不代表无语义冲突。 -
生成交付提交。 验证通过后创建符合仓库风格的一个提交,记录
integrated_sha,确认其父为base_sha、恰好领先一提交。复核源分支仍为source_sha、源工作区无新增改动、整合工作区干净;源内容变化则暂停,重新冻结和验证。 -
推进主线。 持锁回主工作区,复核默认分支、干净状态、HEAD 为
base_sha、整合分支为integrated_sha,完成碰撞复查后仅执行:git merge --ff-only --no-overwrite-ignore integrate/<slug> -
合并后检查。 确认 HEAD 为
integrated_sha,检查状态并运行必要验证。基线变化或无法快进则不强制,基于新主线重新整合和验证;SHA 与历史关系不能代替内容和行为检查。
依赖分支
main → A → B 按依赖顺序交付。A 被 squash 后,不能仅凭祖先关系或提交数认定 B 全是新增内容。记录 A 的源 SHA 和整合提交,对照 B 的依赖基线识别已交付与 B 独有变化,在独立整合 Worktree 验证组合结果。仅在无歧义时选择性重放 B 的提交,不自动改写仍被使用的 A/B 分支;混合提交、交叉修改或依赖不明时报告并制定专项方案,不强行 squash 后清理。
Push
仅明确获准才 push。推送前确认代码、测试和必要文档完整入提交,无任务遗漏,默认分支状态正确;推送后检查远程结果。
6. 最终汇报
开发交付另说明主要文件、分支/Worktree/Git 状态和 commit/merge/push 状态。涉及整合另记 source_sha、base_sha、integrated_sha 和保留/清理对象。