# Coding Agent Harness

搭建 Coding Agent 或设计 Agent 护栏时使用, , 当你要构建能自主读写代码、跑测试、自我纠错的编码 Agent，或为已有 Agent...

- Repository: https://github.com/bojieli/ai-agent-book (56844 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-10-08
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add bojieli/ai-agent-book --skill coding-agent-harness -g -a claude-code -y`
Codex: `npx skills add bojieli/ai-agent-book --skill coding-agent-harness -g -a codex -y`
Cursor: `npx skills add bojieli/ai-agent-book --skill coding-agent-harness -g -a cursor -y`
Gemini CLI: `npx skills add bojieli/ai-agent-book --skill coding-agent-harness -g -a gemini-cli -y`

## Description

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

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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 的最小清单**：

The rest: https://github.com/bojieli/ai-agent-book/blob/HEAD/skills/coding-agent-harness/SKILL.md