很多人第一次使用Codex时，会把效果不好归因于模型：

是不是模型还不够强？

于是换更强模型。

提高Reasoning。

重新写Prompt。

但真正长期把Codex放进大型项目以后，会发现一个很反直觉的现象：

模型越强，项目本身的问题反而暴露得越明显。

例如：

Codex找不到正确入口；

不知道怎么启动项目；

不知道测试命令；

改完以后无法验证；

Repository里有三套重复实现；

文档和实际代码已经不一致；

日志只有人看得懂；

CI失败以后不知道下一步做什么。

这些问题继续提高模型能力，并不一定能够彻底解决。

因为Agent缺的不是：

Intelligence。

而是：

Environment。

OpenAI在2026年公开的Harness Engineering实践中就提到，他们尝试用Codex构建一个没有人工直接编写代码的真实产品时，早期瓶颈并不是Codex不会写，而是工程环境本身缺少Agent能够理解和使用的工具、抽象以及反馈机制。工程师的工作因此逐渐从直接写代码，转向设计环境、明确意图并构建反馈循环。

这就是：

Harness Engineering。

---

一、先理解Harness到底是什么

很多人第一次看到Harness Engineering，会以为它只是：

给Codex准备一个AGENTS.md。

实际上远远不止。

可以把Model理解成：

Brain

Agent Runtime负责：

Reason
↓
Tool Call
↓
Observe
↓
Reason Again

而Harness解决的是：

这个Agent进入真实工程以后，靠什么稳定完成工作？

可以简单抽象成：

Model
↓
Agent
↓
Harness
↓
Repository
↓
Verified Result

Harness里面可能包括：

Repository Structure
Build Commands
Test Commands
Lint / Format
AGENTS.md
Skills
CI
Observability
Development Environment
Verification

所以Harness不是某一个文件。

它更像是：

Agent与真实软件工程之间的适配层。

---

二、为什么Agent越强，Harness反而越重要？

早期AI主要生成代码。

开发者负责：

运行；

测试；

发现错误；

继续修改。

因此即使项目比较混乱，人也可以不断补位。

例如AI不知道怎么运行测试。

人自己运行。

AI找错目录。

人告诉它。

AI修改了错误模块。

人手工纠正。

整个结构其实是：

Weak Agent
+
Strong Human Supervision

但Agent越来越自主以后，情况发生变化。

现在一个任务可能是：

修复这个Bug，运行相关测试并确认问题已经解决。

于是Codex要自己：

Find
↓
Understand
↓
Modify
↓
Run
↓
Observe
↓
Verify

人的补位越来越少。

这时候项目里任何模糊的地方都会直接变成：

Agent Failure Point。

所以Agent能力越强，越不能依赖：

人知道应该怎么做。

而必须变成：

Repository自己能够告诉Agent应该怎么做。

---

三、OpenAI为什么先从Repository Scaffold开始？

OpenAI公开的Harness Engineering实践有一个很值得注意的细节：

他们从空Git Repository开始以后，最早搭建的并不只是业务代码，而包括Repository结构、CI配置、格式规则、包管理、应用框架以及AGENTS.md。

为什么？

因为真正让Agent稳定工作的第一步不是：

给它一个Feature。

而是先回答：

代码放哪里？
怎么安装？
怎么启动？
怎么测试？
什么风格才正确？
怎样判断完成？

这些问题如果项目本身没有标准答案，

Agent每一次都会重新猜。

于是同一个任务今天可能生成：

src/services/

明天生成：

src/modules/

后天又生成：

lib/services/

最后Repository越来越乱。

所以Harness Engineering第一层其实是：

Repository Legibility。

让项目结构对机器来说足够清楚。

---

四、第一层：Repository Structure必须让Agent“看得懂”

一个对人还算能用的Repository，不一定适合Agent。

例如：

src/
utils/
common/
shared/
helpers/
misc/

里面到处都有类似功能。

人类老员工可能知道：

新代码其实都应该放shared。

但Agent不知道。

它只看到：

六个似乎都合理的目录。

于是结果很可能是：

选择一个局部看起来最合理的位置。

