AI 会写代码了，为什么项目还是会越做越乱？

AI 会写代码了，为什么项目还是会越做越乱？

——我对 Harness Engineering 的第一次理解

最近我一直在用 AI 开发自己的项目。

一开始，我关注的事情和很多人差不多：

• 哪个模型写代码更强？
• Codex、OpenCode、Claude Code、DeepSeek 到底谁更适合开发？
• Prompt 应该怎么写，才能让 AI 一次性把功能做对？

但随着项目代码越来越多，我慢慢发现了一个比“模型够不够聪明”更麻烦的问题：

AI 很会写代码，但“会写代码”不等于“会长期维护一个越来越复杂的工程”。

这也是我读 OpenAI《Harness Engineering》之后，最大的认知变化。

---

1. 功能写出来，不代表系统真的变好了

假设我正在开发一个 Agent。

今天让 AI 做 Graph。

完成了。

明天让 AI 做 Evidence。

也完成了。

后天继续做 Hypothesis、ActionTrace、Tool Registry。

每个模块单独看都没有问题，测试甚至可能全部通过。

但放到一起以后，可能变成这样：

工具发现一个资产
↓
Evidence 记录了

但是 Graph 不知道

Graph 里出现了 Endpoint
↓
Hypothesis 没有消费

Hypothesis 产生了判断
↓
Planner 又完全没看到

这时候就会出现一种非常危险的错觉：

功能越来越多
≠
系统越来越完整

有时候甚至恰恰相反。

功能越多，模块之间的关系越复杂，AI 越容易写出“局部正确、整体脱节”的代码。

所以后来我开始刻意区分两个词：

implemented

和：

integrated

前者表示：

代码写出来了。

后者才表示：

这个能力真的进入了系统主流程，并且上下游都能消费它。

---

2. OpenAI 做了一个很极端的实验

OpenAI 在《Harness Engineering》里介绍了一个实验：

他们从一个空 Git 仓库开始，让 Codex 构建一款真实的软件产品。

五个月后，这个仓库已经达到大约一百万行代码，期间大约打开并合并了 1500 个 Pull Request。应用逻辑、测试、CI、文档、可观测性、内部开发工具等，都由 Codex 编写。人类工程师主要负责方向、环境、意图和反馈机制。

真正让我注意的不是“一百万行代码”这个数字。

而是 OpenAI 后面总结出来的一句话：

早期进展比预期慢，并不是因为 Codex 没有能力，而是因为环境规范不够明确，缺少完成高级目标所需要的工具、抽象层和内部结构。

这句话对我冲击很大。

因为以前 AI 做不好时，我第一反应往往是：

是不是 Prompt 不够详细？

于是继续补：

请仔细一点。
请不要破坏已有功能。
请遵循项目架构。
完成以后请测试。

但现在回头看，这些很多时候只是在“提醒模型”。

并没有真正解决能力缺口。

---

3. Prompt 和 Harness 的区别

假设你让 Agent：

修改页面以后记得检查 UI。

如果 Agent 根本不能打开浏览器，也不能读取 DOM，不能截图，那这句话没有意义。

这不是“模型不听话”。

而是：

Agent 根本没有验证 UI 的能力。

这时候正确解决方案不是：

把 Prompt 写得更严厉。

而是补：

Browser
DOM
Screenshot
Navigation
Logs

同样的道理。

如果你告诉 AI：

不要绕过 Scope。

但 Runtime 本身允许它直接执行 Tool，那么这个安全要求依然只是文本。

真正的解决应该是：

Action
↓
ScopeGuard
↓
Runtime
↓
Tool

没有通过 Scope：

Tool 根本不能执行。

这个时候，规则才真正进入系统。

所以我现在对 Harness 最简单的理解是：

Prompt 是告诉 Agent“应该怎么做”；Harness 是让整个环境“帮助它做对，并尽量阻止它做错”。

---

4. 为什么 AGENTS.md 也不是万能药

很多人在 AI 项目做大以后，会自然想到一个办法：

把所有规则写进 AGENTS.md。

一开始效果确实很好。

项目结构、编码规范、注意事项、架构要求，都塞进去。

但是随着项目增长：

100 行
↓
500 行
↓
2000 行
↓
5000 行

最后反而会出现新的问题。

OpenAI 自己也走过这条路，并明确说“大型 AGENTS.md”是一种失败尝试。

