ChatGPT、Codex实战：Agent写代码越来越强，为什么项目本身反而要先做好Harness Engineering？

很多人第一次使用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理解成BrainAgent Runtime负责Reason ↓ Tool Call ↓ Observe ↓ Reason Again而Harness解决的是这个Agent进入真实工程以后靠什么稳定完成工作可以简单抽象成Model ↓ Agent ↓ Harness ↓ Repository ↓ Verified ResultHarness里面可能包括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 ConventionAgent看到任务给订单系统增加退款状态。应该能够很快判断orders/ ↓ refund/ ↓ domain/而不是全Repository搜索半天以后随便选一个位置。五、第二层所有常用操作都应该有唯一、可靠的命令这是很多项目最容易忽略的地方。假设Agent修改完代码以后需要测试。它可能发现README写npm testpackage.json里还有test:unit test:integration test:ciMakefile又有make verifyCI实际运行的是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 ↓ ReportAgent只需要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 ↓ VerificationAgent就不需要从零设计。这时候任务从Design Everything变成Follow Golden PathAgent稳定性会明显提高。九、模型能力越强越要减少“不必要的自由度”这也是一个很反直觉的地方。很多人认为模型越聪明就应该给它更大自由。但真实软件工程里一致性通常比创造力重要。比如一个支付系统你并不希望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_id123 providerstripe error_codetimeout retry_count3Agent可以继续Search ↓ Correlate ↓ Reason同样如果测试只输出Test FailedAgent需要重新调查。如果输出Expected: statuspaid Actual: statuspending Fixture: order_123Agent下一步会容易很多。所以Agent时代的Observability目标应该变成让失败状态本身包含下一步分析需要的Context。十二、第六层Verification必须成为Repository的一等公民Codex真正进入工程以后一个非常重要的原则是修改不是完成。应该是Change ↓ Verify ↓ Evidence ↓ DoneCodex本身也一直强调通过测试输出、终端日志等可验证证据帮助用户检查Agent完成的工作。所以项目应该尽量让Agent能够回答修改了什么 为什么 运行了什么验证 结果是什么 还有什么没验证如果一个项目根本没有可靠测试Agent再强也只能Reason而不能真正Prove十三、没有VerificationAgent越快反而可能越危险假设过去一个开发者一天修改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 1Agent只能自己搜索。更好的测试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 Interfacedocs提供On-demand Contexttests提供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 CommandsBuild、Test、Lint、Verify有没有唯一入口4. InstructionsAGENTS.md是否只保留稳定、高价值规则5. Golden Path常见开发任务有没有标准模式6. ObservabilityAgent能不能直接看到日志、UI和错误状态7. Verification修改以后能不能程序化判断是否正确8. Feedback Loop失败以后是否提供足够信息继续修复最后形成Intent ↓ Repository Context ↓ Golden Path ↓ Execution ↓ Observability ↓ Verification ↓ Feedback ↓ Verified Result这才是一套真正适合Agent工作的工程Harness。最后Codex能力越来越强以后一个很容易出现的误区是等下一代模型更强Agent自然就会更稳定。但真正进入大型工程以后会发现模型只解决其中一部分问题。模型可以帮助推理理解生成规划。但项目本身仍然需要告诉AgentWhere 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会员订阅渠道。