一个不懂架构的小白，怎么从 0 到 1 用 Harness Engineering 开发 AI 项目？

一个不懂架构的小白，怎么从 0 到 1 用 Harness Engineering 开发 AI 项目？

——不需要先成为架构师，也能一步一步把 AI 开发流程搭起来

读完 OpenAI 的《Harness Engineering》以后，我遇到了一个比“看懂文章”更现实的问题：

道理我好像都懂了，但我是小白，我到底怎么照着做？

文章里会出现很多词：

Architecture
Invariant
Repository
Feedback Loop
E2E
Lint
CI
Observability
Garbage Collection

对有经验的工程师来说，这些东西很好理解。

但是对于一个本来就依赖 AI 帮自己开发项目的人来说，很容易陷入另一种困境：

我连什么叫合理架构都不知道，
那我怎么设计Harness？

我后来发现，这个问题其实可以换一种理解。

你不需要第一天就设计出完美架构。

真正更适合小白的方法是：

先做一个最小闭环
↓
让Agent真正跑起来
↓
观察它在哪里失败
↓
从真实问题里提炼规则
↓
把重复问题逐步变成Harness

这篇文章就从一个完全小白的视角，把整个过程走一遍。

---

第一步：不要一上来就让 AI“把整个项目做完”

假设我要做一个任务管理网站。

需求很简单：

新增任务
查看任务
完成任务
删除任务

一个很自然的 Prompt 是：

帮我完整开发一个任务管理系统。

AI 很可能真的能写。

甚至几分钟以后：

项目结构有了
页面有了
数据库有了
接口有了

看起来效率非常高。

但对于小白来说，这是最危险的时候。

因为你根本不知道：

哪些结构是合理的？
哪些只是为了快速跑通临时拼的？
哪些以后会变成技术债？
哪些模块根本没有真正接起来？

所以第一步不要直接要完整产品。

先问：

这个大目标可以拆成哪些“最小可验证闭环”？

比如：

Slice 1：
用户输入“买牛奶”
↓
点击Add
↓
系统保存任务
↓
页面显示“买牛奶”

先只做这一条。

---

第二步：怎么判断目标拆得够不够小？

我现在有一个特别简单的判断方法：

你能不能清楚说出“怎么证明它完成了”？

例如：

目标：
增加任务

验证方法：

打开页面
↓
输入“买牛奶”
↓
点击Add
↓
页面出现“买牛奶”
↓
刷新页面
↓
“买牛奶”仍然存在

这个目标就比较清楚。

但是如果你的目标是：

优化整个系统架构。

你会发现：

怎么证明优化完成？

很难回答。

那说明这个目标还太大。

所以小白拆目标的时候，不需要懂复杂项目管理。

只需要不断问：

完成以后我能观察到什么？

---

第三步：让 Agent 尝试，然后看它在哪里卡住

假设 AI 已经把“新增任务”写出来了。

但它只能：

修改代码

不会：

启动页面
点击Add
查看DOM
确认结果

这时候你发现：

AI写出来了

但：

AI不知道自己写对没有。

很多人第一反应是：

Prompt：
“请认真检查一下。”

但这其实没有解决问题。

因为它缺的不是“认真”。

它缺的是：

验证能力。

所以应该考虑给它：

Playwright
Browser Tool
Chrome DevTools
日志
E2E

这就是 Harness Engineering 最重要的思维之一：

先判断缺的是能力，还是提醒。

---

第四步：小白怎么判断 Agent 到底缺什么？

我现在会把 Agent 的失败先简单分成五种。

不需要专业术语。

只问下面五个问题。

---

第一种：它“看不到”

比如：

找不到真实Runtime入口
不知道哪个文件真正被调用
看不到运行日志
不知道Graph里现在有什么

这种问题不是：

Agent不会思考。

而是：

它没有足够可见性。

可能需要补：

AGENTS.md地图
Architecture Docs
代码搜索
日志
Status命令
Dependency Map

---

第二种：它“看得到，但不知道”

例如代码就在它面前。

但它不知道：

这个模块不能直接调用另一个模块。

这个Store才是真相源。

这个状态只能由Settlement创建。

这说明知识还停留在：

人的脑子
聊天记录
历史讨论

需要把它写回：

Repository

比如：

ARCHITECTURE.md
SECURITY.md
Design Decision

---

第三种：它“知道要干什么，但做不了”

比如 Agent 知道：

应该运行nmap。

但是：

本机没有nmap
路径不知道
没有执行权限
没有Sandbox

那缺的是：

Tool / Runtime / Execution Environment

而不是：

更长的Prompt。

例如安全 Agent 以后可能需要：

Kali WSL
Docker
Remote Tool Gateway

这就是补“执行能力”。

