介绍

过去使用 AI 编程工具时，常见流程是：输入 Prompt，得到一段代码，再由程序员手动寻找文件、修改代码、运行测试和处理错误。

Claude Code、OpenAI Codex 等 Coding Agent 已经不再只是“生成代码”。它们可以进入真实项目，读取仓库上下文，搜索和修改文件，执行 Shell 命令，调用外部工具，运行测试，并根据执行结果继续调整。

这种变化的关键，不是模型单独变得更聪明，而是模型被放进了一个能够持续行动的工程环境中。这个环境通常包含两部分：

Agent Loop：负责规划、执行、观察、反思和重复；
Agent Harness：负责提供上下文、工具、规则、权限、状态和验证机制。

本文不再完整重复前面文章中的 Harness 理论和实现代码，而是聚焦两个具有代表性的智能体编程工具：Claude Code 和 Codex，说明它们如何通过 Harness 支持真实的软件开发。

需要先澄清一个容易混淆的说法：

Agent Loop 是运行机制，Agent Harness 是承载这个运行机制的工程环境。Claude Code 和 Codex 通常同时包含两者，而不是先运行一个独立的 Harness Agent，再调用另一个 Loop Agent。

一、Agent Loop 与 Agent Harness

1. 从“回答问题”到“完成任务”

传统 AI 的典型过程是：

1	Prompt → Answer

Coding Agent 的过程更接近：

1	Goal → Plan → Act → Observe → Verify → Repeat

例如，用户提出“为测试平台增加 AI 测试用例生成功能”，Agent 需要完成的并不是生成一段孤立代码，而是：

理解需求和项目约束；
找到相关模块、接口和测试；
制定修改计划；
修改代码和配置；
运行测试、构建或浏览器验证；
根据失败结果继续修复；
输出 Diff、验证结果和遗留风险。

2. Agent Loop：让任务持续推进

Agent Loop 可以简化为下面几个阶段：

阶段	Agent 需要回答的问题	编程任务中的典型动作
Goal	最终要完成什么？	新增功能、修复 Bug、完成重构
Plan	应该分几步完成？	找入口、读测试、确定修改范围
Act	现在执行什么动作？	读写文件、运行命令、调用 MCP
Observe	动作产生了什么结果？	读取命令输出、日志、页面和 Git Diff
Reflect	下一步如何调整？	修复错误、补充上下文、重新测试
Done	是否满足验收标准？	测试通过、构建成功、结果可审查

一次用户请求通常会触发多轮模型和工具交互：

模型提出工具调用
    ↓
Harness 执行工具
    ↓
工具结果返回上下文
    ↓
模型继续判断下一步
    ↓
直到完成或达到停止条件

因此，Agent Loop 解决的是“如何持续执行”，但它本身并不知道项目结构、测试命令和权限边界。这些内容需要由 Harness 提供。

3. Agent Harness：为 Loop 提供工程环境

Agent Harness 可以理解为围绕模型和 Agent Loop 构建的一套运行时。它至少需要解决六类问题：

Harness 能力	作用	常见载体
Context / Rules	让 Agent 理解项目和必须遵守的约束	`CLAUDE.md`、`AGENTS.md`、项目文档、Rules
Tools / MCP	让 Agent 能够读取、修改、执行和访问外部系统	文件工具、Shell、Git、MCP Server
Skills	为重复任务提供稳定的专业工作流	代码审查、测试、发布、数据库迁移
Permissions / Sandbox	限制文件、命令、网络和高风险操作	权限策略、沙箱、审批机制
Hooks	将确定性检查变成自动动作	格式化、静态检查、危险命令拦截
Git / Tests / Evals	保存状态并提供外部完成证据	Git Diff、测试、构建、浏览器和日志

可以把它们类比为：

Model 是大脑；
Agent Loop 是心跳；
Tools 是手和脚；
Skills 是工作手册；
Harness 是工作环境和操作系统；
Tests / Evals 是验收机制。