时间久了就产生Architecture Drift。

所以Agent-friendly Repository最好拥有比较明确的：

Domain Boundary
Module Boundary
Dependency Direction
Naming Convention

Agent看到任务：

给订单系统增加退款状态。

应该能够很快判断：

orders/
↓
refund/
↓
domain/

而不是全Repository搜索半天以后随便选一个位置。

---

五、第二层：所有常用操作都应该有唯一、可靠的命令

这是很多项目最容易忽略的地方。

假设Agent修改完代码以后需要测试。

它可能发现：

README写：

npm test

package.json里还有：

test:unit
test:integration
test:ci

Makefile又有：

make verify

CI实际运行的是：

pnpm test:all

现在问题来了：

到底哪个才是真正的验证命令？

人类开发者可能凭经验知道。

Agent只能自己判断。

所以Harness Engineering很重要的一步是建立：

Canonical Commands。

例如：

./scripts/setup
./scripts/test
./scripts/lint
./scripts/typecheck
./scripts/verify

无论底层技术栈怎么变化，

Agent只需要知道：

verify

就是最终验证入口。

这比给Prompt增加几十行说明稳定得多。

---

六、为什么“命令可执行”比“文档写得详细”更重要？

传统文档可能写：

修改后请运行单元测试、Lint、Type Check，并根据修改模块执行相关Integration Test。

对于人很合理。

但对于Agent来说：

描述仍然存在解释空间。

更好的结构是直接提供：

./scripts/verify-changes

然后脚本负责：

Detect Changed Files
↓
Run Relevant Tests
↓
Lint
↓
Type Check
↓
Report

Agent只需要：

Execute
↓
Observe

这就是一个非常重要的Harness Engineering原则：

能程序化表达的规则，不要只写成自然语言。

因为：

Natural Language是Guidance。

Executable Check才是Enforcement。

---

七、第三层：AGENTS.md负责规则，但不要把整个公司Wiki塞进去

AGENTS.md仍然非常重要。

Codex官方一直建议使用AGENTS.md告诉Agent：

项目结构；

开发规范；

测试方法；

Repository里的特殊规则。

但另一个极端是：

为了让Agent知道更多，写一个两万字AGENTS.md。

最终Agent进入项目第一步就需要读取：

架构历史；

部署说明；

几十条例外规则；

大量并不相关的信息。

结果就是：

Context Noise。

更合理的分层应该是：

AGENTS.md
↓
Stable Rules

例如：

目录边界
核心命令
必须遵守的架构原则
Verification要求

而具体流程可以放进：

Skills

详细背景放进：

docs/

真正需要时再读取。

所以好的Harness不是：

Context越多越好。

而是：

正确的信息在正确时间可被Agent找到。

---

八、第四层：项目必须拥有Golden Path

什么叫Golden Path？

就是：

对常见任务，项目已经定义了推荐做法。

例如新增API。

如果每个开发者都可以自己决定：

Controller怎么写；

Schema放哪里；

Validation怎么做；

测试放哪里；

错误处理怎么做。

Agent也会产生大量差异。

如果项目已经有：

create-endpoint Skill

或者模板：

API Route
↓
Schema
↓
Service
↓
Test
↓
Verification

Agent就不需要从零设计。

这时候任务从：

Design Everything

变成：

Follow Golden Path

Agent稳定性会明显提高。

---

九、模型能力越强，越要减少“不必要的自由度”

这也是一个很反直觉的地方。

很多人认为：

模型越聪明，就应该给它更大自由。

但真实软件工程里：

一致性通常比创造力重要。

比如一个支付系统：

你并不希望Agent每一次增加接口都发明一种新的Architecture。

你更希望：

90%
遵循已有模式

只有真正必要的时候才：

10%
提出新设计

因此Harness很重要的一项工作就是：

Constraint Engineering。

把不需要Agent重新决策的东西固定下来。

例如：

目录
依赖方向
测试标准
错误格式
日志格式
API约定

让模型把推理能力集中到真正困难的问题上。

---

十、第五层：Observability必须让Agent自己看得到

这是很多所谓“Agent-ready项目”最缺的一环。

