AI Agent工程实践：Harness Engineering完全指南

当AI Agent完成一个功能开发后，运行lint却直接失败——类型定义文件import了配置包，违反了架构分层约束。这种情况并不罕见：AI生成的代码能跑，但完全不符合团队规范。问题不在于Agent不够聪明，而在于它「看不见」——代码库中的隐式规则（架构约束、命名规范、依赖方向）从未被传达给它。传统做法是写更详细的prompt或文档，但这很快就会触及天花板：规范文档AI读不到，prompt再长也装不下整个仓库的架构决策。

Harness Engineering的核心思路

从理念到落地：两大引擎协作

Harness Engineering的解决思路截然不同：与其教Agent怎么做，不如让它自己验证做得对不对。它把仓库视为Agent的「操作系统」——LLM推理能力再强，也需要知道internal/types/不能import internal/config/，新文件应该放在哪个目录。具体有四条核心原则：首先是仓库作为唯一事实来源，所有架构决策、层级约束、命名规范都必须编码到Git仓库中作为版本化文件，而不是写在Wiki或发在群里；其次是AGENTS.md应该是地图而非手册，控制在约100行只做索引，详细内容放在docs/目录按需加载，避免指令文件过于庞大而迅速过时；第三是约束的粒度只管架构边界，将代码库的自然依赖方向编码为层级编号（Layer 0是类型定义，Layer 1-2是工具函数和配置，Layer 3是业务逻辑，Layer 4+是HTTP handler），规则只有一条「高层可以import低层，反过来不行」；最后是人的角色从「写出正确代码」转变为「设计让Agent能可靠产出正确代码的环境」。

验证机制的层次与实践

Harness Engineering靠两个核心引擎协作实现：harness-creator负责分析代码库、生成基础设施（文档、lint脚本、目录结构）；harness-executor在这套基础设施中执行开发任务。当executor启动时发现AGENTS.md不存在，会自动调用creator来搭建基础设施。一个典型的Harness项目结构包含：AGENTS.md作为导航地图（约100行）、docs/目录存放各类详细文档、scripts/目录包含lint-deps（依赖方向检查）、lint-quality（代码质量规则）、validate.py（统一验证管道）、以及harness/目录管理任务状态和执行轨迹。creator首次运行时会审计项目现状，按文档覆盖率和lint规则覆盖率打出0-100分，0-20分从零搭建，21-70分针对性补充，71分以上微调即可。

上下文管理：协调者与执行者分离

验证是Harness最实操的部分，分为几类。最核心的是依赖方向检查（lint-deps），确保core/不能import ui/，api/和cli/不能互相引用；其次是质量规则检查，强制单文件不超过500行、禁止console.log/print()要求用结构化日志、禁止硬编码品牌字符串。但更重要的是事前预防——在写代码前先问「能不能做」，而不是写完后让linter来抓。预验证只需两次交互就能拦截层级违反，避免了事后修复需要约10次tool call的代价。验证流程有严格顺序：先build（编译通过）、再lint-arch（架构约束）、然后test（功能正确性）、最后verify（端到端功能验证）。verify是容易被遗漏的关键步骤——测试通过不代表功能是对的，verify要验证的是「用户执行这个操作，最终结果对不对」。

如有侵权，请联系删除。