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

先直接说几个核心判断：

• Agent Loop 就是 Agent 不断“推理 → 行动 → 观察 → 再推理”的执行循环。
• Harness 是承载、约束并扩展这个循环的完整运行系统。
• Claude Code 和 Codex 已经提供了产品级 Harness，日常开发不需要重新实现底层循环。
• 项目团队真正值得建设的，是一套轻量的项目级 Harness：明确规则、架构边界、运行方式和验收标准，让 Agent 在你的项目里正确工作。

一、Agent Loop：Agent 如何一步步完成任务

Agent Loop 要回答的核心问题是：Agent 如何一步步完成任务？

一个最简化的循环可以这样表示：

读取用户目标
    ↓
模型分析并决定下一步
    ↓
调用工具
    ↓
执行操作并获得结果
    ↓
将结果放回上下文
    ↓
继续分析，直到任务完成

伪代码大致如下：

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 在什么环境和规则下运行？

一个典型的 Harness 可能包含：

Harness
├─ Agent Loop
├─ 模型调用与模型选择
├─ Prompt / 上下文构造
├─ 工具注册与执行
├─ 文件系统和 Shell
├─ 权限审批与沙箱
├─ 会话状态持久化
├─ 上下文压缩
├─ 超时、重试和预算控制
├─ 日志与可观测性
├─ MCP / Skills / Hooks
└─ 子 Agent 与任务编排

业界对 Harness 的边界没有完全统一。这里采用一个较宽泛的工程定义：Harness 是 Agent 的完整运行系统，包含 Agent Loop 以及所有支撑它的基础设施。

三、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

面向大规模迁移、安全审计、复杂研究和多方案验证等任务，临时负责拆分、并行执行、独立复核和结果汇总。

举个例子：

规划 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
- A void 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、并行执行和独立复核。

最后用一句话收束：

而最需要投入精力建设的，是让 Agent 在项目里正确工作的那个“项目级 Harness”。

参考资料

• 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