Harness Engineering 深度解析：从 Prompt 到 Context 再到 Harness，AI 工程的三次演进与落地实践

1. 从 Prompt 到 Context 到 Harness：AI 工程的三次演进

1.1 Prompt Engineering：让模型听懂

大模型本质上是一个对上下文极度敏感的概率生成器。它根据输入内容预测下一个字，输入越具体，输出越收敛。

写提示词的本质不是"命令"模型，而是塑造它的概率空间。一个完整的提示词通常包含六部分：角色设定、背景信息、参考资料、明确任务、约束条件、输出格式。把这些按结构组装起来，就是 Prompt Engineering 的核心工作。

Prompt Engineering 解决的是"表达"问题——模型不是不会，是没把话说明白。它在短链路任务（聊天、翻译、问答）中表现很好，但存在一个根本天花板：无法解决"信息"问题。模型对没见过的知识、动态变化的信息、长链路中的状态保持，都无能为力。

1.2 Context Engineering：让模型知道

当 Agent 形态出现后，模型不再只是回答问题，而是要进到真实环境里执行任务。这时问题从"这一次回答对不对"变成了"整条链路能不能跑通"。Context Engineering 正是在这个背景下接棒。

上下文（Context）的定义：每次发给模型的所有信息的总和，包括用户输入、历史对话、检索资料、工具返回结果、任务状态、中间产物、系统规则等。Context Engineering 要解决的核心问题是：在上下文窗口有限的前提下，把最相关的信息，以最合理的方式送给模型。它包含三个核心步骤：

• 召回（RAG）：从文档库、向量数据库、代码库中检索与当前任务最相关的信息。将文档切块、向量化存储，每次任务进来先搜索最相关的几块。
• 压缩（摘要）：检索结果可能超出窗口容量，需要对每一段做摘要过滤，移除冗余信息，控制上下文总量。
• 组装（关键信息靠后放）：大模型的注意力对"靠后的信息"更敏感，因此关键指令和当前任务应放在上下文靠后位置。

此外，渐进式披露是一个重要的实践原则：按需给、分层给、在正确时机给。初始只给能力目录，模型判断需要某项能力时，再动态加载详细说明。这避免了上下文被无效信息填满导致的注意力稀释。

Context Engineering 从"把任务讲清楚"升级到了"把信息送对"，但它依然有一个天花板：信息给对了，单步表现好了，但长链路任务依然会跑偏。

---

2. 第三阶段：Harness Engineering——让模型持续做对

2.1 核心问题

长链路任务中，即使提示词和上下文都正确，模型仍然会出现以下失败模式：

• 执行跑偏：计划做得好，执行时突然偏离了初衷
• 工具结果理解错误：调用工具调对了，但解析错了返回结果
• 状态丢失：在多个步骤之间遗忘了前面已经完成的工作
• 目标遗忘：在长任务链中逐渐偏离最初的系统目标

Prompt Engineering 优化的是"意图的表达"，Context Engineering 优化的是"信息的供给"，两者都停留在输入侧。当模型开始连续行动时，需要一个全新的系统来监督执行、约束行为、拉回偏差。

2.2 核心公式

Agent = Model + Harness
Harness = Agent − Model

在一个 AI Agent 系统中，除了模型本身之外，几乎所有决定它能不能稳定交付的东西，都属于 Harness。三者不是替代关系，而是包含关系：

Prompt ⊂ Context ⊂ Harness

Prompt 是对指令的工程化，Context 是对输入环境的工程化，Harness 是对整个运行系统的工程化。做 Harness 时必然包含 Context 工程，Context 工程里必然包含 Prompt 工程。

2.3 六层结构拆解

一个成熟的 Harness 可以拆成六层，按三组划分：输入侧（看得准）→ 动作侧（做得对）→ 校验侧（错了能兜底）。

分组	层级	一句话问题
输入侧	上下文精细化管理	模型这一轮该看到什么？
输入侧	记忆与状态管理	模型跨轮该记住什么？
动作侧	工具系统	模型用什么动手？
动作侧	任务执行编排	模型下一步该干啥？
校验侧	评估与观测	模型做得好不好有没有尺子？
校验侧	约束与恢复	模型出错了能不能爬起来？