4. MCP 与 Skills 不要混淆

MCP 和 Skill 经常同时出现，但解决的问题不同：

概念	解决的问题	示例
MCP	Agent 可以调用什么能力？	GitHub、Linear、PostgreSQL、Playwright、Sentry
Skill	Agent 应该如何完成某类任务？	测试设计、代码审查、前端开发、数据库迁移

例如实现一个登录功能：

Playwright MCP 可以打开浏览器、填写表单、读取页面结果；
testing Skill 可以规定需要覆盖成功、错误密码、空密码和锁定用户；
Harness 负责控制权限、执行工具并把结果交回 Agent Loop。

一句话总结：

MCP 提供能力，Skill 提供方法，Harness 将它们组织到可持续、可验证的执行循环中。

二、Claude Code：面向项目开发的 Agent Harness

1. Claude Code 的定位

Claude Code 是面向软件开发的 Coding Agent。它将模型与项目上下文、文件操作、Shell、Git、MCP、Skills、Hooks、权限和子智能体组合起来，在真实仓库中持续完成工程任务。

因此，Claude Code 不应只被理解为“终端中的代码生成工具”，而应理解为：

一个以项目目录为工作空间、以 Harness 为运行环境、以 Agent Loop 为执行方式的 Coding Agent。

2. 项目配置结构

一个典型项目可以这样组织：

project/
├─ CLAUDE.md                    # 项目上下文与长期规则
├─ .mcp.json                    # 项目级 MCP Server 配置
├─ .claude/
│  ├─ settings.json             # 团队共享配置、权限和 Hooks
│  ├─ settings.local.json       # 本机配置，通常不提交
│  ├─ rules/                    # 路径级或技术栈规则
│  ├─ skills/                   # 可复用工作流
│  │  └─ <skill-name>/
│  │     ├─ SKILL.md
│  │     ├─ references/
│  │     └─ scripts/
│  └─ agents/                   # 自定义 Subagent
├─ src/
├─ tests/
├─ docs/
└─ .git/

不同配置的职责可以概括为：

配置	主要职责	适合存放的内容
`CLAUDE.md`	项目导航和长期上下文	项目目标、架构入口、常用命令、开发约定
`.claude/rules/`	细粒度规则	前端、后端、数据库、测试或目录级规范
`.claude/skills/`	可复用专业流程	代码审查、测试、发布、数据库迁移
`.claude/agents/`	专项子智能体	`code-reviewer`、`test-engineer`
`.mcp.json`	外部工具和数据	GitHub、Linear、Playwright、数据库
`settings.json`	行为控制	权限、Hooks、工具策略和项目设置

3. `CLAUDE.md`：项目的入口文件

CLAUDE.md 不是一次对话中的临时 Prompt，而是项目级的持久上下文入口。它应该帮助 Claude Code 快速建立项目地图，而不是承载所有项目知识。

一个精简示例：

# AI Test Platform

## Project Structure

- frontend/：React + TypeScript 前端
- backend/：Python API
- tests/：自动化测试
- docs/：架构与产品文档

## Development Commands

- 前端检查：pnpm lint && pnpm typecheck
- 前端测试：pnpm test
- 后端测试：pytest

## Working Agreements

- 修改前先读取相关实现和测试
- 优先复用已有组件和服务
- API 变更必须补充测试
- 未运行验证时不能声称任务完成

详细的架构说明、测试策略和安全约束应放在 docs/ 中，再由 CLAUDE.md 负责导航。这样既能减少入口文件膨胀，也能让 Agent 在需要时读取更完整的资料。

4. Skills、MCP 与控制机制

Claude Code 中的几个扩展机制可以这样理解：

