Harness Engineering 检查清单：团队使用 AI coding agent 前要补齐的 10 个工程位
如果团队已经开始让 AI coding agent 连续改仓库、跑验证和提 PR，这份 Harness Engineering 检查清单能帮你先补最关键的工程位：知识入口、边界、验证、观测、清理和回退。
Find related content
Search the site for tools, terms, comparison pages, or related troubleshooting notes without going back to the blog index.
Main answer
团队真正需要的不是无限加 prompt，而是先把 10 个基础工程位补齐：入口、规则、验证、观测、回退、清理。
Who should read this
适合已经在仓库里用 AI coding agent 做连续开发、review 或修复的个人开发者和小团队。
Key check
Harness Engineering 最怕一步到位做成大平台。更有效的做法通常是先补关键薄弱环节，再逐步把规则工程化。
Next step
如果你想看这套方法对应到具体开源平台，就接着看 Harness Open Source 两篇。
你将学到
- + 团队进入 harness engineering 阶段后应该先补哪些基础工程位
- + 哪些规则适合写进文档，哪些应该直接变成 lint 或自动检查
- + 为什么验证和观测入口要直接对 agent 开放
- + 如何避免 AI 代码库的熵增和坏模式复制
Harness Engineering 检查清单：团队使用 AI coding agent 前要补齐的 10 个工程位
如果你还没先把几个基础词看顺，建议先过一遍：
先说判断标准
如果你的团队已经出现下面任意两三条，其实就该开始做 harness engineering 了：
- agent 不只是回答问题，而是在持续改仓库
- 会自己跑测试、改代码、提 PR
- 团队开始反复遇到相同风格偏差或重复错误
- 人工 review 时间被挤占得越来越明显
- 文档、代码和真实行为开始脱节
这时候最该做的，不是继续把 prompt 越写越长，而是先补工程位。
1. 给 agent 一个短入口
你的仓库应该有一个短入口文件，比如：
AGENTS.mdREADME-agent.mddocs/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 的开始。
一个更稳的落地顺序
如果你不想一下子铺太大，推荐按这个顺序补：
- 短入口
- repo 内知识源
- 默认验证命令
- 边界和依赖规则
- 关键 lint / 结构检查
- 日志和运行观测
- cleanup 节奏
这个顺序对个人开发者、小团队和内部工具项目都更友好。
下一步怎么接着看
- 什么是 Harness Engineering
- Open Harness 是什么：其实官方名称是 Harness Open Source
- Harness Open Source 安装与入门指南
- 如何把 Agent 工作流从 demo 变成稳定系统
参考与延伸阅读
Continue exploring
Use a tool first
If you need to format JSON, XML, YAML, or prompts, start with the online tools.
See implementation projects
If you want to see how these methods enter real builds and experiments, continue with projects.
Get checklists and templates
If you need checklists, resource entries, or SOP starter packs, continue with resources.
Download reusable skills
If you want repeatable judgment, search, and cleanup actions, continue with the skill market.
要点总结
- - 先补最小可行 harness，比先追求完全自动化更稳
- - 规则写在 repo 里并可校验，才算真正被 agent 看见
- - 没有 cleanup 机制的 agent 代码库会越来越脏
常见问题
这份检查清单适合个人开发者吗？
适合。个人开发者通常不用一次做全，但入口、规则、验证和回退这几项会很快有回报。
是不是每一项都要自动化？
不是。更好的顺序通常是先显式化，再标准化，最后再自动化。
