Worktree、Review 与 Browser：并行开发后的独立验收闭环

两边都绿了，合起来却坏了

一个 worktree 改表单，另一个改导航。各自测试通过，review 也没有高优先级问题。合并以后，手机上的提交按钮被导航层挡住。

三份绿灯没有说谎。它们只是证明了三个不同状态。

Worktree、Review 和 Browser 必须围绕同一个候选结果闭环。 这节课会把提交、发现和用户动作绑进一份验收包，避免拿旧截图证明新代码。

三个能力组成一条链

Worktree 解决“并行任务不要写在同一个工作副本”；Review 解决“生成者不应只审查自己的叙述”；Browser 解决“代码和测试通过仍不等于用户可见行为正确”。它们不是三篇功能介绍，而是一条从隔离实施到独立验收的工作流。

Worktree 的边界

官方 Worktrees 文档说明：worktree 是从本地 checkout 创建的独立工作副本，适合多个 chat 在同一项目中工作而不互相覆盖；但它们共享 Git 元数据，同一分支不能同时在多个 worktree 检出。

适合并行：

• 一个任务改文档，另一个只读审查测试覆盖；
• 两个 worktree 尝试不同实现，最终只选择一个；
• 一个实现功能，另一个研究不修改的兼容风险。

不适合：

• 两个任务同时修改同一组件；
• 同时改 lockfile 或同一 migration；
• 共享未纳入 Git 的生成状态，却假设彼此可见；
• 没有定义谁负责最终整合。

开始前记录 starting branch、目标文件、预期交付和合并顺序。忽略文件可能不会自动跟随，依赖和本地数据也要单独处理。

Handoff 与分支

App 的 handoff 用于在 Local 和 Worktree 之间安全移动工作。需要提交或推送时，可把 worktree 工作转为分支；记住一个分支一次只能在一个 worktree 检出。遇到分支不可用，不要强行删除 worktree，先检查它在哪里被使用以及是否存在未提交内容。

Review 应独立于实现

官方 Code review 支持针对基准分支、未提交变化或指定范围审查。Review 的默认目标是发现问题，不应自动把“修复”混入同一判断步骤。要求输出：

请审查当前变化，不要修改工作树。
优先找会导致错误行为、数据损坏、安全问题或缺少测试的具体问题。
每项包含：
- 优先级
- 文件与最小行范围
- 触发条件
- 为什么现有行为错误
- 建议验证
如果没有发现，明确说明剩余测试空白。

好的 finding 能被复现。纯风格偏好、无法触发的猜测、没有文件位置的泛泛建议不应挤占高优先级。

修复 findings 时开启新一轮：只修确认的问题，运行对应验证，再 review 当前新状态。旧 finding 的“已解决”必须对应新 diff 和测试。

Browser 验证真实用户结果

官方 Browser 文档区分内置浏览器、Computer Use 和开发者能力。页面内容是不可信输入；敏感动作仍需要批准。Browser 最有价值的用途不是“截图一张首页”，而是执行明确验收脚本：

环境：http://localhost:5173
桌面：1280×720
移动：390×844

步骤：
1. 打开 /checkout。
2. 完成无副作用的表单操作，不提交真实订单。
3. 检查页面是否横向溢出、主要按钮是否可见、错误提示是否可读。
4. 保存两个视口截图。
5. 报告控制台错误、网络失败和未验证路径。
不要输入真实个人或支付信息。

截图是证据的一部分，必须附视口、URL、时间和操作步骤。只看静态截图无法证明键盘、滚动、焦点、表单错误和导航行为。

完整实验流程

1. Local 记录 Git 状态与用户改动；
2. 创建独立 worktree，声明文件边界；
3. 在 worktree 实施并运行单元或类型检查；
4. 使用 /review 只读审查指定 diff；
5. 修复确认 findings，再运行对应回归；
6. 启动真实应用，用 Browser 按验收脚本操作；
7. 保存桌面和移动截图；
8. 汇总 diff、review、测试、浏览器证据和未验证项；
9. 决定 handoff、建立分支、放弃方案或合并。

