结对编程辅助

角色分工

驾驶员（Driver）拥有编辑焦点：输入代码、运行命令、触发测试。职责是保持小步前进，并在每个可验证点停下来。导航员（Navigator）不抢键盘（除非轮换），持续对照团队约定：可读性、错误处理、与周边模块的耦合方式。

Driver 负责（持有键盘）：
  ✓ 打开编辑器，输入具体代码
  ✓ 运行测试命令：npm test / pytest / go test ./...
  ✓ 执行 git add / commit（按导航员确认后）
  ✓ 保持每步 ≤ 10 行改动，每步可通过测试或失败明确
  ✗ 不做架构决策，不跳过测试验证步骤

Navigator 负责（不持有键盘）：
  ✓ 大声检查命名是否与仓库约定一致
  ✓ 标出遗漏的错误处理分支与边界情况
  ✓ 对照已有模块检查耦合方向是否合理
  ✓ 记录分歧点（见下方分歧决策规则）
  ✓ 在交换前用一句话总结：「接下来要做 X，风险是 Y」
  ✗ 不在驾驶员打字时并行重写代码

每 25 分钟强制交换（Pomodoro 变体）：
  [0-25 min] Driver 实现 → Navigator 导航
  [25 min]   5 分钟切换：交接上下文 + 提交当前增量
  [30-32 min] 2 分钟复盘：本轮完成了什么、下轮目标是什么
  [32-57 min] 新 Driver 接手（原 Navigator 变 Driver）

轮换节奏

每完成一个可运行增量（绿测、或明确失败的单测）、或每修好一个与本轮目标直接相关的失败用例后，考虑交换角色，减轻疲劳与认知偏差。紧急 hotfix 可压缩为「你写我审」的短回合，但仍要口头过一遍变更面与回滚点。

  [ 对齐本轮目标 + 验收标准 ]
                    │
                    ▼
            ┌───────────────┐
            │    DRIVER     │  敲键盘、跑测、小步提交
            └───────┬───────┘
                    │
                    ▼
            ┌───────────────┐
            │   NAVIGATOR   │  命名 / 边界 / 与现有模式一致
            └───────┬───────┘
                    │
                    ▼
            [ 本轮可运行增量完成? ]
                    │
         ┌──────────┴──────────┐
         │ no                  │ yes
         ▼                     ▼
  [ 继续：缩小范围或补信息 ]   [ 轮换角色 或 记录决策 ]

• 轮换前用一句话交接：「接下来文件 X 里要实现 Y，已知风险是 Z。」
• 长时间会话建议设墙上时钟提醒，避免两人同时陷入实现细节。

Agent 作导航员

Agent 适合承担导航员角色时：主动要求展示调用栈、相关文件片段或测试输出，避免在信息不足时大段改写。人类驾驶员应定期口述当前假设（「我认为这里会先走缓存」），便于模型纠正方向而非附和幻觉。

下面是一段真实的 Driver（人类）+ Agent（导航员）协作会话记录：

Driver：「我要给 checkout API 加一个优惠码校验，现在在写 validateCoupon 函数」

Agent（导航员）：「好，我看到你要调用 coupon.findOne()，在写之前：
  1. findOne 返回 null 时你打算怎么处理？
  2. 同一个用户同一订单用两次同一优惠码的情况考虑了吗？」

Driver：「第一个我返回 { valid: false, reason: 'NOT_FOUND' }，
       第二个还没考虑，先跳过吧」

Agent：「跳过可以，但先加个 TODO 注释：
  // TODO(JIRA-456): 防重用校验，同用户同码只能用一次
  这样后续 PR 可以追踪」

Driver：「好，加上了。现在写测试——」

Agent：「先不写实现，先写一个失败的测试：
  it('should reject invalid coupon code', async () => {
    const result = await validateCoupon('INVALID', orderId);
    expect(result.valid).toBe(false);
    expect(result.reason).toBe('NOT_FOUND');
  });
  测试红了之后再写实现，TDD 步骤。」

Driver：「明白，运行 npm test — 测试红了，现在写实现」
(25 分钟后)
Driver：「实现完了，测试绿了，准备提交」

Agent：「提交信息格式：feat(checkout): add coupon validation with NOT_FOUND handling
  然后交换角色——下一轮你来导航员」

当 Agent 暂时充当驾驶员（例如生成脚手架）时，人类应切回导航员，显式验收每一步：编译、类型检查、与现有目录结构是否一致。

意见分歧决策规则

分歧发生时的处理步骤：
1. 导航员提出异议，驾驶员暂停，双方各用 1 句话陈述理由
2. 判断类型：
   a. 技术事实分歧（「这样写会有内存泄漏」）→ 写测试验证，数据说话
   b. 风格/命名分歧 → 查现有仓库规范；若无规范则 Driver 决定，记录 TODO
   c. 架构/设计分歧 → 超出本轮范围，记录为 ADR 草稿，本轮用最简单实现
3. 最终决策者：Driver 在本轮持有最终决策权
4. 分歧记录格式（写进 git commit body 或 PR 描述）：
   [DECISION] 选择方案 A 而非 B，原因：XXX
   [DEFERRED] 方案 C 暂缓，待 JIRA-789 中确认

增量提交的 git commit 格式

# 每次 Pomodoro 结束后提交，格式：
# <type>(<scope>): <简短描述>（50 字内）
#
# [可选 body：本轮实现了什么 / 决策记录]

# 示例：
feat(auth): add JWT token refresh endpoint

- 实现了 POST /api/auth/refresh
- 过期 token 返回 401，非法签名返回 403
- [DECISION] 用 RS256 而非 HS256，支持多服务验证

test(auth): add unit tests for token refresh

- 覆盖正常刷新、过期 token、签名错误三个分支
- 使用 jest.useFakeTimers 模拟 token 过期

# 禁止的提交格式：
# git commit -m "fix stuff"        ← 无法追踪
# git commit -m "WIP"              ← 不可 revert 到有意义状态
# git commit -m "更新了很多文件"   ← 无具体语义

PR 与审查卫生

结对的价值一部分要沉淀给异步审查者：在 PR 描述中写清「结对结论」——哪些方案被否决、为什么、有没有未竟事项。复杂重构可链接 ADR 或 issue，避免审查者重复争论已在键盘前 resolved 的点。

• 复杂改动结对前先跑通基线测试与类型检查，PR 只承载增量差异。
• 需要后续跟进的项用 checklist 或 TODO（带 owner），不要只留在对话记录里。