---
name: coding-agent-harness
description: 搭建 Coding Agent 或设计 Agent 护栏时使用——当你要构建能自主读写代码、跑测试、自我纠错的编码 Agent，或为已有 Agent 系统补约束/验证/纠正机制、设计执行边界与验收基线、判断某类任务是否适合交给 Agent、优化 Harness 提示词与工具集时使用。覆盖 Harness 四组件、任务四象限、四条设计原则与业界实践。
---

# Coding Agent 与 Harness 工程

## 何时使用
- 从零搭建 Coding Agent（选工具集、定工作流、接测试反馈）
- 为已有 Agent 补可靠性：加护栏、验收基线、执行边界、回退手段
- 评估一个任务是否适合交给 Agent 自主执行（四象限判断）
- Agent "能跑但不可靠"：跑偏、走破坏性捷径、过早宣布完成
- 优化 Harness 本身（提示词、工具中间件、自验证循环）而不是换模型

## 核心原则

**Agent = Model + Harness，Harness = 上下文管理 + 工具接口 + 约束 + 验证 + 纠正。**
Harness 是"Agent 边界内、模型之外"的运行与治理层：工具定义、调用适配器、沙箱权限属于 Harness；沙箱内的文件进程、外部数据库、用户属于 Environment。模型能力趋同后，竞争力在 Harness。

**Coding Agent 场景的 Harness 四组件**（把抽象机制落地成工程件）：

| 组件 | 回答的问题 | 落地形态 |
| --- | --- | --- |
| 验收基线 | 什么算做完了 | 测试套件、CI 管道、代码审查标准 |
| 执行边界 | 能碰什么不能碰什么 | 模块边界、依赖规则、权限控制 |
| 反馈信号 | 自动化的对错判断 | Linter 输出、测试结果、类型检查错误 |
| 回退手段 | 出了问题怎么恢复 | Git 版本控制、沙盒隔离、快照回滚 |

**任务四象限（目标清晰度 × 验证自动化程度）**——Harness 的目标是把任务推向"目标明确 + 可自动验证"：

- 目标明确 + 可自动验证 = **最佳区域**（修复有测试用例的 bug）
- 目标明确 + 需人工验证 = **吞吐量受限**，天花板是人的审查速度
- 目标模糊 + 可自动验证 = **高效地跑偏**（如拿 linter 分数优化"代码质量"）
- 目标模糊 + 需人工验证 = **难以启动**（如"让 UI 更好看"）

代码编写天然处于象限核心：测试套件给验收标准，Linter/类型检查给即时验证，Git 给版本控制与回退。Coding Agent 成熟度最高不是因为代码模型最强，而是软件工程几十年积累的基础设施天然就是一套 Harness。

**四条可迁移的设计原则**：

1. **约束优先于指导**——能用代码强制的规则不要用文档建议。Linter 规则、类型约束、CI 检查是"做不了"，系统提示词里"请遵循..."只是"建议别做"。
2. **验证要自动化**——人工审查是不可扩展的瓶颈，测试/检查/监控的投入回报率远高于加人力。
3. **反馈越快越好、越结构化越好**——错误信息越详细、越接近出错时刻，Agent 纠正效率越高。
4. **回退要可靠**——有安全网 Agent 才敢试错；Git 分支、沙盒、快照确保任何错误可逆。

**约束管动作，不只是管结果。** 验收基线管结果对不对，执行边界管过程：删库重建"修复"了故障但数据没了，删光重写让编译通过但实现没了。这类破坏性捷径 Agent 总能绕开指标找到（reward hacking 的日常形态），因此 `rm -rf`、删生产数据、覆盖未读文件要设专门检查与审批。

**并行调用的故障边界控制**：一个工具失败时，故障只在同一批并行调用内传播（级联中止依赖它的调用），不取消独立调用，不上升到父级操作、不让整个任务中止。每个工具声明是否支持并发（默认否，失败安全）。