以下用一个贯穿示例来说明：PR Review Agent，任务是每天定时扫描 GitHub 上关注仓库的新 PR，挑选值得关注的，生成摘要和点评，发送到 Slack。

2.3.1 上下文精细化管理

空间维度：每次调用时，模型该看到什么？这一层解决的是"当前这一轮的上下文结构"。

核心策略是渐进式披露：初始只给模型能力目录（“我有这些工具、这些规则、这些参考”），当模型判断需要某个能力时，再动态加载详细说明、参数定义、使用示例。这避免了上下文被无效信息填满，也减轻了模型在大量信息中筛选的负担。

在 PR Review Agent 中，每次触发时不会把全部仓库的 PR 列表都塞进上下文，而是先给一个"你有以下工具可用"的目录，当模型决定要查某个仓库时，才加载该仓库的 PR 清单。

2.3.2 工具系统

工具系统是模型对外部世界的操作接口，包括 API 调用、文件读写、Shell 命令、数据库查询等。工具系统需要解决以下问题：

• 工具注册：以统一格式定义工具的名称、参数、返回值、使用限制
• 参数校验：调用前校验参数类型和取值范围，防止运行时错误
• 结果解析：将工具返回的原始数据解析为模型可理解的结构化信息
• 工具选择：根据当前任务上下文，自动路由到最合适的工具

PR Review Agent 需要的工具包括：GitHub API 查询 PR 列表、获取 PR diff、读取仓库文件、发送 Slack 消息。

2.3.3 任务执行编排

任务执行编排将一个大任务拆解为可执行的步骤序列，并管理执行过程。核心流程：

• Plan 生成：Agent 分析任务目标，生成执行步骤的有向图
• Step 分解：每个步骤是一个原子操作，调用一个工具或执行一段逻辑
• 执行与校验：逐步骤执行，每步完成后校验结果，通过后才进入下一步
• 重试与回退：步骤失败时自动重试，达到阈值后回退到上一步或重新规划

PR Review Agent 的任务编排：查询 PR 列表 → 筛选值得关注的 PR → 读取每个 PR 的 diff → 生成本地化摘要 → 发送到 Slack。每个步骤的输出作为下个步骤的上下文输入。

2.3.4 记忆与状态管理

当任务跨越多个轮次时，模型需要记住前面已经完成的工作。记忆分为三层：

• 短期记忆：当前会话的任务上下文，包括本轮已执行步骤、中间结果、当前状态
• 长期记忆：跨会话的项目知识、用户偏好、历史决策记录
• 记忆操作：持久化存储、检索、合并、去重、过期清理

PR Review Agent 中，短期记忆记录本轮扫描了哪些仓库、哪些 PR 已处理；长期记忆记录用户偏好的 PR 筛选规则、历史点评风格。

2.3.5 评估与观测

评估与观测为模型的执行结果提供定量和定性的校验手段，解决"做得好不好"的问题：

• 正确性校验：通过单测、Lint、编译检查等自动化手段验证输出
• 完整性校验：检查是否覆盖了任务要求的所有要点
• 一致性校验：修改是否与现有代码风格、架构约束一致
• 观测手段：日志、指标、链路追踪，用于定位执行中的异常

PR Review Agent 的评估环节：检查生成的摘要是否包含关键变更、评审意见是否与代码上下文匹配、Slack 消息格式是否正确。

2.3.6 约束与恢复

约束与恢复是 Harness 的兜底层，确保系统在异常情况下仍能安全运行：

• 安全约束：文件权限、网络访问限制、敏感信息保护
• 异常恢复：自动重试、状态回滚、人工介入的触发机制
• 幂等性设计：确保重复执行不产生副作用

PR Review Agent 中，发送 Slack 消息的操作需要幂等——如果 Agent 重复执行，不会向同一个 PR 发送多次重复消息。API 调用失败时自动重试，超过阈值则放弃该 PR 并记录日志。

