---
source_url: "https://mp.weixin.qq.com/s/K4c-lFJFjF5ouTXKxw5Shg"
source_type: "wechat-mp"
title: "Claude Code 从 Demo 到产线 · 企业 Harness 工程化的 8 道关卡"
author: "黄佳（咖哥）"
publisher: "CSDN（ID：CSDNnews）"
publisher_secondary: "WeChat 公众号转载"
date: "2026-06-13"
ingested: "2026-06-13"
sha256: "ea69f5cb896091cbdd3306e3ca261d3ec2663f10b4ef004598fc6260b91a5271"
tags: [agent-harness, claude-code, production, context-management, token-routing, skill, hook, hitl, talker-reasoner, adps, csdn, huang-jia]
extraction: "browser"
---

# Claude Code 从 Demo 到产线 · 企业 Harness 工程化的 8 道关卡

> 来源：https://mp.weixin.qq.com/s/K4c-lFJFjF5ouTXKxw5Shg
> 作者：黄佳（咖哥），新加坡科技研究局高性能计算研究所 AI 研究员
> 2026-06-13 14:17 · 江苏
> 责编：梦依丹 · 出品：CSDN（ID：CSDNnews）
> 本文基于黄佳老师在 CSDN「AI 进化论」栏目的分享整理。

## 引言：Demo 惊艳不等于产线可用

在 AI 辅助编程风靡全球的今天，许多开发者都经历过 Vibe Coding 带来的惊艳：输入一行 Prompt，AI 迅速生成一个精美的 Demo。然而，当技术团队试图将这些工具引入复杂的、百万行级代码的企业级生产系统时，往往会面临"硬着陆"的尴尬：

- 每次开启新会话，AI 就会忘记项目既定的技术栈和代码规范；
- 长对话进行到后期，AI 因为上下文污染和"注意力漂移"变得越来越糊涂，甚至开始原地打转；
- 自动生成的代码因为隐藏的逻辑缺陷或依赖引入，导致 PR 被多次退回。

这些痛点说明了一个严峻的事实：AI 编程的瓶颈，已经不再是模型本身的智力，而是工程化能力。

黄佳指出："2025 年我们都在玩 Vibe Coding，而 2026 年，企业真正需要的是 Harness Engineering。"

## 核心共识：Agent = Model + Harness

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

**关键规律**：
- "同一模型在不同 Harness 下的表现差异，远大于不同模型在同一 Harness 下的差距。"
- 在 TerminalBench 基准测试中，仅通过对 Harness 层的优化，就使同一个模型的能力从基线以下跃升至 Top 5；
- Vercel 团队发现，主动剔除 80% 的 Agent 工具后，流程更精简，Token 消耗骤降，响应速度反而更快。

## 第一关：如何让 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**：系统/工具/MCP 注入，必读
- **P1**：项目级硬规范（CLAUDE.md 200~300 行）
- **P2**：相关代码片段
- **P3**：历史工单、长时记忆

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

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

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

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

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

- **反例**：帮我优化这个函数。
- **正例**：优化 `src/utils/parser.ts` 的 `parseConfig` 函数，瓶颈在第 42 行的循环。

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

> "Prompt 是请求，Hook 是契约。"

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

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

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

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

### 痛点
每个开发者都在自己的终端里重复写着类似的代码审查、测试生成等 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 人工审核

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

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

- **只读/低爆炸半径操作**（如查代码、看文档）：自动放行，不中断流程。
- **可写/中等影响操作**：留痕放行，记录全链路的 Keyed log，事后支持完整 replay 溯源。
- **高爆炸半径/不可逆操作**：强制触发阻断，并在控制台弹出 **HITL 人工审核面板**，人手点下确认后，AI 才能继续往下执行。

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

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

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

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

- **Skill = 岗位操作手册**：是静态的、跨任务复用的知识包与 SOP 模板，代表了 Agent 的职业能力。
- **SubAgent = 专职员工**：具备独立的、被隔离的上下文空间，执行完特定任务（如跑个测试、搜个关键字）后即刻销毁，实现防污染。
- **Workflow = SOP 流程图**：将控制流显式、确定性地冻结在代码或脚本中，适用于多步、有着明确目标的长期自动化流程（如 nightly build 代码自动修复）。
- **Agent Team = 持续协作的虚拟团队**：维持长期的、多人的对话交互，各个 Mate 角色拥有持久化 Session。

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

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

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

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

黄佳老师引述了团队核心共创者**梁博**老师在金融级 SaaS 智能体落地中的实践经验。当一个 Agent 需要操作多套系统并维持长周期任务时，传统的混沌上下文极易导致"状态漂移"。

其核心解法是推行**三权分立的状态平面管理**：

- **执行调度平面**：采用 DAG 结构，只记录任务状态与执行流，不掺杂任何自然语言叙事与业务参数。
- **机械参数平面**：严格键值的结构化字典，是业务 API 入参的唯一可审计来源。
- **叙事对齐平面**：采用自然语言记录"目标与进展"，它是防漂移的"防波堤"，包含三个核心：
  - **锚（Anchor）**：锁定用户的原始最终目标，无论中间跳转多少轮，均以此进行校准，防漂移。
  - **账（Ledger）**：里程碑台账，结构化地纪要"做到了哪一步"、"确认了什么"。
  - **集（Collection）**：投影工作集。由于全量状态过大，每一步只给 AI 投影当前该看的、最小的上下文集合，降低检索开销。

此外，引入**草稿纸看板**设计，将 AI 内部的思考流外化成一块可读、可审计、可随时恢复的物理看板，落盘保存。即使某一轮因意外故障导致崩溃，系统也能根据草稿纸记录瞬间恢复状态并继续运行。

## 第八关：从 Demo 到产线，如何合规治理？

### 痛点
能写代码不等于能交付系统，谁来对 AI 的生产出错负责？

### 解法：可观测性 + 来源坐标 + 团队的两条纪律

AI 本身作为概率性模型，无法承担最终的生产安全责任。"背锅"和负责的永远是人。

- **Provenance 来源坐标体系**：对系统中的每一个机械参数进行严格的链路追踪（哪个工具产生、从响应的哪条路径抽取、处于哪一步 turn、由哪个用户输入发起），出事能精准回溯到源头。
- **两条铁的纪律**：
  - **纪律一**：角色规则前置，别等出事再通过 Prompt 去补，必须写进 Skill 或 `agent.md`。
  - **纪律二**：实行 **Pre-task gating**。在 AI 动手写代码前，强迫其先进行评估，说出"要做好这件事，我还需要补充什么信息、明确哪些问题"。不评估，不准写代码。

## 尾声

从 Vibe Coding 的热闹，走到 Harness Engineering 的严谨，这是 Agent 工业化落地的必经之路。

为了让这些踩坑得来的经验重新回到团队层面，黄佳老师联合业内在软件工程、长程多智能体编排以及企业级落地有着丰富经验的资深专家（**茹炳晟、姜宁、梁博**），共同发起了 **Agent 设计模式共同体**（**Agent Design Patterns Society, 简称 ADPS**）。