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

责编 | 梦依丹

出品 | CSDN（ID：CSDNnews）

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

• 每次开启新会话，AI 就会忘记项目既定的技术栈和代码规范；

• 长对话进行到后期，AI 因为上下文污染和“注意力漂移”变得越来越糊涂，甚至开始原地打转；

• 自动生成的代码因为隐藏的逻辑缺陷或依赖引入，导致 PR 被多次退回。

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

近日，新加坡科技研究局高性能计算研究所 AI 研究员、知名技术作家黄佳（咖哥）走进 CSDN 「AI 进化论」栏目，深入拆解了如何将 Claude Code 从 Demo 推进到产线的完整方法论。

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

本文基于黄佳老师的分享内容，整理了将 Agent 推向生产环境必须跨越的“八道 关卡”及对应的工程设计模式，以飨读者。

核心共识：Agent = Model + Harness

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

Agent=Model+Harness

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

截图自黄佳老师 PPT

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

• “同一模型在不同 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）：

截图自黄佳老师PPT

通过这种分诊调度，例如在排查“订单扣款失败”问题时，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 完成响应并生成完代码之后、准备交付之前触发），让系统自动静默运行单元测试与代码静态检查：

}

如果测试未通过，系统直接阻断本次提交并报错，把结果喂回给 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。

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

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

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

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

针对这个问题，黄佳老师引述了团队核心共创者梁博老师在金融级 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）。

如果您对将 AI 真正引入生产系统、优化研发效能、打通 Harness 工程设计感兴趣，欢迎添加 CSDN 福利官，领取黄佳老师本次分享的 PPT 与直播回放视频。