Harness Engineering 检查清单：团队开始用 AI coding agent 后，最该先补的不是更多提示词，而是这 10 个工程位

如果你还没先把几个基础词看顺，建议先过一遍：

• Harness Engineering
• Coding Agent
• Agent Workflow

先说判断标准

如果你的团队已经出现下面任意两三条，其实就该开始做 harness engineering 了：

• agent 不只是回答问题，而是在持续改仓库
• 会自己跑测试、改代码、提 PR
• 团队开始反复遇到相同风格偏差或重复错误
• 人工 review 时间被挤占得越来越明显
• 文档、代码和真实行为开始脱节

这时候最该做的，不是继续把 prompt 越写越长，而是先补工程位。

1. 给 agent 一个短入口

你的仓库应该有一个短入口文件，比如：

• AGENTS.md
• README-agent.md
• docs/START_HERE.md

它的任务不是包打天下，而是回答这几个问题：

• 先看哪里
• 哪些文件是知识源
• 哪些规则最重要
• 默认验证顺序是什么

2. 把知识源放进 repo

如果关键知识只存在于：

• Slack
• 口头约定
• 临时白板
• 飞书文档但没人同步

那对 agent 来说基本等于不可见。

优先补齐这些：

• 架构说明
• 关键业务规则
• 活跃执行计划
• 技术债清单
• 常见错误与例外处理

3. 把规则分成“说明类”和“强制类”

很多团队的问题不是没规则，而是所有规则都停留在“说明”。

更稳的做法是分两层：

• 说明类：放文档，帮助 agent 理解上下文
• 强制类：放 lint、结构测试、CI、schema 校验

如果某条规则每周都会被违反，它通常就不该只写在文档里。

4. 明确边界和依赖方向

agent 在“自由发挥”的环境里，往往会更快地产生结构漂移。

所以你至少要清楚：

• 哪些层可以依赖哪些层
• 哪些目录是边界
• 哪些类型必须在边界校验
• 哪些跨层访问不允许出现

这类规则一旦明确，agent 反而更好用。

5. 让验证动作标准化

每次都靠人手动告诉 agent “改完跑什么”，是最容易累积摩擦的。

建议至少固定：

• 默认本地验证命令
• 哪类改动必须跑哪些检查
• 前端改动的 visual gate
• 内容改动的 schema / build gate

对你自己的站点来说，像 build + preview 这类规则就是很典型的 harness。

6. 给 agent 观测入口

如果 agent 只能改代码、看不到运行结果，它就很难闭环。

最低配也应该逐步补：

• 测试结果
• 应用日志
• 页面快照或截图
• 关键耗时指标
• 明确的错误信息

这样 agent 才不是“写一下试试”，而是“改完能判断自己到底修没修好”。

7. 设计回退和人工接管点

不是每个问题都适合继续自动迭代。

你应该显式定义：

• 遇到什么情况必须停下来
• 哪些风险需要人工判断
• 哪些改动不能自动 merge
• 出错后默认回到哪个状态

越早把这些点说清楚，越少出现 agent 一路把问题越改越深。

8. 把 review 目标改成“纠偏系统”，不只是挑代码

agent-first 环境里，review 不应该只盯着这一次提交写得像不像人。

更该问的是：

• 这次暴露出什么缺失规则
• 哪个知识入口不够清楚
• 哪个 lint 该补
• 哪个坏 pattern 已经开始复制

好的 review 会反过来升级 harness。

9. 建立固定 cleanup 节奏

AI 代码库不怕偶尔脏一次，怕的是没有持续清理。

建议至少固定做这些：

• 清理重复 helper
• 清理模糊命名
• 把临时 workaround 收敛掉
• 更新失效文档
• 修复 agent 易复制的坏模式

如果你已经开始把每周固定时间花在清理 “AI slop” 上，说明这一步不能再省了。

10. 让团队默认问“缺的是哪层 harness”

当 agent 做不好时，最容易出现的错误反应是：

• 再试一次
• 再换个 prompt
• 再换个模型

但很多时候真正应该问的是：

• 缺的是知识入口？
• 缺的是边界？
• 缺的是验证？
• 缺的是观测？
• 缺的是 cleanup？

这个判断习惯，本身就是 harness engineering 的开始。

一个更稳的落地顺序

如果你不想一下子铺太大，推荐按这个顺序补：

1. 短入口
2. repo 内知识源
3. 默认验证命令
4. 边界和依赖规则
5. 关键 lint / 结构检查
6. 日志和运行观测
7. cleanup 节奏

这个顺序对个人开发者、小团队和内部工具项目都更友好。

下一步怎么接着看

• 什么是 Harness Engineering
• Open Harness 是什么：其实官方名称是 Harness Open Source
• Harness Open Source 安装与入门指南
• 如何把 Agent 工作流从 demo 变成稳定系统

参考与延伸阅读

• OpenAI: Harness engineering: leveraging Codex in an agent-first world