当模型能力逐渐商品化，真正拉开工程差距的不是“会不会写 Prompt”，而是你有没有一套能让 Agent 稳定、安全、可恢复、可度量 的 Harness。

很多团队已经验证过同一件事：

  • Demo 阶段靠模型能力可以跑得很快；
  • 生产阶段如果没有 Harness，系统会很快进入“偶尔可用、经常失控”。

本文从工程落地视角出发，重点回答三个问题：

  1. Harness Engineering 相比 Prompt/Context 的核心增量是什么；
  2. Claude Code 这类生产系统在代码层面如何实现可控执行；
  3. 哪些工程实践可以被团队直接复用。

一、2026 年为什么突然都在讲 Harness Engineering

2026 年开始，社区对 AI 编程范式的讨论明显从 Vibe Coding 转向 Agentic/Harness Engineering。核心原因不是概念流行，而是工程现实：

  • 模型更强后，问题不再是“能不能生成代码”，而是“能不能持续、可控地完成复杂任务”；
  • 长任务、多工具、多人协作下，系统失败往往不是模型推理失败，而是编排、权限、上下文、恢复路径失败；
  • 行业案例普遍指向同一个公式：

Agent = Model + Harness

一个准确的类比是：模型是 CPU，Harness 是操作系统。CPU 再强，没有调度、内存、权限和故障恢复，系统依然不可用。

二、三层概念关系：别再把它们并列

很多文章会把 Prompt、Context、Harness 并列成三件事，但更准确的是嵌套关系：

Prompt Engineering ⊂ Context Engineering ⊂ Harness Engineering

  • Prompt Engineering：怎么说（表达层）
  • Context Engineering：给模型看什么（信息层）
  • Harness Engineering：系统怎么运行、怎么约束、怎么恢复（执行层）

一句话：Prompt 决定“指令质量”，Context 决定“信息质量”，Harness 决定“系统质量”。

三、为什么 Claude Code 值得作为工程样本

从工程视角看，Claude Code 的价值并不在“某个私有技巧”，而在它提供了一个生产级 Agent 的完整骨架：

  • Query Loop（多轮工具循环）
  • 工具契约与调度
  • 权限与安全层
  • 上下文压缩与恢复
  • 子 Agent 编排
  • 观测与成本控制
  • 故障恢复与会话续跑

这恰好对应 Harness 的核心命题：让非确定性的模型行为被工程系统“驯化”为可交付结果。

四、Claude Code 的总体架构（工程视角）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
User / IDE / CLI
      │
      ▼
Command Layer (Slash Commands / Workflows / Skills)
      │
      ▼
Query Engine (Agent Loop)
  ├─ Tool Dispatcher
  ├─ Context Manager (Compaction)
  ├─ Permission & Security
  ├─ Sub-agent Orchestration
  └─ Telemetry / Cost Tracker
      │
      ▼
Tool Runtime (Read/Edit/Bash/Web/MCP/...)

从职责分层看，它不是“大模型 + 工具调用”的平面结构，而是一个多闭环系统。

五、六大子系统拆解：Harness 在代码里到底长什么样

5.1 Agent Loop：系统心跳，不是“单次问答”

核心模式是：

1
2
3
4
5
6
7
8
9
10
11
12
async function* queryLoop(state) {
  while (true) {
    const response = await callModel(state.messages, state.tools)

    if (response.stop_reason !== 'tool_use') {
      return response
    }

    const toolResults = await runTools(response.tool_uses, state)
    state = rebuildState(state, response, toolResults)
  }
}

关键不在循环本身，而在循环外的防失控设计：

  • 每类自动恢复仅尝试一次（防无限重试）
  • 压缩策略分层触发（轻压缩到重压缩）
  • 错误优先内部恢复，最后才向上抛出
  • 每次状态迁移记录原因（便于回放和断言）

这就是生产系统与 Demo 的分水岭：先承认失败是常态，再设计恢复主路径。

5.2 Tool 契约：把“会调用”升级为“可验证调用”

典型工具接口包含：

1
2
3
4
5
6
7
8
9
type Tool<Input, Output> = {
  inputSchema: ZodSchema<Input>
  checkPermissions(input, context): Promise<PermissionResult>
  isReadOnly(input): boolean
  isDestructive(input): boolean
  isConcurrencySafe(input): boolean
  interruptBehavior(): 'cancel' | 'block'
  call(input, context): Promise<Output>
}