机制	适合解决的问题	使用建议
Rules	项目必须遵守的长期约束	放稳定规则，不要写临时任务要求
Skills	重复出现的专业工作流	用 `SKILL.md` 描述步骤、检查项和辅助资源
MCP	访问外部系统和数据	明确凭据来源、读写权限和不可信输出
Hooks	必须自动执行的确定性动作	格式化、静态检查、危险操作拦截
Permissions	控制哪些动作需要确认或拒绝	保护密钥、生产数据、删除和发布操作
Subagent	隔离上下文或处理独立任务	适合探索、测试分析和专项 Review

一个简单的判断原则是：

会被多个任务重复使用的步骤，沉淀为 Skill；
必须执行且不能依赖模型记忆的检查，使用 Hook 或 CI；
涉及外部系统的能力，使用 MCP；
可能造成不可逆影响的动作，放入权限和审批边界。

5. 一次典型的 Claude Code 开发任务

不要只输入：

1	帮我实现一个测试用例列表页。

更好的任务输入应该明确目标、范围、约束和验收标准：

任务：为测试平台增加测试用例列表页。

范围：
- frontend/src/pages/test-cases/
- frontend/src/components/
- 相关测试文件

约束：
- 先读取 CLAUDE.md 和前端 Rules
- 优先复用已有组件
- 不修改后端 API

验收标准：
- 支持分页、状态筛选和关键字搜索
- 覆盖加载、空数据和错误状态
- lint、typecheck 和相关测试通过

执行方式：
先探索项目并给出计划，确认修改范围后再实施。

一次完整的开发过程通常是：

读取 CLAUDE.md / Rules
    ↓
探索代码、测试和 Git 状态
    ↓
输出计划并确认范围
    ↓
调用 Skill / MCP，修改代码
    ↓
运行测试、构建或浏览器验证
    ↓
根据反馈修复
    ↓
检查 Git Diff 并汇报结果

Claude Code 的核心价值不在于一次生成多少代码，而在于它可以把项目上下文、工具调用和验证过程组织成连续的开发闭环。

三、OpenAI Codex：共享 Harness 驱动的 Coding Agent

1. Codex 的定位

Codex 是 OpenAI 面向软件开发的 Coding Agent，可以从 CLI、IDE、桌面应用或云端任务等不同入口接收工作。入口虽然不同，但核心仍然是：

1	项目上下文 + Agent Loop + 工具调用 + 权限控制 + 验证反馈

Codex 的一个重要特点是，项目规则、运行配置、Skills、MCP 和沙箱策略共同决定了 Agent 的实际工作边界。

2. 项目配置结构

一个典型项目可以这样组织：

project/
├─ AGENTS.md                    # 仓库级长期规则和项目入口
├─ .codex/
│  ├─ config.toml               # 项目级运行配置
│  ├─ hooks.json                # 可选：生命周期 Hooks
│  └─ agents/                   # 可选：项目级自定义 Agent
│     ├─ reviewer.toml
│     └─ test-engineer.toml
├─ .agents/
│  └─ skills/                   # 仓库级 Skills
│     ├─ frontend-design/
│     │  └─ SKILL.md
│     ├─ testing/
│     │  └─ SKILL.md
│     └─ database-design/
│        └─ SKILL.md
├─ frontend/
├─ backend/
├─ tests/
├─ docs/
└─ .git/

Codex 的用户级配置通常位于 ~/.codex/，项目级配置位于项目目录下。项目配置涉及权限和命令执行时，应确认项目处于可信状态，避免陌生仓库自动加载高权限配置。

3. `AGENTS.md`：仓库规则的入口

AGENTS.md 适合存放稳定、长期、每次任务都应该知道的信息。复杂流程可以放进 Skill，详细设计可以放进 docs/。

一个精简示例：

# AI Test Platform

## Project Structure

- frontend/：React + TypeScript
- backend/：Python API
- tests/：自动化测试
- docs/：架构和产品文档

## Development Rules

- 修改前先搜索现有实现和测试
- 优先复用已有模块
- API 变更必须更新测试
- 不在未经授权时执行 git push 或部署

## Verification