**业界经验**：
- 大规模代码迁移成功靠三件事：知识必须存在于代码库本身（Agent 看不到的等于不存在）、约束编码进 Linter/CI 而非文档、验证与纠正全链路自动化。
- LangChain 只优化 Harness（提示词、工具中间件、自验证循环）就把 Terminal Bench 2.0 从 52.8% 提到 66.5%，并用 Agent 分析失败轨迹反哺 Harness，让 Harness 工程从经验驱动变数据驱动。
- Anthropic 拆两个角色：初始化 Agent 分解任务清单，执行 Agent 逐步推进并留下清晰的交接产物，解决"一次想做太多"和"过早声称完成"。

## 实践模式

**建一个 Coding Agent 的最小清单**：

1. **工具集**：文件读写（read/write/edit）、目录浏览（glob/ls）、内容搜索（grep）、命令执行（bash）七件套；每个工具命名直观、参数带例子、边界有说明（防呆设计）。
2. **工作流**：先理解项目（读文档、建认知框架）→ 设计 → 实现 → **立即写测试并跑** → 失败则分析-定位-修复循环，直到测试全绿。把"测试通过"而非"代码写完"定义为完成标准——跳过测试直接报完成是 Coding Agent 最常见的偷懒方式。
3. **验收基线**：接入现成的测试套件、Linter、类型检查、CI；没有就先补最小可跑的。
4. **执行边界**：默认权限最小化（故障安全默认值，能力默认关闭、显式开放）；危险命令走审批。
5. **回退手段**：每次任务前开 Git 分支或快照；沙盒内执行不可逆操作。
6. **反馈回路**：把 Linter/测试/编译错误结构化地喂回上下文（附行号、文件路径、错误类型）。
7. **持续改进**：收集失败轨迹，让 Agent 分析轨迹反哺 Harness 修改。

**上下文与环境注入**（Harness 的上下文层）：大文件按行号范围读取并给每行加行号前缀；长命令输出只保留头部（错误上下文）与尾部（错误总结）并说明完整输出已落盘；每次推理前以状态栏形式动态注入当前工作目录、git 分支、最近提交、未暂存变更（动态追加，别硬编码进系统提示词以免破坏 KV Cache）；维护持久化终端会话保留 cd/环境变量状态。

## 常见陷阱
- 把指导写进提示词而不落成代码约束——模型会忽略"请遵循..."式建议
- 没有验收基线就放权：Agent 高效地往错误方向跑，或走破坏性捷径（删库重建、删光重写）
- 写完代码不跑测试就报告"任务完成"
- 把整个代码库一股脑塞进上下文，既不经济也没必要
- 一个工具失败就中止整批并行调用甚至整个任务
- 只换模型不修 Harness：基准提升往往来自 Harness 而非模型
- 环境信息硬编码在静态系统提示词里

## 配套代码
- `chapter5/coding-agent/` — 纯 Python 实现的生产级 Coding Agent：16 个工具、patch 应用、测试/lint 验收反馈与失败路径
- `chapter1/context/` — 上下文感知 Agent 与消融实验：量化 history/reasoning/工具调用/工具结果各自的作用
- `chapter1/web-search-agent/` — 基于 Kimi Formula API 的自主 ReAct 搜索 Agent，展示"模型即 Agent"的最小闭环
- `chapter1/search-codegen/` — Responses API 深度研究 Agent：托管 web_search + code_interpreter 的编排
- `chapter1/learning-from-experience/` — LLM 上下文学习 vs 传统 RL 对照，理解 Agent 经验从哪来
- `chapter1/image-gen-workflow/` — 工作流路线 vs 原生生成路线对照：何时该用固定 Harness、何时该交给模型自主

## 深度阅读
- `book/chapter5.md`「Coding Agent」→「Harness 工程在 Coding Agent 中的实践」
- `book/chapter1.md`「Harness 工程：模型之外的竞争力」