---

3. 落地实现路径：以 Claude Code 为例

3.1 规则文件（CLAUDE.md）

CLAUDE.md 是项目级的规则文件，定义 Agent 的行为边界和编码规范。它解决的是"模型知道项目规则"的问题，让 Agent 在每次执行任务前加载项目特有的约束。

规则文件的编写要点：

• 全局规则：适用于整个项目，定义技术栈、编码规范、架构原则
• 模块级规则：针对特定目录或模块，定义该模块的边界和约束
• 版本管理：CLAUDE.md 随代码库一起管理，规则变更通过 PR 审查

一个典型的 CLAUDE.md 包含以下内容：

# 项目全局规则
- 技术栈：Go 1.24 + chi + PostgreSQL
- 编码规范：遵循 Go 标准格式，error 必须处理
- 架构原则：分层架构，handler → service → dao

# 模块规则
- internal/service/ 下不允许直接调用 HTTP 接口
- api/ 下的 handler 只做参数校验和响应封装

3.2 任务拆解与规划驱动

大任务拆解是 Agent 落地的关键环节。将复杂任务按以下维度拆解：

• 按功能模块：每个模块独立为一个子任务
• 按文件：每个文件的修改作为一个独立步骤
• 按依赖顺序：先完成基础模块，再完成依赖模块

拆解后，Agent 自动生成 Plan（执行计划），包含每个步骤的输入、输出和验证条件。Plan 驱动执行，每个步骤完成后校验结果，通过后才进入下一步。

任务："添加用户注册接口"
Plan:
  Step 1: 创建用户表结构（model/user.go）
  Step 2: 实现 DAO 层（dao/user.go）
  Step 3: 实现 Service 层（service/user.go）
  Step 4: 实现 Handler 层（api/user.go）
  Step 5: 注册路由并验证

3.3 自动修复与验证闭环

自动修复是 Harness 的核心能力之一。执行 → 校验 → 发现错误 → 自动修复 → 重新校验，形成闭环。

校验门禁包括：

• 编译检查：代码是否能通过编译
• 单元测试：已有测试是否通过
• Lint 检查：代码风格是否符合规范
• 增量检查：新增代码是否引入了新的问题

当校验失败时，Agent 分析错误原因，定位问题文件，执行修复，然后重新进入校验流程。超过重试次数仍无法通过时，将问题标记为"需人工介入"并记录上下文。

执行 → 编译失败 → 分析错误日志 → 定位问题文件
→ 执行修复 → 重新编译 → 验证通过 → 提交

3.4 插件与工具链扩展

Agent 的能力边界通过工具系统扩展。Claude Code 支持 MCP（Model Context Protocol）工具注册机制，允许开发者自定义 Agent 可调用的外部工具。

常用工具类型：

• Web 搜索：获取最新的 API 文档和技术资料
• 文件操作：读写项目文件
• 数据库查询：执行 SQL 查询并返回结果
• API 调用：调用外部服务接口
• Shell 命令：执行构建、测试、部署等命令

工具调用链的编排规则：按依赖顺序执行，前一个工具的输出作为后一个工具的输入参数。每个工具的调用结果都经过校验侧过滤，异常结果触发重试或回退。

---

4. 总结

Harness Engineering 不是一次性架构设计，而是持续迭代的工程体系。每一次 Agent 犯错，都是环境升级的机会——将修复沉淀到规则文件、校验门禁、工具配置中，使 Agent 在结构上不可能再犯同样的错误。

落地路径可归纳为四步：

规则约束 → 任务拆解 → 规划执行 → 自动校验 → 闭环修复

• 规则约束（CLAUDE.md）定义 Agent 的行为边界
• 任务拆解将大问题转化为可执行的子任务
• 规划驱动按 Plan 逐步执行，每步验证
• 自动校验与闭环修复确保 Agent 稳定交付

Harness 的质量取决于这四步的完善程度，而不是模型本身的能力。模型是通用的，Harness 是项目的专属资产。