- 前端：pnpm lint、pnpm typecheck、pnpm test
- 后端：pytest
- 最终输出修改文件、验证结果和剩余风险

如果项目存在多级 AGENTS.md，可以让靠近当前工作目录的规则负责更具体的约束，而仓库根目录的文件负责全局导航和通用约定。

4. `config.toml`：配置运行环境

项目级 config.toml 可以用于表达默认模型、推理强度、沙箱、审批、MCP、Hooks 和其他运行选项。下面只展示结构，不代表可以直接复制使用：

# project/.codex/config.toml

approval_policy = "on-request"
sandbox_mode = "workspace-write"

[mcp_servers.github]
command = "your-github-mcp-command"
args = []

[mcp_servers.playwright]
command = "your-playwright-mcp-command"
args = []

MCP Server 的命令、认证方式和凭据应根据实际环境配置，不要把 Token 直接写入仓库。

5. Skills、MCP、Sandbox 与 Subagents

Codex 的能力可以按下面的方式划分：

机制	主要作用	典型内容
`AGENTS.md`	提供仓库规则和导航	目录结构、开发命令、完成标准
`.agents/skills/`	提供专业任务流程	测试、前端、数据库、代码审查
MCP Server	连接外部工具和上下文	GitHub、浏览器、数据库、内部 API
Sandbox	限制命令的文件和网络访问	工作区边界、网络策略、环境变量
Approvals	控制高风险操作是否需要确认	写出工作区、危险命令、外部写操作
Hooks	执行生命周期检查	格式化、审计、策略检查、通知
Subagents / Worktrees	隔离上下文和并行修改	探索、测试分析、独立模块开发

Sandbox 的目标不是让 Agent 无法工作，而是控制失败时的影响范围；Approvals 则决定哪些行为需要暂停并询问用户。

对于多个会写代码的并行任务，应使用 Worktree 或其他工作区隔离方式，避免多个 Agent 同时修改同一文件。

6. 一次典型的 Codex 开发任务

一个适合 Codex 的任务输入可以写成：

请先读取 AGENTS.md，并按照其中的导航查看相关文档。

任务：为测试平台新增 AI 测试用例生成接口。

范围：
- backend/app/api/
- backend/app/services/
- tests/api/

要求：
- 先探索现有 API 和测试结构
- 输出实现计划后再修改
- 优先复用已有模型和错误处理
- 不修改数据库结构

验收标准：
- 新接口测试通过
- 原有 API 测试不回归
- 输出 git diff 摘要
- 无法完成的验证必须明确说明原因

一次完整的 Codex Loop 可以概括为：

读取 AGENTS.md 和相关 Skills
    ↓
探索代码、测试、配置和 Git 状态
    ↓
确认权限和执行范围
    ↓
调用工具并修改代码
    ↓
运行测试或其他验证
    ↓
根据反馈继续修复
    ↓
输出 Diff、测试结果和剩余风险

Codex Harness 的重点不是某一个配置文件，而是将规则、工具、权限、状态和反馈组织成一个可以持续运行的工程过程。

四、Claude Code 与 Codex 的差异

Claude Code 和 Codex 都属于 Coding Agent / Agent Harness。它们的共同点比差异更重要：都需要项目上下文、工具能力、权限边界、验证反馈和可恢复的任务状态。

能力	Claude Code	OpenAI Codex
项目长期规则	`CLAUDE.md`	`AGENTS.md`
项目配置	`.claude/settings.json` 等	`.codex/config.toml` 等
仓库级 Skills	`.claude/skills/`	`.agents/skills/`
MCP 配置	常见项目配置为 `.mcp.json`	常见配置在 `config.toml`
Hooks	生命周期 Hooks	`hooks.json` 或配置中的 Hooks
子智能体	`.claude/agents/` 等	`.codex/agents/` 等
权限控制	Permissions、Hooks 等	Sandbox、Approvals、Permissions、Hooks
并行和隔离	Subagents、团队或会话能力	Subagents、Tasks、Worktrees
主要入口	以终端和项目工作流为核心	CLI、IDE、桌面和云端等多种入口

