使用 Claude Code、Codex、Skills、MCP 或多 Agent 工作流时，经常会遇到两个容易混淆的概念：Harness 和 Agent Loop。它们有什么区别？使用现成的编码 Agent 后，项目团队还需要做什么？
先给结论：
- Agent Loop 是 Agent 不断“推理 → 行动 → 观察 → 再推理”的执行循环。
- Harness 是承载、约束并扩展这个循环的完整运行系统。
- Claude Code 和 Codex 已经提供了产品级 Harness，日常开发不需要重新实现底层循环。
- 项目团队真正值得建设的是一套轻量的项目级 Harness：明确规则、架构边界、运行方式和验收标准，让 Agent 在你的项目里正确工作。
Harness、Agent Loop 与项目级 Harness 完整知识总览
一、Agent Loop：Agent 如何一步步完成任务
Agent Loop 回答的是一个核心问题：
模型完成当前一步以后，接下来应该做什么？
一个最简化的循环可以表示为：
读取用户目标
↓
模型分析并决定下一步
↓
调用工具
↓
执行操作并获得结果
↓
将结果放回上下文
↓
继续分析，直到任务完成
Agent Loop 从用户目标到持续迭代的执行流程
伪代码大致如下：
while (!done) {
const response = await model.generate(context)
if (response.toolCall) {
const result = await executeTool(response.toolCall)
context.push(response, result)
continue
}
done = true
return response.text
}
真实系统当然复杂得多，还要处理多工具调度、失败重试、上下文压缩、终止判断、无限循环、用户中途追加要求，以及子 Agent 调度等问题。
但无论实现多复杂，Agent Loop 的核心都可以压缩成一句话：
Reason → Act → Observe → Reason
也就是“推理、行动、观察，再继续推理”。
二、Harness：Agent 在什么环境和规则下运行
Harness 原意是控制装置、线束或挽具。在 Agent 领域，可以把它理解为：
把模型、Agent Loop、工具和运行环境连接起来，并保证它们安全、稳定运行的系统。
一个典型的 Harness 可能包含：
Harness
├─ Agent Loop
├─ 模型调用与模型选择
├─ Prompt / 上下文构造
├─ 工具注册与执行
├─ 文件系统和 Shell
├─ 权限审批与沙箱
├─ 会话状态持久化
├─ 上下文压缩
├─ 超时、重试和预算控制
├─ 日志与可观测性
├─ MCP / Skills / Hooks
└─ 子 Agent 与任务编排
Harness 由 LLM、Agent Loop、工具、上下文和沙箱组成
业界对 Harness 的边界没有完全统一。本文采用较宽泛的工程定义：
Agent Loop 表示执行流程；Harness 表示承载这套流程的完整运行系统。
三、Harness 和 Agent Loop 到底差在哪？
| 对比维度 | Agent Loop | Harness |
|---|---|---|
| 关注范围 | Agent 的循环执行逻辑 | Agent 的完整运行系统 |
| 核心问题 | 下一步做什么，何时结束 | 以什么工具、权限、上下文和规则运行 |
| 工具调用 | 决定何时调用工具 | 注册、执行、限制并记录工具调用 |
| 上下文 | 消费并更新上下文 | 构造、裁剪、压缩和持久化上下文 |
| 权限与沙箱 | 通常不直接负责 | 通常负责 |
| 错误处理 | 决定是否继续 | 提供超时、重试、恢复和降级机制 |
| 二者关系 | Harness 的核心组成部分 | 包含 Agent Loop |
可以用机器人做类比：
- LLM 是大脑；
- Agent Loop 是“思考—行动—观察—再思考”的循环；
- Tools 是手、眼睛、终端和编辑器；
- Context 是工作记忆；
- Sandbox / Permission 是安全护栏；
- Harness 是整个身体、控制系统和安全装置。
一句话概括：
Agent Loop 决定执行顺序，Harness 决定执行能力和运行边界。
四、用“修复一个 Bug”理解两者
假设我们让 Codex 修复一个前端 Bug：
读取用户描述
↓
搜索相关代码
↓
分析根因
↓
修改代码
↓
运行测试
↓
根据测试结果继续修改
↓
测试通过并输出结果
其中这段循环属于 Agent Loop：
搜索 → 分析 → 修改 → 测试 → 观察结果 → 再次分析
而下面这些问题属于 Harness：
- 如何搜索和读取文件？
- 如何应用代码补丁？
- Shell 命令在哪个目录执行？
- 哪些命令需要用户审批？
- Agent 是否允许访问网络？
- 测试超时后如何处理？
- 上下文过长时如何压缩？
- 会话中断后如何恢复？
- 如何加载
AGENTS.md、CLAUDE.md、Skills 和 MCP？
前者描述“任务怎样循环推进”，后者定义“这套循环拥有什么能力、受到什么约束”。
五、用了 Claude Code 或 Codex，还要自己实现 Harness 吗？
通常不需要。
Claude Code 和 Codex 本身已经是成熟的编码 Agent Harness，处理了大量底层工作：
- 模型调用与 Agent Loop；
- 文件搜索和编辑；
- Shell 命令执行；
- 工具调用结果回填；
- 上下文管理与压缩；
- 权限控制和沙箱；
- 会话保存与恢复；
- MCP、Skills 等扩展机制。
因此，日常项目开发没有必要再手写模型调用、动作解析、工具执行和结果回填的底层循环。
只有当你的目标是开发一个类似 Claude Code、Codex 的 Agent 产品，或者需要完全自定义模型、工具、状态和调度方式时，才需要深入产品级 Harness。
但这不代表项目侧什么都不需要做。
六、真正要建设的是“项目级 Harness”
可以把 Harness 分成三个层级：
1. 产品级 Harness
由 Claude Code、Codex 等产品提供，负责 Agent Loop、工具、权限、上下文和会话。项目团队一般不需要重新实现。
2. 项目级 Harness
由项目团队维护，负责项目规则、架构边界、运行方式和验收标准。
它要帮助 Agent 回答：
- 项目怎么启动？
- 使用 npm、pnpm 还是 yarn？
- 新功能应该放在哪个模块？
- 哪些目录不能修改？
- 修改业务逻辑后要运行哪些测试？
- 满足什么条件才算任务完成？
项目级 Harness 通常不是一个独立框架，而是一组工程设施：
项目级 Harness
├─ CLAUDE.md / AGENTS.md
├─ README 和架构文档
├─ package.json scripts
├─ lint / typecheck / test / build
├─ Docker 和环境初始化脚本
├─ .env.example
├─ Hooks
├─ Skills
├─ MCP
└─ Definition of Done
3. 任务级 Harness
面向大规模迁移、安全审计、复杂研究和多方案验证等任务，临时负责拆分、并行执行、独立复核和结果汇总。
产品级、项目级和任务级 Harness 的三层结构
例如：
规划 Agent
↓
多个执行 Agent 并行处理
↓
Reviewer Agent 独立检查
↓
测试 Agent 验证
↓
汇总 Agent 生成最终结果
七、普通项目最少需要哪些 Harness？
对于 TypeScript、React、Next.js 或 Node.js 项目，不必一开始就设计复杂的多 Agent 系统。先把下面四件事做好，收益往往更高。
1. 写清楚项目指令
Claude Code 通常读取 CLAUDE.md，Codex 可以读取 AGENTS.md。内容不用追求长，关键是明确、可执行。
# Project Overview
This is a pnpm monorepo using Next.js and TypeScript.
## Commands
- Install: `pnpm install`
- Type check: `pnpm typecheck`
- Lint: `pnpm lint`
- Unit tests: `pnpm test`
- Build: `pnpm build`
## Working Rules
- Do not use npm or yarn
- Avoid modifying unrelated files
- Run typecheck after changing TypeScript code
- Update tests after changing business logic
## Definition of Done
1. TypeScript passes
2. Relevant tests pass
3. No unrelated files are changed
4. The final response explains the root cause and validation
2. 提供确定性的验证命令
不要只告诉 Agent“确保代码没问题”，而要提供真正能执行的验证方式：
{
"scripts": {
"lint": "eslint .",
"typecheck": "tsc --noEmit",
"test": "vitest run",
"build": "next build",
"verify": "pnpm lint && pnpm typecheck && pnpm test"
}
}
验证命令越明确，Agent 越容易形成稳定闭环：
修改代码 → 运行验证 → 观察错误 → 继续修复 → 验证通过
3. 准备可重复的开发环境
最好让新开发者和 Agent 都能通过少量命令启动项目：
pnpm install
docker compose up -d
pnpm dev
同时准备好 .env.example、docker-compose.yml、README.md 和初始化脚本，不要让 Agent 猜测数据库、Redis、Node 版本、服务启动顺序或测试账号的配置方式。
4. 按需使用 Hooks、Skills 和 MCP
它们解决的问题不同：
- Hooks：在固定时机确定性执行动作，例如格式化、检查危险命令或运行验证；
- Skills：沉淀可复用的多步骤流程，例如性能排查、代码审查或模块生成；
- MCP：接入项目外部工具和数据，例如 GitHub、监控平台、设计稿或数据库。
它们不是越多越好。只有当某个流程高频重复、容易出错，或确实依赖外部系统时，才值得沉淀。
八、什么时候才需要任务级 Harness？
下面这些任务通常适合更复杂的任务编排：
- 大规模架构迁移；
- 跨几十个模块的重构；
- 全仓库安全审计；
- 大量 Issue 的自动分类和处理；
- 多方案并行实现与评估；
- 需要独立 Reviewer 交叉验证；
- 工作量无法提前确定，需要循环到没有新问题为止。
普通 Bug 修复、单个功能开发或小规模重构，一般不需要专门创建多 Agent Harness。
子 Agent 会增加 Token 消耗，并行任务也会带来协调和合并成本。任务规模不足时，复杂编排反而可能让开发更慢。
九、如何判断自己需要哪一层？
- 只是修一个 Bug、改一个组件、补一个接口：直接使用 Claude Code 或 Codex 的默认 Harness。
- Agent 经常违反相同的项目规则：补充
CLAUDE.md、AGENTS.md、验证脚本和架构约束。 - 存在高频重复流程：把性能排查、模块生成、PR 审查等流程沉淀成 Skill、脚本或 Hook。
- 任务规模很大，需要拆分和独立复核：再考虑任务级 Harness、动态工作流或自定义多 Agent 编排。
十、总结
Harness 和 Agent Loop 最准确的关系是：
Agent Loop = Agent 的执行循环
Harness = 承载和管理执行循环的完整运行系统
在 Claude Code 和 Codex 的使用场景中：
- 不需要从零实现底层 Agent Loop，产品已经提供了成熟的编码 Agent Harness；
- 正式项目应该建设轻量的项目级 Harness，让项目更容易被理解、操作和验证；
- 复杂任务才需要任务级 Harness，例如多 Agent、Worktree、并行执行和独立复核。
最后用一句话收束：
Claude Code 和 Codex 已经解决了“Agent 如何运行”；项目团队需要解决的是“Agent 如何在这个项目里正确地工作”。
