Harness Design Patterns
Agent harness 架构设计决策参考。蒸馏自 Claude Code 内部架构、OMC、Anthropic/OpenAI harness engineering 博客。
When to Use
- 设计多阶段任务的上下文传递方案 → Handoff 文档 / Compaction 提取
- 选择多 agent 的协调模式 → Coordinator / Fork / Swarm 选型
- 设计 hook 系统架构 → Hook Pair Bracket / Component-Scoped / Profiles
- 评估任务复杂度以选择执行强度 → Adaptive Complexity
When NOT to Use
- 需要可执行的 hook 脚本 → 用
agent-hooks - 需要运维工具（限速恢复、session 监控） → 用
agent-ops - 需要 prompt 硬化 → 用
prompt-hardening
10 个设计模式
| # | 模式 | 解决什么 | 详情 |
|---|---|---|---|
| 1 | Handoff 文档 | 跨阶段/跨压缩的上下文传递 | 详情 |
| 2 | 原子文件写入 | 并发状态文件安全 | 详情 |
| 3 | Compaction 记忆提取 | 压缩前被动抢救知识（PreCompact hook） | 详情 |
| 4 | 权限否决追踪 | 防止 agent 绕过拒绝 | 详情 |
| 5 | 三门控记忆合并 | 跨 session 记忆碎片化 | 详情 |
| 6 | Hook Pair Bracket | 每轮 context/时间测量 | 详情 |
| 7 | Component-Scoped Hooks | 任务级别的 hook 控制 | 详情 |
| 8 | 三种委托模式 | 多 agent 协调方式选型 | 详情 |
| 9 | Adaptive Complexity | 任务复杂度自适应 | 详情 |
| 10 | Hook Runtime Profiles | 环境级 hook 强度控制 | 详情 |
注：reference 文件名保留原始编号（02/06/08/...）以兼容 monorepo 中的交叉引用。
常见场景选型
| 场景 | 推荐模式 |
|---|---|
| 多阶段任务（plan → implement → verify） | Handoff 文档 + Compaction 提取 |
| 选择 Coordinator / Fork / Swarm | 三种委托模式选型指南 |
| Hook 太多互相干扰 | Component-Scoped Hooks + Hook Profiles |
| 不同环境需要不同保障级别 | Hook Runtime Profiles (minimal/standard/strict) |
| 简单任务 overhead 太高 | Adaptive Complexity (triage → 自动选执行模式) |
工作流程
Step 1: 识别问题
当遇到 agent 可靠性问题时，判断属于哪一类：上下文丢失、协调混乱、hook 冲突、或执行强度不匹配。
Step 2: 选型
根据「常见场景选型」表找到对应模式，MUST 先读 reference 详情再做决策，otherwise 可能误用模式。
Step 3: 应用
如果需要可执行脚本 → 切换到 agent-hooks skill。如果需要运维工具 → 切换到 agent-ops skill。如果不确定 → 先从最简单的模式开始试验。
Output
当被询问 harness 设计建议时，returns:
- 推荐的模式名称及原因
- 该模式的 tradeoff 说明
- 具体的实施步骤指引（指向 agent-hooks 或 agent-ops 中的脚本）