ADR-003 — 工程实施栈与协作模式

决策

工具栈

1. OpenSpec 承担 spec / 提案层：与现有 governance/proposals/ 模式契合，里程碑提案与修复提案走 OpenSpec 流程
2. Archon 承担里程碑工作流执行：每个里程碑写一个 .archon/workflows/milestone-MX.yaml，含：
   • 确定性 gate 节点：脚本（npm run verify:kb、npx docusaurus build、grep 检查），不依赖 Agent 主观判断
   • AI 实施节点：实际写代码 / 改文档 / 跑测试
   • PR 节点：自动开 PR + 关联 issue
   • git worktree 隔离：每个里程碑工作流跑在独立 worktree 不互相干扰
3. 现有 engineering/ 文档作为契约事实源：所有里程碑实施不得背离

Agent 协作模式（每个里程碑标准流程）

阶段	谁做	产出
Spec	Claude Code	在 OpenSpec / governance/proposals/inbox/ 写里程碑提案：task packet + 数据结构 diff + 验收口径 + 与战略 + engineering/* 文档的追溯
实施	Codex	工作流维护者把 OpenSpec 提案包成自包含 task spec 交给 Codex；Codex 在 git worktree 里实施；产 PR
Review	Claude Code	review Codex 的 PR；跑确定性 gate；跨文档一致性核查；出 review report
认知质量评估	工作流维护者 + 跨 Agent 模拟视角	评估方法待 OQ-002 / 后续 CHAP-20 / CHAP-21 定义
Merge + 移交下一里程碑	Claude Code	提案移到 accepted/；更新 status.md / 章节追踪表

关键原则

• 实施者不当自己代码的 reviewer（fresh eyes 原则 · 一阶）
• spec 起草人不当自己 spec 的 reviewer（fresh eyes 原则 · 二阶，2026-05-28 Step 11 Action III-3 新增）
• 确定性 gate 由脚本节点执行（不依赖任何 Agent 的主观判断，保证可重复）

fresh-eyes 二阶原则（2026-05-28 新增）

问题：spec 起草人（Claude 主控 / Codex）作为 AI 同时承担 spec 起草 + PR review 时，"承认自己 spec 错"的心理成本极低（只是改文档），"承认自己作为 reviewer 错过 spec bug"的心理成本极高（要重 review），存在结构性 bias。Step 10 完整通读 review 发现这是 9 步 review 没收敛的核心根因之一。

应对（用户 2026-05-28 拍板：AI 三方互审 + 人介入混合方案）：

1. P0 决策（战略不变量级 / 合规底线）：

   • 人类用户必签
   • AI 三方仅起草建议方案（Claude 主控 + Codex + 第三方 AI 各自独立产 1 页 signed brief）
   • 决议落盘必须含 user_id + timestamp + signature（GPG 签名或显式声明）
   • 不接受 PR audit trail inline 30 min 决议
   • 详细签字协议见 owner map §2.2

2. P1 决策（工程契约级，有外部影响）：

   • AI 三方互审协议：
     1. Claude 主控起草 spec
     2. Codex 工程实施 review（fresh-eyes 一阶 — 实施可行性视角）
     3. 第三方 AI（默认 OOSO，备选 Cursor / Hermes）独立 review（fresh-eyes 二阶 — 跳出 Claude/Codex 内部互审）
     4. 三方一致 → 决议落盘 audit trail
     5. 三方不一致 → 升级到人类用户审（可能转 P0）
   • 工作流维护者 / 项目所有者 T+30 天回查 audit trail

3. P2 决策（工程实施细节级）：

   • AI 双签（Claude + Codex）可
   • PR audit trail inline 决议
   • 不强制 OOSO 三方互审

4. 每个 milestone 至少 1 个 PR gate 由人类工作流维护者亲自走：

   • 不只签字
   • 亲自 review 关键 PR
   • 主控辅助

5. M0 验收人工 5 条 checklist 评分人：

   • 必须含真人维护者
   • 不能仅 AI

AI 三方第三方角色选择

• 默认：OOSO（M0 启动时确认可用性）
• 备选：Cursor / Hermes / Claude 主控不同 sub-agent context（fallback）
• 正式选定时点：M1 启动前确定常驻角色
• fallback 兜底：OOSO 不可用 → 降级为人类工作流维护者直接 review（不缺失 fresh-eyes 二阶）

配套实施

• pending-decisions-owner-map.md 27 项已按 P0 / P1 / P2 三档分级（Step 11 Action III-1）
• .archon/workflows/pr-review-checklist.md 第 11 项加 P0 决策触及检查（Step 11 Action III-4）
• scripts/audit_p0_decision_touch.mjs 自动校验 PR 是否触及 P0 项（Step 11 Action IV-2）
• 详见 Step 11 整改包详细方案 III

上下文

工作流维护者既有多 Agent 协作能力（Claude Code 与 Codex 是对等主控，能力对等）。FinBayes 工程化是长链路多步骤任务，需要明确工具栈与角色分工避免：

• 多 Agent 各自维护"心智模型"导致漂移
• 实施者既写又评的质量盲点
• 长链路中契约慢慢失保

后果

收益：

• spec 驱动 + 工作流执行的分工清晰，每个里程碑可重复
• 多 Agent 并行能力得到释放，各做擅长的事（Claude Code 强在编排 / multi-file 操作 / 跨 Agent 三角验证；Codex 强在 coding 吞吐量 / 配额充裕 / 自包含任务黑盒委托）
• 确定性 gate 提供战略保真度硬保障，不依赖 Agent 主观判断
• 实施者与 reviewer 分离避免质量盲点

成本：

• 学习新工具（OpenSpec + Archon）的前期投入约 2-3 天
• 多 Agent 交接 protocol 需要严格执行（status.md 末尾的交接 prompt 模板）
• 每个里程碑工作量增加 review + gate 环节
• 工作流配置（YAML）本身的漂移风险需要纳入 governance change-protocol 管理

备选方案

考虑过未采用：单 Agent 独占（浪费另一 Agent 能力 + 失去跨 Agent 验证）/ 不用 Archon 由 Claude Code 直接调度脚本（workflow 表达力弱 + 可重复性弱）/ GSD + OMOC + OMX（更轻但缺 spec 层与 workflow 执行的严谨）/ 单 Multica 不配合 OpenSpec + Archon（缺 spec 与 workflow 强约束容易漂移）/ deer-flow（研究探索定位不匹配）/ OpenHarness（底层 runtime 不是工作流）。

关联

• 工程范式决策见 ADR-001
• 架构文档结构决策见 ADR-002
• 多 Agent 交接 prompt 模板在 status.md 末尾
• 工具栈与角色分工的具体落地由后续里程碑实施时实际验证
• M0 工作流契约首发实例：可执行 workflow 仓内路径 .archon/workflows/milestone-M0.yaml（真 Archon schema：确定性 gate=bash / AI 实施=prompt / 人工 gate=approval；archon validate 通过）+ 契约规约 .archon/specs/milestone-M0.spec.yaml（确定性 gate / AI 实施 / PR 三类节点富语义拓扑 + pass_criteria）；目录说明见仓内 .archon/README.md（Archon 运行态约定不进公开站点）