Claude Code / Codex 已经有 Harness，项目里还需要自己搭吗？

使用 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 如何在这个项目里正确地工作"。

参考资料

• OpenAI：Unrolling the Codex agent loop
• OpenAI：Unlocking the Codex harness
• Anthropic：A harness for every task --- dynamic workflows in Claude Code
• 原文：Harness、Agent Loop 与项目级 Harness