Harness 架构企业工程落地指南

大家好我是玄姐。PSHermes 干货直播欢迎点击预约直播见。导读你是否经历过这样的绝望时刻让 AI Agent 写个功能它洋洋洒洒写了 200 行结果一跑 Linter 直接报错。因为它违反了项目的架构分层约束当然因为你没在 Prompt 里告诉它。 于是它开始自动修复循环三次后上下文窗口被错误日志和 diff 彻底塞满Agent 最终“失忆”连最初的任务目标都忘了。这并不是 Agent 不够聪明而是它“看不见”你的隐式规则。在 AI 辅助编程进入深水区的今天单靠优化 System Prompt 已经摸到了天花板。本文将为你拆解一套全新的工程范式Harness Engineering治理工程带你从“教 Agent 写代码”进化为“为 Agent 打造专属操作系统”。一、 核心破局仓库Repository就是 Agent 的操作系统CPU 再强大没有操作系统也只是无头苍蝇LLM 推理能力再强不知道 internal/types/ 不能引入 internal/config/同样会把代码库搞成一团乱麻。Harness 的核心逻辑是与其依赖 LLM 的“直觉”和庞大的 Prompt不如靠代码、Linter 和测试来做物理拦截。就像 CI/CD 对人类开发者的作用只不过这次拦截的时机更早在写代码之前。这背后有四条不可妥协的原则代码仓库是唯一事实来源IM 群里的约定、Wiki 里的文档对 Agent 来说都不存在。所有的架构约束、命名规范必须作为版本化的文件提交到 Git。地图而不是说明书放弃写 500 行的 AGENTS.md。巨大的指令文件只会挤占宝贵的上下文。AGENTS.md 应该保持在 100 行以内只做索引详细文档按需加载。架构边界重于实现细节不限制具体的设计模式只通过层级Layer 0 到 Layer 4限制依赖方向。高层可以调低层逆向绝对禁止。人类角色的重塑人的核心价值从“写出正确的代码”变成了“设计出让 Agent 必定产出正确代码的流水线”。二、 落地实战Harness 基础设施全景图一个标准的 Harness 项目由两个引擎驱动creator负责审计代码并生成基础设施和 executor在基础设施中执行任务。装备了 Harness 的工程目录通常长这样my-project/├── AGENTS.md ← Agent 的入口导航~100行├── docs/ ← 按需加载的上下文│ ├── ARCHITECTURE.md ← 架构、层级、依赖规则│ └── exec-plans/ ← Agent 的执行计划记录├── scripts/ ← 机械化执法层核心│ ├── lint-deps.* ← 层级依赖检查脚本│ └── validate.py ← 统一验证管道└── harness/ ← Agent 的记忆与状态 ├── memory/ ← 成功经验与失败教训 └── trace/ ← 执行轨迹在这套架构下脚本目录 (scripts/) 就是铁腕执法的警察把团队的软性约定变成了“不遵守就报错”的硬性规则。三、 防御前置动手前先问“能不能做”传统的 Agent 工作流是写代码 - 跑测试 - 报错 - 修复。 但如果写了 50 行代码才发现架构分层错了修复成本极高往往需要消耗大量的 Tool Call。Harness 引入了预验证机制。在 Agent 准备“创建新文件”或“添加跨包 import”时必须先验证合法性❌非法操作拦截python3 scripts/verify_action.py --action import internal/core from internal/handler拦截提示internal/handler (L4) 不能引用 internal/core (L3)。请通过 interface 传递。划重点报错信息的质量决定了 Agent 的自愈能力。不要只抛出 Forbidden import一定要带上原因和修复建议。一条好的报错本身就是一次绝佳的 In-context Learning。此外验证流必须遵循严格的先后顺序Build编译 → Lint-Arch架构约束 → Test单元/集成 → Verify端到端功能验证。 其中 Verify 是往往被忽视但最重要的一环跑通测试不代表功能符合业务逻辑必须用真实的模拟请求来做黑盒验证。四、 高阶心法上下文是最贵的资源在复杂任务中Agent 翻车的头号死因是上下文污染。到了第 40 次交互早期的架构决策早就被满屏的错误日志冲掉了。铁律中等复杂度以上的任务协调者Coordinator绝不写代码你需要把 Agent 拆分为两层协调者 (Coordinator)只负责规划、委派、验收。一行代码都不碰。执行者 (Sub-agents)每次带着纯净的、精确的 Prompt 从头开始干活干完就释放。不要因为“只是改一行代码”就让协调者亲自下场一次简单的编辑往往会牵扯出五次连环修改瞬间抽干上下文。 进阶技巧多模型协同与交叉 Review并不是所有任务都需要用最贵的模型。Harness 提倡按需路由代码检索/定位用 Gemini 1.5 Flash速度极快成本低。简单修改/命名用 Claude Haiku。复杂重构/核心逻辑用 GPT-4o 或 Claude Opus。更重要的是跨模型交叉 Review。用写代码的同一个模型去 Review它会产生“思维盲区”。让架构和训练数据完全不同的模型例如 Opus 写代码GPT-4o 做 Review介入专注于逻辑合理性、竞态条件和边界异常。这种模式能抓出机器 Lint 抓不到的逻辑 Bug且成本极低。五、 终极形态系统的自生长Harness 最迷人的地方在于它能从 Agent 的失败中学习。如果同一个依赖报错反复出现系统的 Critic 模块会分析出规律并交由 Refiner 模块自动去更新 docs/ 里的规则说明或调整 Lint 脚本。当同一类任务如“新增一个 API 接口”被成功执行了多次Harness 会将这段轨迹Trajectory“编译”成一个确定性的自动化脚本。下一次做同样的事连 LLM 都不用调了直接跑脚本。这是一个棘轮效应Agent 踩过的坑变成了永久的基础设施释放出更多的算力去解决真正需要创造力的新问题。六、 行动指南从今天开始建设 Harness 不是非黑即白你不需要第一天就搭出完整的六层基础设施。哪怕只是一个简单的 AGENTS.md也能让协同体验产生质变。你的第一步动作在项目根目录新建一个 AGENTS.md这也是业界的标准协议 agents.md# [项目名] Agent Guide ## 快速链接- [架构总览](docs/ARCHITECTURE.md) — 分层规则- [开发指南](docs/DEVELOPMENT.md) — 常用命令 ## 分层规则 (Layering)- Layer 0: types/ → 纯类型定义严禁引入其他内部包- Layer 1: utils/ → 工具函数仅依赖 Layer 0- Layer 2: core/ → 业务逻辑依赖 L0-L1- Layer 3: api/ → 接口层依赖 L0-L2 ## 质量红线- 必须使用结构化日志禁止直接 print()- 业务逻辑文件不超过 500 行写在最后在未来技术团队的竞争优势不再是“谁的 Prompt 写得更好”而是谁能为 Agent 提供更完善的 Trajectory轨迹和运行环境。这些沉淀在仓库里的约束规则和验证管道是任何新模型都无法轻易复制的护城河。给你的 Agent 装上操作系统吧它不需要变得更聪明它只需要“看得见”。好了这就是我今天想分享的内容。如果你对构建企业级 AI 原生应用新架构设计和落地实践感兴趣别忘了点赞、关注噢~PSHermes 干货直播欢迎点击预约直播见。—1—加我微信扫码加我有很多不方便公开发公众号的我会直接分享在朋友圈欢迎你扫码加我个人微信来看加星标★不错过每一次更新⬇戳”阅读原文“立即预约