从 Vibe Coding 到 Harness Engineering

2025 年，Vibe Coding 让无数开发者体验到了凭借直觉与 AI 快速构建 Demo 的乐趣。然而，当这些 Demo 试图走向真实的企业级生产环境时，许多团队却面临着“AI 失忆症”与工程化协作的痛点：

每次开启新会话，AI 就会忘记项目既定的技术栈（比如用回了 Express 而非团队指定的 Fastify）？

生成的代码风格飘忽不定，频繁被 CI/CD 或代码审查（PR）退回？

面对百万行级别的庞大代码库，如何防范 AI 在长任务中因上下文溢出而“迷失方向”？

这些问题并不是因为 AI 模型不够聪明，而是因为我们往往只发挥了它 10% 的能力，仅把它当作一个高级的聊天窗口。

2025 年我们见证了 Vibe Coding 的繁荣；而 2026 年，企业级应用的核心将转向 Harness Engineering。

核心公式：Agent = Model + Harness

在系统拆解之前，我们需要厘清一个核心公式：

Agent = Model + Harness

Harness 一词的原意为“马具”（套在马身上的挽具、缰绳等）。马匹虽然力大无穷，但若没有马具的控制与牵引，便无法拉动车辆。大语言模型也是如此，它本身只是一个具备理解与生成能力的“智力引擎”，而 Harness 则是包裹在模型外层的一切工程化基础设施（包括上下文管理、工具调度、事件拦截、状态持久化等）。

近期，多项行业实测证实了一个关键规律：

“同一模型在不同 Harness 下的表现差异，远大于不同模型在同一 Harness 下的差距。”

在 TerminalBench 基准测试中，仅通过对 Harness 层的优化，就使同一个模型的能力从基线以下跃升至 Top 5。

Vercel 团队发现，主动剔除 80% 的 Agent 工具后，流程更精简，Token 消耗骤降，响应速度反而更快。

因此，调教 Harness 才是释放 AI 真实工程效能的真正变量。

第一关：如何让 AI 读懂（巨型）代码库？

痛点：AI 记不住项目规范，大库读不完

每次新建会话都要重新给 AI 解释项目背景，且由于上下文窗口的限制，面对百万行级别的代码大库，AI 常常面临“读不完”或“读了后面忘前面”的窘境。

解法：五层记忆体系 + 上下文分诊

#### 1. 建立分层的记忆架构

不能把所有的规范都塞进同一个配置文件里。应该构建一个五层记忆体系：

Enterprise 级：企业全局 CLAUDE.md，写入不可绕过的安全与合规策略（如：严禁将代码发送至外部 API、禁止硬编码密钥等）。

User 级：存放个人的编码偏好（如：交流语言、快捷指令映射）。

Project 级：团队共享的项目级规范（如：明确规定使用 Fastify 框架和 pnpm 包管理）。Anthropic 官方硬指标要求该文件控制在 200~300 行以内，它不是文档夹，而是始终在线的 P0 槽，每一行都应是真金白银的规则。

