Harness Engineering：AI 时代的工程最佳实践

实践二：Architectural Constraints — 用机器而非人来守住架构边界

靠 Code Review 守住架构？当 Agent 一天输出几十个 PR 时，这条路走不通。

OpenAI 的做法是用 Agent 自己写 Linter 来约束 Agent，形成自动化的架构护栏：

关键设计：Linter 不只是让构建失败，还将修复指令注入回 Agent 的上下文

Agent 生成代码
↓
自定义 Linter 检测到违规
↓
构建失败 + 错误信息包含修复指令
↓
Agent 读取错误信息，自动修复
↓
再次提交 → 通过

这是一个反馈闭环，而不是一堵墙。

具体约束举例：

• 依赖方向：service 层不能反向依赖 controller 层，Linter 检测 import 路径强制执行
• 结构化日志：所有日志必须使用指定格式，不允许裸 System.out.println
• 文件大小限制：单文件超过阈值自动拒绝，倒逼模块拆分
• 命名规范：类名、方法名、变量名通过正则校验
• 循环依赖检测：依赖图分析，发现环路立即阻断

三管齐下的检查体系：

• 确定性 Linter — 适用于规则明确的硬约束，如 import 方向、命名规范
• 结构化测试 — 适用于运行时行为验证，如依赖图环路检测
• LLM-based Agent — 适用于需要语义理解的软约束，如 "这个类的职责是否越界？"

实践三：Garbage Collection — 把技术债务当 GC 来做

Agent 生成的代码会退化，这是不可避免的。OpenAI 的策略不是"事后大扫除"，而是持续小增量清理，像 JVM 的垃圾回收一样。

传统方式：技术债务累积 → 某天爆发 → 停下来还债（痛苦）
Harness 方式：GC Agent 持续运行 → 小增量清理 → 代码库自我清洁

GC Agent 的工作内容：

• 扫描并修复架构约束违规
• 清理未使用的代码、过时的接口
• 统一不一致的编码风格
• 修复文档与代码的偏差

落地建议：

1. 设置定时任务，让 Agent 每天扫描代码库中的已知反模式
2. GC 结果输出为 PR，人工快速审核后合并
3. 监控技术债务指标的趋势，确保持续收敛而非发散

实践四：Agent Legibility — 让 Agent 能"看到"运行时

代码吞吐量上来后，瓶颈从"写代码"转移到"验证代码"。OpenAI 的突破点是让 Agent 直接访问运行时状态。

三大可观测性通道：

• UI 通道 — 通过 Chrome DevTools Protocol 实现，Agent 可以截取 DOM 快照、截图、操作页面验证
• 日志通道 — 通过 LogQL 查询接口实现，Agent 可以查询错误日志、追踪请求链路
• 指标通道 — 通过 PromQL 查询接口实现，Agent 可以查询延迟、吞吐量、错误率等指标

这意味着 Agent 可以处理这类任务：

"确保服务启动在 800ms 内完成"

Agent 可以自己启动服务、查询启动耗时指标、定位瓶颈、优化代码、再次验证 — 全程无需人工介入。

落地建议：

1. 暴露结构化的日志查询接口，让 Agent 可以按 traceId、错误级别过滤
2. 关键性能指标通过 API 可查询，而非只能在 Dashboard 上看
3. 如果有前端项目，考虑集成浏览器自动化工具让 Agent 能做 UI 验证

实践五：Bootable per Git Worktree — 每个变更一个独立沙箱

并发是 Agent 开发的常态。多个 Agent 同时在不同分支上工作，如果共享环境，互相污染是必然的。

OpenAI 的做法：每个 Git Worktree 可以启动一个完全隔离的应用实例。

Agent-1 (feature-A worktree) → 独立实例 -1 → 独立数据库
Agent-2 (feature-B worktree) → 独立实例 -2 → 独立数据库
Agent-3 (bugfix-C worktree) → 独立实例 -3 → 独立数据库

每个 Agent 拥有自己的"私人实验室"：

• 独立复现 Bug，不受其他变更干扰
• 独立验证修复，不污染其他环境
• 独立推理 UI 行为，截图结果可信

落地建议：

1. 容器化你的应用，确保一条命令即可启动完整环境
2. 使用 Docker Compose 或类似工具定义隔离的服务栈
3. 数据库使用内存模式或独立实例，避免数据竞争

实践六：Autonomous Workflow — 从 Prompt 到 Merge 的全自治流水线

当前面五个实践就绪后，最终形态就是端到端自治开发工作流，以下是一个可预期的场景：

一个 Prompt
↓
验证代码库当前状态
↓
复现 Bug / 理解需求
↓
实现修复 / 新功能
↓
驱动应用验证（UI + API + 指标）
↓
录制演示视频
↓
开 PR + 描述变更
↓
响应 Review 反馈并修改
↓
检测构建失败 → 自动修复
↓
合并（或升级给人类判断）

仅在需要判断力时才升级给人类。Agent 处理 90% 的机械性工作，人类聚焦于真正需要决策的 10%。

总结

• Context Engineering — 解决上下文丢失。用 AGENTS.md 建导航地图，渐进式披露，文档当代码维护。
• Architectural Constraints — 解决架构漂移。Linter 不只报错，还把修复指令喂回给 Agent，形成闭环。
• Garbage Collection — 解决技术债堆积。像 JVM GC 一样持续小增量清理，代码库自我清洁。
• Agent Legibility — 解决 QA 瓶颈。让 Agent 直接查日志、看指标、操作 UI，自己验证自己。
• Bootable per Worktree — 解决环境污染。每个变更一个隔离沙箱，互不干扰。
• Autonomous Workflow — 解决人工瓶颈。从 Prompt 到 Merge 全自治，仅判断力需人类介入。

Harness Engineering 的核心洞察：在 Agent-First 时代，软件工程的核心产出不再是代码，而是让 Agent 高效产出高质量代码的系统。 你设计的不是功能，而是约束、反馈和环境。