假设Codex修改一个前端Bug。

它运行项目以后，

页面还是不对。

如果Agent能看到的只有：

Server started successfully

它实际上很难继续。

OpenAI在Harness Engineering实践中专门强化了应用对Agent的可观测性，例如让每个Worktree能够独立启动应用，并让Codex直接读取UI、日志和应用指标，从而自己复现Bug和验证修改。

这意味着Observability不应该只服务：

Human Operator。

还应该服务：

Agent。

---

十一、什么叫Agent-readable Observability？

传统日志：

Something went wrong.

对Agent几乎没有帮助。

更好的日志：

payment_request_failed
order_id=123
provider=stripe
error_code=timeout
retry_count=3

Agent可以继续：

Search
↓
Correlate
↓
Reason

同样，

如果测试只输出：

Test Failed

Agent需要重新调查。

如果输出：

Expected:
status=paid

Actual:
status=pending

Fixture:
order_123

Agent下一步会容易很多。

所以Agent时代的Observability目标应该变成：

让失败状态本身包含下一步分析需要的Context。

---

十二、第六层：Verification必须成为Repository的一等公民

Codex真正进入工程以后，一个非常重要的原则是：

修改不是完成。

应该是：

Change
↓
Verify
↓
Evidence
↓
Done

Codex本身也一直强调通过测试输出、终端日志等可验证证据帮助用户检查Agent完成的工作。

所以项目应该尽量让Agent能够回答：

修改了什么？
为什么？
运行了什么验证？
结果是什么？
还有什么没验证？

如果一个项目根本没有可靠测试，

Agent再强也只能：

Reason

而不能真正：

Prove

---

十三、没有Verification，Agent越快反而可能越危险

假设过去一个开发者一天修改：

3个PR

即使验证体系一般，

人的速度本身限制了风险扩散。

Agent出现以后，

理论上可以同时生成：

10
20
50

个修改。

这时候如果没有自动验证，

问题会迅速变成：

Code Throughput ↑
↓
Review Load ↑
↓
Human Bottleneck ↑

所以模型速度越快，

测试、CI和Verification的重要性反而越高。

这也是为什么OpenAI自己的Agent-first实践里，会不断把Review、测试以及反馈循环进一步交给Agent和自动化系统处理。

---

十四、第七层：失败以后，不要先修改Prompt，先问Harness缺了什么

这是Harness Engineering最值得建立的思维。

假设Codex连续三次把文件放错目录。

传统解决方法：

在Prompt里强调：“一定要放到正确目录。”

但真正应该问：

为什么Agent无法确定正确目录？

可能真正的问题是：

Repository有多个相似目录。

没有架构文档。

没有Boundary Check。

没有Lint Rule。

于是更长期的解决办法应该是：

Clarify Structure
+
Document Rule
+
Add Enforcement

而不是：

Prompt再强调一次

OpenAI在自己的实践中也提到，当Agent失败时，他们更关注“缺失的能力是什么，以及怎样让这个能力对Agent可理解、可执行”，而不是简单让Codex再试一次。

这正是Harness Engineering和Prompt Engineering最大的差别。

---

十五、Prompt Fix和Harness Fix有什么区别？

例如Agent总忘记运行测试。

Prompt Fix

每次写：

IMPORTANT：
修改完成以后一定运行测试。

下一次任务还需要继续写。

---

Harness Fix

在AGENTS.md规定：

所有代码修改必须运行 ./scripts/verify

再让：

CI

强制执行。

结果变成：

Rule
+
Executable Check
+
Feedback

现在这条能力已经属于：

Repository。

不再属于某一次Prompt。

这就是Harness的复利。

---

十六、Agent-friendly项目应该让错误“可恢复”

真正成熟的Harness不只是帮助Agent成功。

还要帮助Agent：

失败以后知道怎么办。

例如：

npm test

失败以后只输出：

Exit Code 1

Agent只能自己搜索。

更好的测试Harness应该输出：

Failing Suite
Affected Module
Expected
Actual
Suggested Debug Command

于是Agent Loop变成：

Action
↓
Failure
↓
Structured Feedback
↓
Reason
↓
Retry