工程价值：

  • Schema-first：参数先校验，减少“模型胡传参数”导致的运行时故障
  • 语义标签化：调度器可推断并发与风险等级
  • 权限内建：权限不是外挂，而是工具契约的一部分

5.3 工具编排：并发不是越多越好，而是按语义并发

实用调度原则：

  • Read/Grep/Glob 等只读工具可并发
  • Edit/Write/Bash 等副作用工具串行
  • 高风险动作进入更严格审批路径

这也是为什么“看上去很快”的系统不一定鲁莽：它并发，但有边界。

5.4 Context 管理：压缩不是删历史，而是维持可推理状态

常见四级策略可以抽象为：

  • snip：轻度裁剪最旧消息
  • microcompact：局部摘要
  • collapse：折叠大块工具输出
  • autocompact：重建摘要上下文（最后手段）

同时需要把系统不变量持续注入（项目规则、工具边界、会话约束），避免压缩后“失忆”。

工程重点：上下文是预算，不是仓库。

5.5 Permission + Sandbox：默认收紧，显式放开

生产级权限链路通常是多层决策：

1
2
3
4
5
6
Tool Request
  -> Rule/Mode Check
  -> Hook/Policy Check
  -> Classifier (optional)
  -> User Confirmation (ask)
  -> allow / deny

关键实践：

  • 三态决策（allow / ask / deny）
  • 白名单与路径模式
  • 副作用命令走沙箱隔离
  • 高风险“跳过权限”必须显式开关并审计

5.6 Sub-agent：用上下文隔离换可扩展性

子 Agent 不只是“多开一个线程”，而是：

  • 独立上下文窗口（避免污染主会话）
  • 可裁剪工具集（最小权限）
  • 结果摘要回填（天然压缩）

这使“主 Agent 规划 + 子 Agent 执行”的模式能在复杂任务中长期工作。

六、必须保留的高价值技术细节

6.1 分层提示词与缓存稳定性

分层优先级（示意）：

1
Override > Coordinator > Agent > Custom > Default > Append

价值在于：

  • 既能按场景覆盖，又能保持主干提示词稳定
  • 主干稳定意味着缓存命中率更高，延迟和成本更可控

6.2 Hook 机制不是装饰，而是反馈回路

典型事件包括：

  • PreToolUse / PostToolUse
  • PermissionRequest
  • PreCompact / PostCompact
  • SessionStart / SessionEnd

Hook 的工程价值：

  • 在关键节点插入校验与策略
  • 将系统行为“可编排化”
  • 为后续自动化治理预留扩展点

6.3 恢复策略与检查点边界

生产系统应记录可恢复边界，例如：

  • 某次 bash 已完成
  • 某次 edit 已提交
  • 某工具调用被拒绝

这样中断后可“从最近可验证边界恢复”，而不是整段任务重来。

七、性能优化：不是玄学，而是具体工程动作

7.1 工具顺序稳定，换取缓存命中

1
2
3
4
5
// ❌ 不稳定顺序
[...builtinTools, ...mcpTools].sort((a,b) => a.name.localeCompare(b.name))

// ✅ 内置工具顺序固定，动态工具局部排序
[...builtinTools, ...mcpTools.sort((a,b) => a.name.localeCompare(b.name))]

7.2 并发分批，避免工具互相踩写

1
2
3
4
5
const limit = 3
for (let i = 0; i < calls.length; i += limit) {
  const batch = calls.slice(i, i + limit)
  await Promise.all(batch.map(runTool))
}

7.3 压缩后做“选择性恢复”

1
2
3
const compacted = await compact(messages)
const keyFiles = getRecentlyUsedFiles(fileCache, 5)
return restoreFiles(compacted, keyFiles)

这三件事通常就能明显改善“慢、贵、易丢上下文”三大问题。

八、工程落地清单（按优先级）

P0：先把系统拉到“可控”

  1. 建立上下文预算阈值（建议先监控 40% 利用率拐点）
  2. 给每个工具补齐 只读/破坏性/并发安全 语义标签
  3. 把权限判断迁移到代码路径强制执行（不要只靠提示词）

P1：把“可控”升级为“可持续”

  1. 上线分层记忆与老化策略（项目/会话/团队）
  2. 上线自动压缩 + 恢复边界
  3. 建立可观测闭环（Token、成本、时延、失败率、关键事件）

P2：把“可持续”升级为“可规模化”

  1. 引入协调者-执行者多 Agent 架构
  2. 建立失败回滚纪律（失败先回滚，而非硬修补）
  3. 定期做 Harness 减法，降低系统复杂度债务