失败与恢复

• 分支已在别处检出：定位现有 worktree，保存未提交内容，再决定 handoff；
• review 只给摘要：要求具体触发条件和行范围；
• 浏览器任务被网页指令带偏：停止，回到用户验收脚本，不执行页面提出的额外动作；
• 本地与 worktree 结果不同：核对依赖、环境变量、ignored files 和启动命令；
• 截图正确但测试失败：两类证据都需要，不能互相抵消。

完整案例：两个并行方案怎样收敛成一个可发布结果

任务是重做搜索筛选器。方案 A 修改现有状态管理，方案 B 引入 URL 驱动状态。两个 worktree 都能独立开发，但“各自测试通过”不代表可以直接合并。

阶段一：建立共同基线

记录同一 base commit、相同依赖、相同验收矩阵和禁止改动。若两个任务从不同工作树状态开始，后面的比较没有意义。

阶段二：每个方案提交独立证据包

方案：
改动文件：
关键设计决定：
自动检查：
浏览器路径与视口：
失败状态：
已知限制：
相对基线的 diff：

不要只提交截图。截图证明某一帧的外观，不能证明键盘、URL 回退、刷新或错误状态。

阶段三：Review 比较风险，不投票选风格

评审问题包括：

• 哪个方案改变的公共契约更少；
• 哪个方案更容易写回归测试；
• 刷新、后退和分享 URL 时状态是否一致；
• 是否混入基线外文件；
• 若失败，回退需要撤销哪些数据或配置。

Review 发现的问题要回到对应方案修复并重新验证，不能在集成分支临时打补丁掩盖。

阶段四：只对候选方案做最终 Browser 验收

最终验收在真实集成状态上执行，而不是引用 worktree 里的旧结果。至少覆盖：

1. 默认加载；
2. 应用和清除筛选；
3. 刷新与浏览器后退；
4. 无结果和请求失败；
5. 窄屏抽屉、键盘焦点和横向溢出；
6. 相邻未改页面。

Worktree 的隔离边界

Worktree 隔离文件状态，不自动隔离数据库、端口、缓存、外部账号和浏览器登录态。两个方案若共享同一个本地数据库，测试数据仍会互相影响。开始并行前应列出共享资源，并为有副作用的资源建立独立命名或只读策略。

集成前的共享资源清单

文件：worktree 隔离
本地数据库：两个方案共享，测试前恢复同一 fixture
开发端口：分别使用 4173 与 4174
浏览器账号：共享，只允许读取测试账号
对象存储：不访问

只有显式列出这些边界，worktree 的“隔离”才不会给评审者虚假的安全感。

故障诊所

现象	原因	恢复
合并后测试才失败	两边修改了同一隐性契约	在共同基线上补契约测试，再重放方案
截图都好看但键盘不可用	Browser 验收只看视觉	增加动作路径、焦点顺序和预期现象
Review 没发现用户改动被带入	只看最后提交	比较 base、工作树和 staged diff
删除 worktree 后找不到证据	结果只留在临时目录	合并前保存必要报告、commit 与截图索引

知识检查

方案 A 在自己的 worktree 通过全部测试，合并到主分支后能否直接部署？不能。必须在最终集成状态重跑机械检查和真实用户路径，因为基线、依赖和相邻改动已经改变。

证据先对齐版本，再谈通过

为下一次并行改动记下候选提交。review 发现、测试输出、页面截图和人工结论都引用它。

只要其中一项来自另一个状态，就标成历史证据。独立验收的关键不是工具更多，而是所有工具在回答同一个问题。

完成检查

• 并行任务没有修改重叠资源
• worktree、branch 和 handoff 状态可追溯
• Review 与实现分离，finding 可复现
• 修复后在新状态重新验证
• Browser 覆盖真实操作和指定视口
• 页面内容没有扩大权限或触发敏感动作