选择工具时，不应只比较一次代码生成效果，更应该比较：

团队当前习惯的开发入口；
项目规则和 Skills 是否容易维护；
MCP 是否能连接已有工作流；
权限、审批和沙箱是否符合安全要求；
长任务是否容易恢复、并行和审查；
测试、浏览器、日志和 CI 是否能够进入反馈闭环。

所以工具选择的重点不是“谁生成代码更快”，而是：

谁更容易被项目约束、被测试验证，并稳定地完成端到端任务。

五、Claude Code 与 Codex 如何共存

如果一个项目同时使用 Claude Code 和 Codex，最重要的不是让两套配置完全相同，而是让两种工具读取同一套项目事实。

1. 共享项目事实

建议将稳定内容放到 docs/：

docs/
├─ architecture.md    # 架构和模块边界
├─ development.md     # 开发、构建和发布流程
├─ testing.md         # 测试策略和验证命令
└─ security.md        # 安全约束和敏感操作

这些文档是项目的事实来源，不应该因为更换 Agent 工具而改变。

2. 分离工具入口

工具相关的配置分别保留：

project/
├─ CLAUDE.md          # Claude Code 入口
├─ AGENTS.md          # Codex 入口
├─ .claude/           # Claude Code 配置
├─ .codex/            # Codex 配置
├─ .agents/skills/    # Codex Skills
├─ docs/              # 两种工具共享的项目事实
├─ src/
├─ tests/
└─ .git/

CLAUDE.md 和 AGENTS.md 不需要复制所有项目知识，只需要完成三件事：

指向共享文档；
说明当前工具的使用约定；
指定常用验证命令和完成标准。

3. 统一验收标准

无论使用哪一种工具，项目的“完成”都应该由同一套证据定义：

前端：lint、typecheck、单元测试和 E2E；
后端：lint、typecheck 和 pytest；
项目：构建、必要的安全检查和 Git Diff Review。

工具入口可以不同，但项目事实、测试命令和验收标准必须尽量一致。

六、Harness Agent 的通用使用方法

1. 把任务写成可执行的规格

模糊指令：

帮我实现登录功能。

结构化指令：

目标：增加邮箱密码登录。
范围：frontend/auth、backend/auth 和相关测试。
约束：不修改现有用户表结构，不引入新的认证依赖。
验收：覆盖登录成功、错误密码、空密码和锁定用户。
流程：先探索现有实现并输出计划，再开始修改。

可以使用下面这个通用模板：

目标：
范围：
约束：
验收标准：
验证命令：
执行方式：先探索和规划，再修改代码

2. 让 Agent 先理解项目，再开始修改

复杂任务开始前，先让 Agent 回答：

相关模块和入口在哪里？
当前实现和测试是什么？
准备修改哪些文件？
有哪些潜在风险？
需要运行哪些验证？

这一步可以减少两类常见问题：一是没有理解现有架构就重复实现，二是修改范围不断扩大。

3. 把稳定规则写入 Harness

需要沉淀的内容	建议位置
长期项目规则	`CLAUDE.md` / `AGENTS.md`
路径或技术栈规则	Rules / 分层 `AGENTS.md`
重复工作流	Skills
外部工具	MCP
必须执行的检查	Hooks / CI
高风险操作	Permissions / Sandbox / Approvals

不要把每次任务都重复写进 Prompt，也不要把所有知识都堆进一个入口文件。好的 Harness 应该让正确路径更容易被 Agent 发现，让危险路径更难被误用。

4. 用外部反馈判断是否完成

Agent 回复“已经完成”并不等于任务完成。至少应该检查：

测试和构建结果；
浏览器、日志或运行时结果；
Git Diff 是否符合预期；
是否修改了范围外文件；
是否存在未完成事项和剩余风险。