Rules 级：将细分领域的规范（如前端组件规范、数据库迁移规范、测试策略）拆解为独立文件。利用 YAML Frontmatter 的 paths 字段声明 Glob 模式进行条件化加载。例如：只有当 AI 操作 tests/** 路径时，才会激活测试规范，实现按需取用。

Local 级：存放个人的临时备忘，该文件自动被纳入 .gitignore，不提交到代码库。

#### 2. 上下文分诊：类比操作系统调度

在大模型时代，LLM 是 CPU，Context 是内存，文件系统则是磁盘。我们无法把磁盘一股脑堆进内存中，这就需要引入类似 OS 虚拟内存管理器的“上下文分诊”机制，将候选信息分为四个等级（P0 ~ P3）：

等级描述示例

P0始终驻留上下文当前任务目标、核心约束 P1按需加载，高优先级相关代码片段、错误日志 P2按需加载，低优先级历史文档、参考实现 P3外部检索，压缩摘要全量代码库索引、旧版本记录

通过这种分诊调度，例如在排查“订单扣款失败”问题时，AI 仅调入 3 段核心日志（P0/P1）与 5 段历史工单句柄（P3），将上下文体积从 18K 压缩至 2K Token，信噪比大幅提升，定位问题的准确度反而更高。

第二关：如何控制 AI 的幻觉？

痛点：AI 给出看起来对、实际是错的代码

在长会话中，Claude Code 在 95% 容量时会自动触发上下文压缩。如果它把一段 487-token 的“连接池耗尽”错误堆栈压缩成了一句简单的 a database error occurred，AI 就丢失了原本的反馈回路，接下来可能会花费数小时重试那些早已被堆栈排除掉的错误方案，在原地打转。

解法：结构化上下文 + Hooks 质量门禁

#### 1. 结构化输入，注入而非生成

减少幻觉的关键在于让 AI 基于已有的代码进行“注入修改”，而不是让其“凭空创造”。在向 AI 下达任务时，尽量避免“帮我优化这个函数”等模糊表达，而是要提供结构化信息：

反例：帮我优化这个函数。

正例：优化 src/utils/parser.ts 的 parseConfig 函数，瓶颈在第 42 行的循环。

#### 2. Stop Hook 作为契约：将控制交回确定性工程

“Prompt 是请求，Hook 是契约。”我们不需要在 Prompt 里一遍遍地哀求 AI “请不要胡思乱想”，而是要用确定性的 Hook 门禁把不靠谱的产出挡在门外。

通过在扩展层配置 Stop Hook（在 AI 完成响应并生成完代码之后、准备交付之前触发），让系统自动静默运行单元测试与代码静态检查：

json
{
  "hooks": {
    "Stop": [
      {
        "matcher": "All",
        "command": "pnpm lint && pnpm test",
        "blocking": true
      }
    ]
  }
}

如果测试未通过，系统直接阻断本次提交并报错，把结果喂回给 AI，让其自己修改，直到自愈通过后再交付。

第三关：如何实现经验复用？

痛点：好 Prompt 锁在个人脑子里，无法团队共享

每个开发者都在自己的终端里重复写着类似的代码审查、测试生成等 Prompt，新人上手慢，全队重复造轮子。

解法：从 Prompt 到声明式 Skill

在 Claude Code 的设计中，支持将好用的 Prompt 封装为 .claude/skills/ 目录下的 Skill 资产，并通过 Git 进行版本控制。如此一来，新人克隆代码库时就能瞬间继承整个团队沉淀的 AI 编程能力。

一个 Skill 实质上是一个包含 SKILL.md 的目录。为了节省 Token，Claude 采用了渐进式披露的设计：

启动阶段：仅加载每个 Skill 顶部的 name 和 description（约 100 tokens 的元数据）。

匹配阶段：当用户的输入命中该 Skill 的语义（如提到“审查代码”），系统才会展开完整的 SKILL.md 主文件。

执行阶段：只有在真正需要动作时，才动态调用挂载的 bundled 脚本/外部资源。

通过这种“只在翻开书的对应章节时才看内容”的设计，在运行多 Skill 系统时，Token 空间可节省达 98% 左右。

第四关：算力贵、用量不透明？探寻 Token 经济学

痛点：一次任务烧了多少钱说不清，长对话越到后面越贵

解法：反向选型、多层路由与 Talker-Reasoner 架构

#### 1. 建立模型选择矩阵

在企业实际部署中，全跑高档的 Opus 往往会造成极大的资金浪费。经过对真实业务复杂度分布的统计发现，多达 41% 的查询只是简单的 SQL 模板填空，只需要最便宜的 Haiku 模型即可胜任。

通过在 Harness 中配置三层路由机制：

Haiku (60%) → Sonnet (30%) → Opus (10%)

在保障产出质量的前提下，月账单可以从 48 万骤降至 12 万，综合成本下降达 65%~75%。

#### 2. 反向选型：在受限模型下选择“模式”

当预算和部署环境是硬约束，只能在本地部署开源便宜模型（如 Qwen-32B）时，该如何提升准确率？

此时模式的选择才是设计的核心：

单次调用 Opus：价格高昂，面对边缘 case 依然可能出错。

Haiku 便宜模型 + 迭代自愈：让 Haiku 写代码，另一个 Haiku 做 Code Review，循环迭代 2 轮。其综合算力成本依然远低于单次调用顶级模型，但最终产出质量反而实现了反超。

#### 3. Talker-Reasoner 双系统

针对实时对话/Voice 等高频交互场景，长时间的思考延迟（如 reasoning 模型动辄等待 24 秒）会导致用户以为系统卡死。

借鉴 Kahneman 双系统理论，可将架构重构为 Talker-Reasoner 协同模型：

Talker：采用 200ms 的极速便宜模型（如 Haiku），负责立即回复用户、边聊边等。

Reasoner：采用慢速但聪明的模型（如 Opus/reasoning），在后台进行深度推理，将推理出的 belief state（信念状态）源源不断地供给给 Talker。

这样成功地把思考延迟在用户的感知里“藏”了起来。

第五关：约束与放手

痛点：AI 改对了 Bug，却顺手改了三处不该改的安全逻辑

解法：约束行动而不是约束思考，引入 HITL 人工审核

在治理 AI 的行动边界时，很多技术负责人会陷入一个误区：试图在 Prompt 里细化 AI 的每一个思考步骤。这反而会束缚模型的推理自由。

“约束限定的是行动的边界，而不是思考的自由。约束不是能力的保障，而是能力的容器。”

合理的工程约束应该放置在动作发生、产生副作用（不可逆操作）的地方：

只读/低爆炸半径操作（如查代码、看文档）：自动放行，不中断流程。

可写/中等影响操作：留痕放行，记录全链路的 Keyed log，事后支持完整 replay 溯源。

高爆炸半径/不可逆操作：强制触发阻断，并在控制台弹出 HITL 人工审核面板，人手点下确认后，AI 才能继续往下执行。

第六关：复杂的编排载体该如何抉择？

痛点：SubAgent、Skill、Workflow、Agent Team 概念混淆，不知道怎么组织

解法：一张四方图厘清边界

在 Harness 设计中，这四种编排载体并不是竞争关系，而是分别映射了现实世界中的四种工作实体：

Skill = 岗位操作手册：是静态的、跨任务复用的知识包与 SOP 模板，代表了 Agent 的职业能力。

SubAgent = 专职员工：具备独立的、被隔离的上下文空间，执行完特定任务（如跑个测试、搜个关键字）后即刻销毁，实现防污染。

Workflow = SOP 流程图：将控制流显式、确定性地冻结在代码或脚本中，适用于多步、有着明确目标的长期自动化流程（如 nightly build 代码自动修复）。

Agent Team = 持续协作的虚拟团队：维持长期的、多人的对话交互，各个 Mate 角色拥有持久化 Session。

在成熟的企业项目中，这四者通常是互补、嵌套使用的，共同组合为一套业务流水线。

第七关：如何防止长任务状态漂移？

痛点：复杂的长任务跑着跑着就偏离了目标

解法：三平面分立架构 + 草稿纸看板

针对这个问题，可以引入三平面分立架构：

推理平面：模型进行思考、规划、决策的地方，不产生副作用。

执行平面：实际调用工具、修改文件、运行命令的地方，所有操作被记录。

验证平面：对执行结果进行校验，如运行测试、检查 lint、比对预期输出。

同时，引入“草稿纸看板”机制：Agent 在执行过程中，将中间推理、计划、待办事项写到一个外部 Markdown 文件（如 dev-plan.md）中。这样即使上下文被压缩，Agent 也能从看板文件中恢复状态，避免“原地打转”。

第八关：可观测性与治理——Agent 的“黑匣子”

痛点：Agent 失败了你不知道为什么，成功了你也不一定敢用

解法：Trace-native 评估与分层治理

#### 1. Trace-native 评估

Agent 评估不能只看最终成功率。要记录模型输出、工具调用、工具返回、环境状态变化、上下文快照、错误、重试、恢复动作、token 使用、延迟和成本。然后再判断三件事：

结果是否正确？

路径是否合理？

评估器本身是否可信？

这会把 Agent 评估从“排行榜机制”拉回“质量控制机制”。排行榜回答的是：谁分高？质量控制回答的是：为什么失败？该改哪一层？

#### 2. 分层治理

执行环境：沙箱隔离，防止 Agent 操作生产环境。

工具权限：最小权限原则，只给 Agent 完成当前任务所需的最小工具集。

数据访问：敏感数据脱敏，禁止 Agent 直接访问 PII 数据。

人工审批：对高危险操作（如删除文件、修改数据库）强制人工确认。

从 Agent Framework 到 Agent Platform

如果只看工具生态，Agent 正在从 framework 走向 platform。

Framework 解决的是局部抽象：agent、tool、memory、loop。Platform 要解决的是完整生产系统：durable workspace、managed sandbox、identity、billing、observability、evaluation、governance、human handoff。

早期大家拼的是：谁能最快搭一个 Agent loop。现在拼的是：谁能让这个 loop 长期可靠运行。

所以 Agent 平台的竞争，可能不会只发生在模型层，也不会只发生在开发框架层，而会发生在整套 harness 能力上。

谁的执行环境更稳，谁的工具协议更清晰，谁的上下文更不容易漂，谁的 trace 更好用，谁的验证更接近真实任务，谁的权限和审计更可控，谁就更可能把 Agent 送进真实生产流程。

结语：Agent 的下一场竞争，是模型外面的工程

过去，代码是模型的考题。现在，代码正在成为 Agent 的操作系统。

AI Agent 的下一步，不只是让模型更会回答，而是让整个代码化执行过程更可检查、更可恢复、更可治理。

如果你想深入了解 Agent 编排与多智能体协作，可以参考 AI Agent 与多智能体。对于工作流自动化，Workflow 工程实践 提供了更多模式。如果你对模型部署与优化感兴趣，模型部署指南 值得一读。

FAQ

Q1: Agent Harness 和传统的 Prompt Engineering 有什么区别？

Prompt Engineering 解决的是“怎么跟模型说话”，Context Engineering 解决的是“模型该看见什么”，而 Harness Engineering 解决的是“怎么让模型在真实世界里可靠干活”。Harness 是一个包含执行环境、工具接口、上下文管理、生命周期编排、可观测性、验证评估和安全治理的完整工程系统。

Q2: 我的团队只有 2-3 个人，有必要搞这么复杂的 Harness 吗？

有必要，但可以分阶段实施。初期可以先从五层记忆体系（CLAUDE.md）和 Stop Hook 开始，这两项投入小、见效快。随着任务复杂度增加，再逐步引入 Skill 复用、模型路由、HITL 等高级特性。关键是要建立“工程化思维”，而不是等到出大问题再补课。

Q3: 如何评估一个 Harness 的好坏？

可以从三个维度评估：

可靠性：在长任务中，Agent 是否容易“迷失方向”？失败后能否自动恢复？

可观测性：能否追踪每一次模型调用、工具调用、错误和重试？

治理能力：是否对危险操作有拦截和审批机制？权限是否最小化？

一个好的 Harness 应该让 Agent 在“能力”和“控制”之间取得平衡。