Coding Agent 与 Harness 工程

何时使用

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

核心原则

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

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

任务四象限（目标清晰度 × 验证自动化程度）——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 工程：模型之外的竞争力」