Harness Engineering
Harness Engineering 是比“会用 AI 写代码“更高一层的能力:给 coding agent 搭建可靠的上下文、工具、验证和边界,让 AI 能长期、稳定、可审计地工作。
一、什么是 Harness Engineering
Harness 是围绕 AI coding agent 的工程脚手架。它不是模型本身,也不是简单 prompt,而是让 agent 在真实项目里知道规则、记住状态、正确使用工具、按验证闭环完成任务的一整套系统。
二、五个子系统
| 子系统 | 类比 | 作用 |
|---|---|---|
| Instructions | 菜谱架 | AGENTS.md/CLAUDE.md、项目规则、架构说明 |
| State | 备餐台 | feature_list.json、progress.md、session-handoff.md |
| Verification | 出餐质检口 | 测试、lint、build、验收证据 |
| Scope | 任务边界 | one-feature-at-a-time、Definition of Done |
| Lifecycle | 班次管理 | init.sh、启动检查、交接流程 |
三、为什么 AGENTS.md / CLAUDE.md 重要
这类文件是 agent 的项目级路由层,用于告诉 AI:
- 先读哪些文档。
- 哪些文件能改、哪些不能改。
- 运行什么验证命令。
- 完成前必须做什么检查。
- 当前项目的架构和命名约定。
四、状态与会话连续性
长任务容易跨会话,所以需要持久状态:
feature_list.json:记录功能、状态、依赖、证据。progress.md:记录当前进度和阻塞。session-handoff.md:让下一轮 agent 接上上下文。
原则:能从代码/仓库推导出的内容不放进记忆;只记录决策、进度、验证结果和非显然约束。
五、验证工作流与 completion gate
Harness 必须定义“什么时候算完成“:
- 相关测试通过。
- 构建/lint/type check 通过。
- diff 符合需求,没有范围外改动。
- 验证证据被记录。
- 代码审查级验收通过。
只说“测试过了“不够,还要说明跑了什么命令、输出是什么、哪些没跑以及原因。
六、Scope 控制与安全
Agent 最常见问题是过度改动、忘记上下文、为了修一个问题重构半个项目。Harness 通过权限、任务边界、计划、提交粒度和 review gate 限制风险。
七、Android 项目的 Agent Harness 怎么搭
Android 项目比普通脚本项目更容易让 AI 误判:Gradle 多模块、Compose/View 生命周期、版本适配、真机行为、性能和隐私都可能超出静态代码理解范围。
Context Pack
给 agent 的上下文不要只是一句“修一下”。一个可用的 Android context pack 至少包括:
| 内容 | 示例 |
|---|---|
| 项目规则 | AGENTS.md、架构分层、禁止引入的依赖 |
| 构建入口 | ./gradlew :app:assembleDebug、./gradlew test |
| 模块边界 | app / feature / core / shared 的依赖方向 |
| UI 栈 | View、Compose、MVI/MVVM、导航方式 |
| 验证证据 | 单测、截图、录屏、Macrobenchmark、lint 输出 |
Validation Ladder
不同任务需要不同验证层级:
- 纯逻辑:单元测试 + 边界用例。
- ViewModel/Flow:
runTest、Turbine、fake repository。 - UI 改动:Compose/Espresso 测试或至少真机/模拟器手动路径说明。
- 性能改动:Profiler/Perfetto/Macrobenchmark 证据，不能只凭体感。
- 发布/权限/隐私:多系统版本矩阵 + 合规清单。
多 Agent 分工
- Implementer:只改计划内文件，跑覆盖自己改动的测试。
- Reviewer:只看 diff 和需求，找遗漏、过度设计、风险。
- Verifier:复跑构建、lint、关键路径，整理证据。
这种分工的价值不是“更热闹”，而是让实现、审查、验证互相制衡。
八、AI Coding 风险与评估
| 风险 | Android 例子 | Harness 对策 |
|---|---|---|
| 编造 API | 写出不存在的 Compose/AndroidX 方法 | 要求先查现有依赖和相邻代码 |
| 过度重构 | 为修一个崩溃改完整架构 | 计划限定文件和验收范围 |
| 未验证 UI | 只说“应该能显示” | 截图/测试/手动步骤作为证据 |
| 性能幻觉 | 声称“更快”但无数据 | Macrobenchmark/trace 对比 |
| 合规风险 | 提前初始化 SDK 或读取设备标识 | 隐私 gate 和敏感 API 扫描 |
评估 agent 不能只看“代码能不能编译”，还要看需求覆盖率、diff 最小性、测试有效性、回归风险、是否遵守项目约束。
九、面试怎么讲
可以说:“我不只是用 AI 生成代码,还会给 AI 建执行边界:项目说明、任务状态、验证命令、完成门禁和 handoff。这样 AI 适合做重复、检索、草稿和局部实现,但质量由工程化流程兜底。”
更贴近 Android 岗的说法:
“我会把 AI 当成一个需要 harness 的初中级工程师使用。比如让它改 Compose 页面前,我会给它现有 UI 状态模型、导航方式、禁止引入 Material3 的约束和验证命令;改完后必须跑对应单测/构建,UI 改动要有截图或手动路径。AI 负责提效,但架构边界、版本适配、隐私和性能结果由工程流程兜底。”
高频面试题
Q1:Harness Engineering 和 prompt engineering 区别? 答:prompt engineering 关注一次对话怎么问;Harness Engineering 关注长期项目里 agent 的规则、状态、工具、安全、验证和生命周期。
Q2:一个最小可用 harness 包含什么? 答:AGENTS.md/CLAUDE.md 项目规则、明确验证命令、任务状态记录、完成定义、session handoff。复杂项目再加多 agent 协作和权限控制。
Q3:为什么需要 completion gate? 答:防止 agent 只凭感觉宣布完成。完成必须有构建/测试/审查证据,并确认没有范围外改动。
Q4:Android 项目里用 AI coding 最大的风险是什么? 答:上下文和验证不足。AI 可能编不存在的 API、忽略生命周期和 targetSdk 差异、或者改出能编译但 UI/性能有问题的代码。解决方式是给 context pack、限定 scope、要求测试/构建/截图/性能证据，并让 review gate 检查范围外改动。
易错点 / 追问
- 不要把 harness 讲成“写一个超长 prompt“。
- 不要让记忆保存可从仓库推导的信息。
- 不要让 agent 在没有验证命令的项目里自由发挥。