---

第四种：它“能做，但不知道做对没有”

例如：

代码写完
Unit Test全绿

但它不知道：

整条真实业务流程到底有没有跑通。

那缺的是：

Integration Test
Golden E2E
Logs
Trace
Browser Validation

简单理解：

Unit Test
检查零件

E2E
检查整台机器

---

第五种：它“知道规则，但系统还是允许它违规”

这是最重要的一类。

比如 ARCHITECTURE.md 明明写：

Planner不能直接调用Tool。

Agent还是写了：

Planner
↓
nmap

这时候问题不是：

它不知道。

而是：

系统没有阻止。

所以应该考虑：

Architecture Test
Lint
Runtime Guard
CI

让：

违反规则
↓
自动FAIL

---

第五步：小白不懂架构，怎么办？

这是我自己最困惑的问题。

后来我发现：

不要先问“正确架构应该长什么样”。

先问：

“现在这个已经能工作的功能，真实到底怎么跑？”

假设新增任务功能已经成功。

让 AI 从真实代码追踪：

用户
↓
UI
↓
TaskService
↓
TaskRepository
↓
Database

这时候你不需要学一整本架构书。

先看三个东西就够了：

Boundary
Ownership
Direction

翻译成中文就是：

谁负责什么？
谁说了算？
谁可以调用谁？

---

第六步：Boundary——谁负责什么？

例如：

UI

应该负责：

展示
接收用户操作

不应该负责：

直接访问数据库

再例如安全 Agent 里的：

HTTPX Adapter

应该负责：

Raw HTTPX Result
↓
Canonical Result

不应该：

直接写Graph
直接创建Hypothesis
直接操作ActionTrace

这就是模块边界。

你不需要知道“Clean Architecture”是什么。

只需要知道：

这个模块应该干什么？
不应该干什么？

---

第七步：Ownership——这个数据到底谁说了算？

项目复杂以后特别容易出现：

Graph里有endpoint
Recon Store也有endpoint
Planner里还有一个endpoint列表

问题来了：

哪个是真的？

这就是 State Ownership。

你可以直接问 AI：

这个事实的 Source of Truth 是谁？

比如：

Evidence
→ EvidenceStore

Graph关系
→ GraphStore

Action历史
→ ActionTrace

其他地方最好：

引用
派生
缓存

而不是再建立一份“官方版本”。

这样以后状态才不会越来越乱。

---

第八步：Direction——谁可以调用谁？

比如：

Planner
↓
Action
↓
Runtime
↓
Tool

这是一个很清楚的方向。

如果有一天 Agent 写：

Planner
↓
直接exec nmap

你就可以问：

为什么绕过Runtime？

你不需要知道具体 TypeScript 实现。

只需要知道：

决策
和
执行

不应该混在一起。

这就是 Dependency Direction。

---

第九步：从真实 Bug 里找 Invariant

Invariant 这个词听起来很专业。

其实可以翻译成：

项目里“绝对不能被破坏”的死规矩。

怎么找？

不要凭空想。

从真实问题反推。

比如你的安全 Agent 曾经出现：

同一次观察被不同模块重复登记

那可以提炼：

Occurrence只能有一个逻辑Writer。

再比如：

Agent可能执行未授权目标。

提炼：

所有External Active Action必须经过Scope。

再比如：

新旧Graph流程可能同时处理同一结果。

提炼：

Canonical结果不能再次进入Legacy Graph解释路径。

你看：

这些规则不是从架构教科书里抄来的。

而是从：

真实Bug
真实风险
真实重复问题

长出来的。

---

第十步：把“文档要求”升级成“机器规则”

你现在有：

ARCHITECTURE.md

里面写：

Occurrence只能由Settlement创建。

但以后新的 Agent 仍然可能忘记。

怎么办？

让 AI 再做一件事情：

把这条文档规则变成可以自动检查的规则。

例如：

Runtime中
只有canonical-settlement.ts
可以调用OccurrenceStore.append

然后增加 Architecture Test：

发现其他调用点
↓
FAIL

这样以后：

AI不需要“记住”

因为：

系统自己会拦。

这就是：

Documentation
↓
Invariant
↓
Machine Enforcement

---

第十一步：人类到底负责什么？

这一步对小白非常重要。

很多人以为：

我不会写代码
↓
所以我没有资格判断架构。

其实不是。

你不一定需要知道：

AST怎么分析
ESLint怎么写
TypeScript泛型怎么实现

你更应该负责：

我要什么结果？

什么绝对不能发生？

什么必须发生？

哪个数据应该只有一个官方来源？

怎么证明这个功能真的工作？

AI 可以负责：

分析代码
提出实现方案
写代码
写测试
写Lint
写Architecture Test