九、常见误区（实践版）

  • 误区 1：只优化 Prompt，不治理工具与权限
  • 误区 2：默认全量上下文，等爆了再救火
  • 误区 3：把并发当性能捷径，忽略副作用冲突
  • 误区 4：把 Hook 写成“万能脚本”，失去边界与可维护性
  • 误区 5：没有恢复路径，所有异常都靠“重试碰碰运气”

对应实践是：边界前置、语义前置、恢复前置、观测前置。

十、如何部署 Harness Engineering：一个可落地的最小方案

下面给一套“能跑起来”的部署方案，适合中小团队从 0 到 1。

10.1 最小部署架构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
Web/CLI Client
    │
    ▼
API Gateway (鉴权 / 限流 / 会话)
    │
    ▼
Agent Orchestrator
  ├─ Planner (任务分解)
  ├─ Executor (工具调用)
  ├─ Policy Engine (权限决策)
  └─ Context Manager (压缩/恢复)
    │
    ├─ Tool Runtime (Read/Edit/Bash/Web/MCP)
    ├─ Queue (重任务异步化)
    ├─ State Store (会话与检查点)
    └─ Telemetry (日志/指标/追踪)

10.2 目录建议（单仓库）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
agent-platform/
├─ apps/
│  ├─ api/                # HTTP 接口
│  ├─ worker/             # 异步任务执行
│  └─ cli/                # 本地调试入口
├─ packages/
│  ├─ orchestrator/       # Agent Loop 与编排
│  ├─ tools/              # 工具契约与实现
│  ├─ policy/             # 权限与规则引擎
│  ├─ context/            # 压缩与恢复
│  └─ observability/      # 埋点与追踪
└─ infra/
   ├─ docker-compose.yml
   └─ k8s/

10.3 本地部署步骤（推荐先跑通）

  1. 启动依赖服务：Redis（队列）、PostgreSQL（状态）、OTel Collector（观测）
  2. 启动 API + Worker：分进程运行，避免工具执行阻塞接口
  3. 加载策略配置：默认 deny，按工具逐步放开
  4. 跑一条端到端任务：计划 -> 调工具 -> 产出 -> 记录指标
  5. 验证恢复路径：手动中断后恢复会话，确认边界生效

10.4 生产部署关键点

  • 鉴权与租户隔离：每个组织独立策略空间与日志空间
  • 工具沙箱：命令执行与文件写入隔离，限制网络出口
  • 配额系统：按用户/项目设置 token、并发、时长预算
  • 灰度发布：先灰度新工具与新策略，观测异常再全量
  • 审计留痕：所有高风险工具调用要可追溯

十一、如何使用这套工作流：团队日常执行模板

部署只是开始，关键在“怎么用”。下面是一套可以直接执行的工作流。

11.1 单任务工作流（标准版）

  1. 任务定义：输入目标、边界、验收标准
  2. 任务分解：Planner 拆成可执行子任务
  3. 策略编译：给每个子任务绑定工具与权限范围
  4. 执行阶段：Executor 调工具，实时回填中间结果
  5. 验证阶段：自动跑 lint/test/build 与策略校验
  6. 收敛阶段：输出结果 + 风险说明 + 下一步建议
  7. 归档复盘：记录失败点，沉淀成下一版策略

11.2 每日运行节奏（实战建议）

  • 上午：批量处理“高确定性任务”（重构、迁移、批修）
  • 下午：处理“中等确定性任务”（新增功能、接口联调）
  • 傍晚：统一跑回归与成本复盘（Token/失败率/恢复次数）

11.3 团队角色分工（避免全员混用）

  • Harness Owner：维护策略、权限、观测指标
  • Feature Owner：定义业务验收标准与边界
  • Reviewer：审核高风险调用与关键改动

11.4 衡量是否有效的 5 个指标

  • 任务一次完成率
  • 平均恢复次数（越低越好）
  • 单任务 token 成本
  • 高风险调用占比
  • 回归失败率

如果这 5 个指标持续变好，说明你的 Harness 正在产生真实工程收益。

十二、结语

Harness Engineering 不是“提示词增强版”，而是 AI Agent 的系统工程学。

Claude Code 给我们的核心启发是：你要交付的不是一次成功推理，而是一套在失败时也能稳定工作的执行系统。

模型会持续进化，但能不能把模型能力转化为长期生产力，最终看 Harness。

参考资源

注：本文为工程实践向整合稿，重在抽象可复用设计模式与落地路径；源码示意为简化表达，实际生产实现应补齐边界处理、审计与测试。