这就是：

Feedback Loop。

没有反馈循环，

Agent只是不断执行。

有反馈循环，

Agent才能持续修正。

---

十七、Harness Engineering本质上是在缩短Agent的搜索空间

可以从另一个角度理解。

假设一个任务理论上存在100种实现方式。

Agent需要：

Search 100 Paths

如果Repository已经提供：

明确架构；

模板；

Golden Path；

验证规则。

可能只剩：

5 Reasonable Paths

模型不需要变聪明。

任务就已经明显变容易。

所以Harness真正做的是：

Reduce Ambiguity
↓
Reduce Search Space
↓
Increase Reliability

这也是为什么同一个Codex，在不同项目里表现可能差距非常大。

问题不一定是模型变化。

而是：

Environment Quality不同。

---

十八、一个简单的Agent-ready Repository可以长什么样？

不一定要搞得特别复杂。

最小结构可以类似：

repo/
│
├── AGENTS.md
│
├── README.md
│
├── docs/
│   ├── architecture.md
│   └── testing.md
│
├── scripts/
│   ├── setup
│   ├── test
│   └── verify
│
├── src/
│
└── tests/

AGENTS.md告诉Agent：

项目怎么工作
↓
哪些规则不能违反
↓
应该执行什么命令

scripts提供：

Executable Interface

docs提供：

On-demand Context

tests提供：

Verification

整个Repository就开始拥有：

Machine Legibility。

---

十九、怎么判断自己的项目Harness够不够好？

可以做一个很简单的测试：

把一个新Agent放进Repository。

只告诉它：

修复Issue #123并验证结果。

然后观察它在哪些地方需要问人。

例如：

不知道怎么启动

说明：

Environment Harness缺失。

不知道改哪个模块

说明：

Architecture Legibility不足。

不知道跑什么测试

说明：

Verification Interface缺失。

改完无法复现UI

说明：

Observability不足。

每次实现方式完全不同

说明：

Golden Path不足。

所以：

Agent需要反复问人的地方，就是Harness下一步应该建设的地方。

---

二十、一套可以直接使用的Harness Engineering检查表

1. Repository Structure

目录和模块边界是否足够清晰？

2. Setup

新Workspace能不能一条命令启动？

3. Canonical Commands

Build、Test、Lint、Verify有没有唯一入口？

4. Instructions

AGENTS.md是否只保留稳定、高价值规则？

5. Golden Path

常见开发任务有没有标准模式？

6. Observability

Agent能不能直接看到日志、UI和错误状态？

7. Verification

修改以后能不能程序化判断是否正确？

8. Feedback Loop

失败以后是否提供足够信息继续修复？

最后形成：

Intent
↓
Repository Context
↓
Golden Path
↓
Execution
↓
Observability
↓
Verification
↓
Feedback
↓
Verified Result

这才是一套真正适合Agent工作的工程Harness。

---

最后

Codex能力越来越强以后，一个很容易出现的误区是：

等下一代模型更强，Agent自然就会更稳定。

但真正进入大型工程以后，会发现模型只解决其中一部分问题。

模型可以帮助：

推理；

理解；

生成；

规划。

但项目本身仍然需要告诉Agent：

Where
How
Rules
Tools
Verification

所以Agent时代的软件工程正在出现一个很重要的变化：

过去工程师主要优化：

Code。

现在还需要优化：

Environment for Agents。

也就是说：

Better Model
+
Better Harness
=
Better Engineering Agent

而不是：

Better Model
=
Everything Solved

这也是Harness Engineering真正值得关注的地方。

它不是为了让项目“更适合AI”。

而是在Agent开始真正承担工程执行以后，把那些过去只存在于：

老员工经验；

隐性规则；

人工判断；

口头约定

里的东西，

逐渐变成：

Readable
Executable
Verifiable
Enforceable

的工程基础设施。

当Repository做到这一点以后，

Codex才真正从：

一个会写代码的Agent

变成：

一个能够在项目里持续可靠工作的工程执行者。

持续更新Codex、大模型开发相关技术内容。

长期使用各类代码大模型，整理了稳定的AI会员订阅渠道。