更合理的协作方式不是把软件工程完全交给 Agent，而是：

人负责目标、优先级、权限和最终判断；Agent 负责在约束范围内探索、执行、验证和修复。

总结

Claude Code 和 Codex 的意义，不只是让模型生成更多代码，而是把模型放进真实的软件工程环境中。

这个环境由几类能力共同组成：

Context 与 Rules，让 Agent 理解项目；
Tools 与 MCP，让 Agent 能够行动；
Skills，让重复任务变成专业工作流；
Permissions、Sandbox 与 Hooks，限制危险行为；
Git、Tests、Logs 和 Review，提供外部完成证据。

Agent Loop 负责持续运行：

1	Plan → Act → Observe → Reflect → Repeat

Agent Harness 负责让这个循环能够安全、稳定、可验证地发生：

因此，更准确的理解不是：

1	Claude Code / Codex = 更强的代码生成器

而是：

Claude Code / Codex
= Model
+ Agent Loop
+ Project Context
+ Tools / MCP
+ Skills
+ Permissions
+ Verification

Harness Engineering 的核心思想也可以归纳为一句话：

不要只思考如何让模型生成代码，而要设计一个让 Agent 能够理解项目、执行任务、验证结果并持续改进的工程环境。

Jean's Blog

基于 Agent Harness 的智能体编程工具：Claude Code 与 Codex

介绍

一、Agent Loop 与 Agent Harness

1. 从“回答问题”到“完成任务”

2. Agent Loop：让任务持续推进

3. Agent Harness：为 Loop 提供工程环境

4. MCP 与 Skills 不要混淆

二、Claude Code：面向项目开发的 Agent Harness

1. Claude Code 的定位

2. 项目配置结构

3. `CLAUDE.md`：项目的入口文件

4. Skills、MCP 与控制机制

5. 一次典型的 Claude Code 开发任务

三、OpenAI Codex：共享 Harness 驱动的 Coding Agent

1. Codex 的定位

2. 项目配置结构

3. `AGENTS.md`：仓库规则的入口

4. `config.toml`：配置运行环境

5. Skills、MCP、Sandbox 与 Subagents

6. 一次典型的 Codex 开发任务

四、Claude Code 与 Codex 的差异

五、Claude Code 与 Codex 如何共存

1. 共享项目事实

2. 分离工具入口

3. 统一验收标准

六、Harness Agent 的通用使用方法

1. 把任务写成可执行的规格

2. 让 Agent 先理解项目，再开始修改

3. 把稳定规则写入 Harness

4. 用外部反馈判断是否完成

总结

参考资料

介绍

一、Agent Loop 与 Agent Harness

1. 从“回答问题”到“完成任务”

2. Agent Loop：让任务持续推进

3. Agent Harness：为 Loop 提供工程环境

4. MCP 与 Skills 不要混淆

二、Claude Code：面向项目开发的 Agent Harness

1. Claude Code 的定位

2. 项目配置结构

3. CLAUDE.md：项目的入口文件

4. Skills、MCP 与控制机制

5. 一次典型的 Claude Code 开发任务

三、OpenAI Codex：共享 Harness 驱动的 Coding Agent

1. Codex 的定位

2. 项目配置结构

3. AGENTS.md：仓库规则的入口

4. config.toml：配置运行环境

5. Skills、MCP、Sandbox 与 Subagents

6. 一次典型的 Codex 开发任务

四、Claude Code 与 Codex 的差异

五、Claude Code 与 Codex 如何共存

1. 共享项目事实

2. 分离工具入口

3. 统一验收标准

六、Harness Agent 的通用使用方法

1. 把任务写成可执行的规格

2. 让 Agent 先理解项目，再开始修改

3. 把稳定规则写入 Harness

4. 用外部反馈判断是否完成

总结

参考资料

3. `CLAUDE.md`：项目的入口文件

3. `AGENTS.md`：仓库规则的入口

4. `config.toml`：配置运行环境