原因其实很好理解：

第一，Context 是有限的。

规则占得越多，真正的任务、代码和相关资料能占的空间就越少。

第二，当所有事情都写成：

IMPORTANT
MUST
CRITICAL

最后结果就是：

什么都重要
=
什么都不重要

第三，文档会过期。

旧规则继续留着，新规则又不断增加，Agent 很难知道哪个才是现在真正有效的。

所以 OpenAI 后来把 AGENTS.md 变成了一张“地图”。

大致思想是：

AGENTS.md
↓
告诉 Agent 去哪里找

ARCHITECTURE.md
docs/design-docs/
docs/exec-plans/
docs/product-specs/
SECURITY.md
RELIABILITY.md
...

也就是说：

不要一次把整个项目知识倒进 Agent 的脑子里。

而是：

先告诉它地图，需要什么，再去读什么。

这就是渐进式披露。

---

5. Repository 才应该是长期记忆

还有一个我以前很容易忽略的问题：

很多重要知识实际上只存在于聊天记录里。

比如我和 AI 讨论了一个小时以后，终于确定：

EO 只能由 Settlement 创建。

如果这个结论只留在聊天里，那么换一个新的 Session 以后：

新的 Agent 根本不知道。

人类团队也一样。

某次 Slack 讨论决定了一个重要架构原则，但三个月以后新来的开发者没有看过那条消息。

OpenAI 的做法是：

Repository = System of Record

也就是说真正重要的长期知识应该尽量进入仓库：

代码
架构文档
设计决策
执行计划
技术债
产品规格
测试
Schema

这样即使聊天历史全部消失，一个新的 Agent 也能重新理解这个项目。

这对 AI-first 开发尤其重要。

---

6. 文档还是不够，因为 AI 依然会违规

这也是 Harness Engineering 最重要的一步。

你可以在 ARCHITECTURE.md 里写：

Planner 不允许直接调用 Tool。

但是 AI 为了快速完成任务，依然可能写出：

Planner
↓
exec("nmap ...")

而且代码还真的能跑。

这时候问题已经不是：

AI 不知道规则。

而是：

系统允许它违反规则。

OpenAI 的解决办法就是把重要架构规则机器化。

例如用：

Custom Lint
Structural Test
CI

去验证依赖方向。

于是：

文档：
“不要这样做”

变成：

代码这样做
↓
FAIL

这才是真正稳定。

---

7. 我现在怎么看 AI 开发

以前我理解 AI 开发：

人提出需求
↓
AI 写代码
↓
人检查
↓
完成

现在我更愿意理解成：

人提出目标
↓
Agent 尝试
↓
观察它在哪里失败
↓
判断它缺的是：
知识？
工具？
状态？
反馈？
约束？
↓
把缺失能力补进 Harness
↓
Agent 再尝试

也就是说：

Agent 犯错本身，也是项目建设的信息。

如果一个错误以后还可能发生，那么最好的问题不是：

这一次怎么修？

而是：

为什么系统允许这个错误发生？

再进一步：

能不能让这个错误以后更难发生？

这时候解决方案可能是：

Docs
Tool
State
Runtime Guard
Integration Test
E2E
Lint
CI

而不是继续加 Prompt。

---

8. 一句话总结

如果一定让我用一句话解释 Harness Engineering，我会这样说：

它不是研究如何让 AI 写更多代码，而是研究如何把软件项目本身改造成一个 AI 更容易理解、更容易操作、更容易验证、也更难破坏的环境。

所以真正的 Agent 工程能力，并不只取决于模型。

更接近：

Model
×
Context
×
Tooling
×
Architecture
×
State
×
Feedback
×
Enforcement

这也是我现在做 AI 项目后越来越强烈的感觉：

AI 会写代码，只是开始。

真正困难的是：

今天这个 Agent 写出的东西，半年以后换一个完全没有聊天历史的 Agent，它还能不能理解、继续开发，并且不把整个系统搞坏？

如果可以，那这个项目才真正开始具备 AI-first 的工程能力。

---

参考资料

OpenAI，《工程技术：在智能体优先的世界中利用 Codex》

https://openai.com/zh-Hans-CN/index/harness-engineering/

注：本文中的部分小型项目案例与示意图是为了帮助理解而重新构造，并非 OpenAI 原文中的具体实现案例。