所以一个比较合理的人机分工是：

Human:
Intent
Boundary
Invariant
Acceptance Criteria
Judgment

Agent:
Investigation
Implementation
Testing
Automation
Refactoring

---

第十二步：新功能怎么走一遍完整流程？

假设我要给安全 Agent 增加：

HTTP探测能力

不要直接：

帮我接HTTPX。

可以这样一步一步走。

1. 目标

用户给一个授权目标
↓
Agent可以完成HTTP探测
↓
结果进入系统
↓
后续推理可以使用

2. 拆小

Agent能表达HTTP探测意图
↓
Runtime能执行Provider
↓
Raw Result能被标准化
↓
结果能进入Evidence / Graph
↓
Trace能记录
↓
E2E能验证

3. 审计当前架构

问 AI：

当前ToolCall从产生到Result落盘
真实经过哪些模块？

4. 找边界

比如：

HTTPX Adapter
只做：
Raw Result → Canonical Result

5. 找 Invariant

例如：

必须经过Scope
不能直接写Graph
不能自己创建Occurrence

6. Change Impact

检查：

会影响哪些已有模块？

7. Implementation

只实现：

这一条Slice。

8. Integration Verification

确认：

不是只有httpx.ts文件存在，
而是真正被Runtime调用。

9. Golden E2E

真正跑：

Target
↓
Scope
↓
ToolCall
↓
HTTPX
↓
Canonical
↓
Settlement
↓
Evidence / Graph / Trace

10. Review

换一个 Agent 检查：

有没有绕架构？
有没有重复状态？
有没有平行Pipeline？

11. Harness Retrospective

问：

这次过程中，
Agent在哪里卡住？
以后还会不会发生？

如果会：

补进Harness。

---

第十三步：什么时候不要过度工程？

Harness Engineering 也不是：

每修一个错别字
都新增一个Architecture Test。

普通小 Bug：

复现
↓
修复
↓
Regression Test

就够了。

只有当你发现：

这个错误以后其他Agent很可能继续犯

才考虑：

Docs
Rule
Guard
Test
CI

这是非常重要的。

否则 Harness 本身也会变成新的复杂度来源。

---

第十四步：项目越来越大以后，再做“垃圾回收”

随着 AI 不断写代码，慢慢可能出现：

重复helper
重复pipeline
Legacy和New同时存在
命名漂移
临时workaround
过期文档

不要等两年以后再大重构。

可以定期让 Agent 做：

Entropy Audit

寻找：

一个坏模式
是不是已经出现第二次、第三次？

然后小范围清理。

这就是 OpenAI 文章里的：

Garbage Collection

核心思想：

技术债不断偿还一点

比：

积累到最后一次性爆炸

更安全。

---

第十五步：真正应该形成的是一个循环

最后，小白真正需要掌握的不是某种架构模式。

而是这个循环：

目标
↓
最小可验证闭环
↓
Agent尝试
↓
观察失败
↓
判断：
看不到？
不知道？
做不了？
无法验证？
没人阻止？
↓
补Harness
↓
验证Harness真的有效
↓
进入下一个闭环

每次项目成长一点：

Harness也成长一点。

而不是：

第一天先设计未来三年的完美架构。

---

我现在最推荐小白记住的 7 个问题

以后让 AI 开发任何功能，我都会先问：

1. 最终我要看到什么结果？

2. 怎么把它拆成一个最小可验证闭环？

3. 当前真实运行链是什么？

4. 谁负责什么？

5. 谁拥有状态？

6. 什么绝对不能被破坏？

7. 怎么让系统自动证明它没有被破坏？

如果这 7 个问题越来越能回答：

你其实就在慢慢获得架构能力。

不是因为你背了多少设计模式。

而是因为你开始理解：

系统为什么这样组织。

---

最后一个原则：不要只修错误，要修“允许错误发生的环境”

以后 AI 又犯错时。

不要只说：

修一下。

再问一句：

为什么系统允许它这样犯错？

如果是一次性问题：

修掉。

如果以后大概率还会发生：

Failure
↓
Root Cause
↓
Harness Gap
↓
Docs / Tool / State / Test / Guard / CI
↓
Machine Verification

最终目标不是：

让Agent永远记住所有规则。

而是：

让项目本身越来越容易被新的 Agent 理解，也越来越不容易被新的 Agent 搞坏。

对于一个依靠 AI 学习开发的小白来说，我认为这才是 Harness Engineering 最实际的意义。

---

参考资料

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

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

注：本文基于 OpenAI Harness Engineering 原文的方法论进行初学者视角的重新组织。文中的任务管理系统、安全 Agent、HTTPX 等案例均用于解释方法，并非 OpenAI 原文中的具体产品实现。