title: 第 28 讲 · Agent 工程范式Harness Engineering 到底革新了什么课程导航 « 第 27 讲 · 第 29 讲 »第 28 讲 · Agent 工程范式Harness Engineering 到底革新了什么热点加餐第 28 / 33 讲Claude Code 工程化实战范式 3.0Harness 本讲摘要· Harness Engineering 是 2025-2026 年 AI 工程领域最被低估的范式跃迁——它把 Agent 从调一个模型重新定义为运行一个系统。本讲从范式演进史Prompt Engineering → Agent Engineering → Harness Engineering出发、系统讲清楚 Harness 是什么、7 层架构长什么样、5 大设计原则如何在工程里落地、并用 200 行最小 Harness 演示让你跑通从想法到运行的完整闭环。学完本讲、你应该能用 Harness 思维重新审视 Claude Code / 任何 Agent 产品的设计选择、而不是只把它当高级 prompt 工具。1. 范式演进史从 Prompt 到 HarnessAI 工程 5 年走完了 3 个范式跃迁、每个范式回答的核心问题不一样范式时间核心问题代表工作范式局限1.0 · Prompt Engineering2022-2023怎么让模型听懂我few-shot、CoT、ReAct换个模型就失效2.0 · Agent Engineering2024怎么让模型能动手Tool use、Function calling行为边界不清晰、容易失控3.0 · Harness Engineering2025-2026怎么让系统在边界内跑得稳Claude Code、OpenClaw工程复杂度高、需要团队关键洞察3 个范式不是取代、而是叠加。Prompt 仍然是 Harness 的一部分、Agent 仍然是 Harness 的一部分。Harness 是把它们装进一个可治理系统的元范式。⚠️ 坑 1· 以为 3.0 取代 1.0 / 2.0——不3.0 是在 1.0 2.0 之上加了一个治理层。写好 Harness 里的 system prompt、仍然要懂 Prompt Engineering选好 Harness 里的 tool schema、仍然要懂 Agent Engineering。2. Harness 是什么包裹模型的工程骨架**Harness Engineering驾驭工程**是把模型装进可治理系统的工程范式——管理上下文、调度工具、设边界、做可观测——让 Agent 在可控、可复现、可演化的方式下稳定运行。它把 Agent 当作完整的产品来对待、而不是一个裸露的模型调用。该概念在 2025 年随着 Claude Code 的工程化实践被业界广泛接受。用一个比喻Harness 是 Agent 的骨架 神经系统 边界护栏、模型是心脏。没有 Harness、模型就是一堆漂浮的智能有了 Harness、模型才能在工程里稳定工作。具体说、Harness 包含 6 个组件System Prompt定义 Agent 的人格和工作守则Tool Schema定义 Agent 能调的工具集白盒化Memory短期上下文 长期记忆 项目记忆Control Loop主循环——读消息 → 思考 → 调工具 → 写回复Boundary权限 / 风险 / PII 等边界护栏Observability日志 / 监控 / 审计 / 计费Claude Code 之所以工程化、就是因为这 6 个组件都做齐了。对比之下、直接调用client.messages.create()那种裸模型路线、缺了 5 个组件、只在 demo 阶段能用。3. 7 层架构图从模型到用户的完整抽象把 Harness 拆成 7 层、从底向上是7 层各自独立可替换——换模型Claude → Gemini只改 L1换通道CLI → Telegram只改 L6换 Orchestrator单 Agent → 多 Agent只改 L5。这正是 Harness 范式的可演化价值不绑死在某一家、某一端。4. 5 大设计原则可观测 / 可控制 / 可演化 / 可分享 / 可测试做 Harness 容易、做好 Harness 难。5 大设计原则是判断 Harness 质量的尺子原则含义反例正例可观测每次行为都能被记录、回放Agent 调了什么我也不知道PostToolUse 落 JSON Lines、可重放可控制用户能随时介入、终止、回滚Agent 跑了 30 分钟我只能等支持 /rewind、中断、Checkpointing可演化Skills / Tools / Hooks 可热加载加个 Skill 要重启 3 个服务Skill 描述加进 CLAUDE.md 即生效可分享团队成员能复用你的 Harness 资产我配的 Skills 你那边跑不通Plugin 打包 Marketplace 共享可测试Agent 行为有自动化测试Agent 改坏了文件我才知道评估集eval 快照测试用这 5 条对照 Claude Code、你会发现它每条都做了 60-80 分——这正是它能工程化的原因。把这 5 条做到 90 分、就是企业级 Harness 的标准。⚠️ 坑 2· 只追功能多、不追可观测与可控制——Harness 的价值不是多能干、而是出问题时能不能 5 分钟内定位 1 分钟内止血。事故驱动的设计比功能驱动的设计重要 10 倍。5. 200 行最小 Harness 演示理论再多不如一行代码。下面是一个最小可运行的 Harness约 200 行 TypeScript实战代码块 1 — 最小 Harness 完整实现。能跑通用户输入 → 调模型 → 调工具 → 返回结果 完整闭环。// minimal-harness.ts (200 行) import Anthropic from anthropic-ai/sdk; import * as readline from readline; import { execSync } from child_process; import { readFileSync, writeFileSync } from fs; // L1: Model Adapter const client new Anthropic(); // L3: Tool Layer (白盒化) const TOOLS [ { name: Bash, description: 执行 shell 命令,返回 stdout/stderr。危险命令会被拦截。, input_schema: { type: object, properties: { command: { type: string } }, required: [command] } }, { name: Read, description: 读取文件内容,返回带行号的文本。, input_schema: { type: object, properties: { file_path: { type: string } }, required: [file_path] } }, { name: Edit, description: 编辑文件,old_text 必须唯一匹配。, input_schema: { type: object, properties: { file_path: { type: string }, old_text: { type: string }, new_text: { type: string } }, required: [file_path, old_text, new_text] } } ]; // L3: Tool Implementation function executeTool(name: string, input: any): string { // L2: Boundary - 黑名单 if (name Bash /rm -rf|sudo|dd |mkfs/.test(input.command) { return ❌ 拒绝执行危险命令; } // L2: Boundary - PII 脱敏 if (/\b1[3-9][0-9]{9}\b/.test(JSON.stringify(input) { return ❌ 检测到 PII,已拦截; } if (name Bash) { try { return execSync(input.command, { encoding: utf-8, timeout: 10000 }); } catch (e: any) { return Error: ${e.message}; } } if (name Read) { return readFileSync(input.file_path, utf-8); } if (name Edit) { const content readFileSync(input.file_path, utf-8); if (!content.includes(input.old_text) return ❌ old_text 不存在; writeFileSync(input.file_path, content.replace(input.old_text, input.new_text); return ✓ 已修改; } return Unknown tool; } // L4: Memory Store (短期) const messages: any[] []; const SYSTEM_PROMPT 你是 Claude Code 风格的 Agent,可以用工具帮用户工作。回答简洁,先想再动手。; // L5: Orchestrator (主循环) async function runTurn(userMessage: string) { messages.push({ role: user, content: userMessage }); for (let i 0; i 10; i) { const response await client.messages.create({ model: claude-sonnet-4-7, max_tokens: 4096, system: SYSTEM_PROMPT, tools: TOOLS, messages }); messages.push({ role: assistant, content: response.content }); if (response.stop_reason end_turn) { return response.content.filter(b: any) b.type text).map(b: any) b.text).join(\n); } // 工具调用 const toolUse response.content.find(b: any) b.type tool_use); if (toolUse) { const result executeTool(toolUse.name, toolUse.input); messages.push({ role: user, content: [{ type: tool_result, tool_use_id: toolUse.id, content: result }] }); } } return 达到最大轮数,停止; } // L6 L7: Channel UI (CLI) const rl readline.createInterface({ input: process.stdin, output: process.stdout }); const ask (q: string) new Promisestring(r) rl.question(q, r); (async () { console.log(Minimal Harness ready. 输入 exit 退出。); while (true) { const input await ask(\n ); if (input exit) break; const result await runTurn(input); console.log(\n result); } })();这个 Harness 包含 L1-L7 中的 6 层L6 channel 简化成 stdin、约 200 行。把它跑起来、就是一个能调 Claude 调工具 有边界护栏的最小 Agent。想学 Harness 演进、从这里开始改加L4 长期记忆把对话摘要写进.claude/memory.md、下次启动读回来加L5 子代理把调工具改成 Task tool 调子代理加L6 Channel用 Telegraf 库挂 Telegram bot加Skills 注册从.claude/skills/读 SKILL.md 描述、塞进 system prompt加L2 HooksPreToolUse 调 PII 脱敏 hook每加一层、Harness 就向 Claude Code 近一步。⚠️ 坑 3· 抄完 200 行就跑——没有改、没有测、没有部署。Harness 的学习不是读懂、而是改 3 个版本后你才真的懂。6. Harness 思维如何反哺日常开发学完 Harness、回过头来用它审视日常开发、会看到一些以前觉得理所当然的事其实有更好的解法实战代码块 2 — 用 Harness 思维重构一个传统 CLI 工具。比如一个传统代码生成器工具、以前是参数驱动Harness 化后是 Agent 驱动# 传统 CLI 工具(参数驱动) $ gen-component --name Button --type functional --style css # 输出:一堆文件,需要人工看是不是想要的 # Harness 化后(Agent 驱动) $ gen-component 我要一个 React Button 组件,支持 primary/secondary 两种风格 # Agent 自己决定:用什么库、什么 props、什么样式、要不要 test # 还能追问:Button 要不要带 icon?要不要支持 disabled 状态?对比之下、Harness 化的工具更像在跟一个同事对话、而不是在用一台机器。这正是 Harness 范式想带给大家的东西从工具升级为伙伴。反哺日常开发的 3 个具体动作把脚本改成 Agent你常用的 5 个 shell 脚本、挑 1 个改成 Agent 能调的工具、放进.claude/skills/把 CLI 工具加 Harness 化你写的 1 个 CLI 工具、加一个简单的对话模式——输入一句话、工具解读后执行把团队约定写进 CLAUDE.md把团队的代码规范 / Git 流程 / 部署命令写进 CLAUDE.md、让 Agent 替你守规矩⚠️ 坑 4· 觉得 Harness 离自己很远——我又不是做 Agent 产品的。其实任何接受输入、产出结果的工具、都可以 Harness 化。哪怕是一个部署脚本、加了 Agent 化后都能省 50% 的手工操作。7. 范式还在演进Loop Engineering 正在兴起本讲写于 2026 年初——彼时 Harness Engineering 已随着 Claude Code 的普及成为业界共识但 Agent 工程范式的演进并未就此停步。2026 年上半年**Loop Engineering循环工程**正在成为新的方向把 Harness 的主循环升级成多 Agent 协作 长时记忆 自动评估的闭环让 Agent 具备自我迭代能力。几个值得关注的方向长时记忆突破单次会话边界、让 Agent 跨任务记住上次学到的教训自动评估Agent 每次跑完、自动生成评估报告、驱动下一步改进多 Agent 协作从一个 Agent 一杆枪到多个 Agent 分工 互相校验自我修复检测到行为漂移后、自动回滚 重试 报警这意味着 Agent 工程范式仍在快速演进——Harness Engineering 是当下、Loop Engineering 是下一个浪尖。保持对范式跃迁的敏感度、才能不被技术更替甩在身后。8. 一句话备忘 未来不是更大的模型、而是更聪明的 Harness下一步不是更长的上下文、而是更聪明的循环。
《Claude Code 工程化实战》第 28 讲 Agent 工程范式
title: 第 28 讲 · Agent 工程范式Harness Engineering 到底革新了什么课程导航 « 第 27 讲 · 第 29 讲 »第 28 讲 · Agent 工程范式Harness Engineering 到底革新了什么热点加餐第 28 / 33 讲Claude Code 工程化实战范式 3.0Harness 本讲摘要· Harness Engineering 是 2025-2026 年 AI 工程领域最被低估的范式跃迁——它把 Agent 从调一个模型重新定义为运行一个系统。本讲从范式演进史Prompt Engineering → Agent Engineering → Harness Engineering出发、系统讲清楚 Harness 是什么、7 层架构长什么样、5 大设计原则如何在工程里落地、并用 200 行最小 Harness 演示让你跑通从想法到运行的完整闭环。学完本讲、你应该能用 Harness 思维重新审视 Claude Code / 任何 Agent 产品的设计选择、而不是只把它当高级 prompt 工具。1. 范式演进史从 Prompt 到 HarnessAI 工程 5 年走完了 3 个范式跃迁、每个范式回答的核心问题不一样范式时间核心问题代表工作范式局限1.0 · Prompt Engineering2022-2023怎么让模型听懂我few-shot、CoT、ReAct换个模型就失效2.0 · Agent Engineering2024怎么让模型能动手Tool use、Function calling行为边界不清晰、容易失控3.0 · Harness Engineering2025-2026怎么让系统在边界内跑得稳Claude Code、OpenClaw工程复杂度高、需要团队关键洞察3 个范式不是取代、而是叠加。Prompt 仍然是 Harness 的一部分、Agent 仍然是 Harness 的一部分。Harness 是把它们装进一个可治理系统的元范式。⚠️ 坑 1· 以为 3.0 取代 1.0 / 2.0——不3.0 是在 1.0 2.0 之上加了一个治理层。写好 Harness 里的 system prompt、仍然要懂 Prompt Engineering选好 Harness 里的 tool schema、仍然要懂 Agent Engineering。2. Harness 是什么包裹模型的工程骨架**Harness Engineering驾驭工程**是把模型装进可治理系统的工程范式——管理上下文、调度工具、设边界、做可观测——让 Agent 在可控、可复现、可演化的方式下稳定运行。它把 Agent 当作完整的产品来对待、而不是一个裸露的模型调用。该概念在 2025 年随着 Claude Code 的工程化实践被业界广泛接受。用一个比喻Harness 是 Agent 的骨架 神经系统 边界护栏、模型是心脏。没有 Harness、模型就是一堆漂浮的智能有了 Harness、模型才能在工程里稳定工作。具体说、Harness 包含 6 个组件System Prompt定义 Agent 的人格和工作守则Tool Schema定义 Agent 能调的工具集白盒化Memory短期上下文 长期记忆 项目记忆Control Loop主循环——读消息 → 思考 → 调工具 → 写回复Boundary权限 / 风险 / PII 等边界护栏Observability日志 / 监控 / 审计 / 计费Claude Code 之所以工程化、就是因为这 6 个组件都做齐了。对比之下、直接调用client.messages.create()那种裸模型路线、缺了 5 个组件、只在 demo 阶段能用。3. 7 层架构图从模型到用户的完整抽象把 Harness 拆成 7 层、从底向上是7 层各自独立可替换——换模型Claude → Gemini只改 L1换通道CLI → Telegram只改 L6换 Orchestrator单 Agent → 多 Agent只改 L5。这正是 Harness 范式的可演化价值不绑死在某一家、某一端。4. 5 大设计原则可观测 / 可控制 / 可演化 / 可分享 / 可测试做 Harness 容易、做好 Harness 难。5 大设计原则是判断 Harness 质量的尺子原则含义反例正例可观测每次行为都能被记录、回放Agent 调了什么我也不知道PostToolUse 落 JSON Lines、可重放可控制用户能随时介入、终止、回滚Agent 跑了 30 分钟我只能等支持 /rewind、中断、Checkpointing可演化Skills / Tools / Hooks 可热加载加个 Skill 要重启 3 个服务Skill 描述加进 CLAUDE.md 即生效可分享团队成员能复用你的 Harness 资产我配的 Skills 你那边跑不通Plugin 打包 Marketplace 共享可测试Agent 行为有自动化测试Agent 改坏了文件我才知道评估集eval 快照测试用这 5 条对照 Claude Code、你会发现它每条都做了 60-80 分——这正是它能工程化的原因。把这 5 条做到 90 分、就是企业级 Harness 的标准。⚠️ 坑 2· 只追功能多、不追可观测与可控制——Harness 的价值不是多能干、而是出问题时能不能 5 分钟内定位 1 分钟内止血。事故驱动的设计比功能驱动的设计重要 10 倍。5. 200 行最小 Harness 演示理论再多不如一行代码。下面是一个最小可运行的 Harness约 200 行 TypeScript实战代码块 1 — 最小 Harness 完整实现。能跑通用户输入 → 调模型 → 调工具 → 返回结果 完整闭环。// minimal-harness.ts (200 行) import Anthropic from anthropic-ai/sdk; import * as readline from readline; import { execSync } from child_process; import { readFileSync, writeFileSync } from fs; // L1: Model Adapter const client new Anthropic(); // L3: Tool Layer (白盒化) const TOOLS [ { name: Bash, description: 执行 shell 命令,返回 stdout/stderr。危险命令会被拦截。, input_schema: { type: object, properties: { command: { type: string } }, required: [command] } }, { name: Read, description: 读取文件内容,返回带行号的文本。, input_schema: { type: object, properties: { file_path: { type: string } }, required: [file_path] } }, { name: Edit, description: 编辑文件,old_text 必须唯一匹配。, input_schema: { type: object, properties: { file_path: { type: string }, old_text: { type: string }, new_text: { type: string } }, required: [file_path, old_text, new_text] } } ]; // L3: Tool Implementation function executeTool(name: string, input: any): string { // L2: Boundary - 黑名单 if (name Bash /rm -rf|sudo|dd |mkfs/.test(input.command) { return ❌ 拒绝执行危险命令; } // L2: Boundary - PII 脱敏 if (/\b1[3-9][0-9]{9}\b/.test(JSON.stringify(input) { return ❌ 检测到 PII,已拦截; } if (name Bash) { try { return execSync(input.command, { encoding: utf-8, timeout: 10000 }); } catch (e: any) { return Error: ${e.message}; } } if (name Read) { return readFileSync(input.file_path, utf-8); } if (name Edit) { const content readFileSync(input.file_path, utf-8); if (!content.includes(input.old_text) return ❌ old_text 不存在; writeFileSync(input.file_path, content.replace(input.old_text, input.new_text); return ✓ 已修改; } return Unknown tool; } // L4: Memory Store (短期) const messages: any[] []; const SYSTEM_PROMPT 你是 Claude Code 风格的 Agent,可以用工具帮用户工作。回答简洁,先想再动手。; // L5: Orchestrator (主循环) async function runTurn(userMessage: string) { messages.push({ role: user, content: userMessage }); for (let i 0; i 10; i) { const response await client.messages.create({ model: claude-sonnet-4-7, max_tokens: 4096, system: SYSTEM_PROMPT, tools: TOOLS, messages }); messages.push({ role: assistant, content: response.content }); if (response.stop_reason end_turn) { return response.content.filter(b: any) b.type text).map(b: any) b.text).join(\n); } // 工具调用 const toolUse response.content.find(b: any) b.type tool_use); if (toolUse) { const result executeTool(toolUse.name, toolUse.input); messages.push({ role: user, content: [{ type: tool_result, tool_use_id: toolUse.id, content: result }] }); } } return 达到最大轮数,停止; } // L6 L7: Channel UI (CLI) const rl readline.createInterface({ input: process.stdin, output: process.stdout }); const ask (q: string) new Promisestring(r) rl.question(q, r); (async () { console.log(Minimal Harness ready. 输入 exit 退出。); while (true) { const input await ask(\n ); if (input exit) break; const result await runTurn(input); console.log(\n result); } })();这个 Harness 包含 L1-L7 中的 6 层L6 channel 简化成 stdin、约 200 行。把它跑起来、就是一个能调 Claude 调工具 有边界护栏的最小 Agent。想学 Harness 演进、从这里开始改加L4 长期记忆把对话摘要写进.claude/memory.md、下次启动读回来加L5 子代理把调工具改成 Task tool 调子代理加L6 Channel用 Telegraf 库挂 Telegram bot加Skills 注册从.claude/skills/读 SKILL.md 描述、塞进 system prompt加L2 HooksPreToolUse 调 PII 脱敏 hook每加一层、Harness 就向 Claude Code 近一步。⚠️ 坑 3· 抄完 200 行就跑——没有改、没有测、没有部署。Harness 的学习不是读懂、而是改 3 个版本后你才真的懂。6. Harness 思维如何反哺日常开发学完 Harness、回过头来用它审视日常开发、会看到一些以前觉得理所当然的事其实有更好的解法实战代码块 2 — 用 Harness 思维重构一个传统 CLI 工具。比如一个传统代码生成器工具、以前是参数驱动Harness 化后是 Agent 驱动# 传统 CLI 工具(参数驱动) $ gen-component --name Button --type functional --style css # 输出:一堆文件,需要人工看是不是想要的 # Harness 化后(Agent 驱动) $ gen-component 我要一个 React Button 组件,支持 primary/secondary 两种风格 # Agent 自己决定:用什么库、什么 props、什么样式、要不要 test # 还能追问:Button 要不要带 icon?要不要支持 disabled 状态?对比之下、Harness 化的工具更像在跟一个同事对话、而不是在用一台机器。这正是 Harness 范式想带给大家的东西从工具升级为伙伴。反哺日常开发的 3 个具体动作把脚本改成 Agent你常用的 5 个 shell 脚本、挑 1 个改成 Agent 能调的工具、放进.claude/skills/把 CLI 工具加 Harness 化你写的 1 个 CLI 工具、加一个简单的对话模式——输入一句话、工具解读后执行把团队约定写进 CLAUDE.md把团队的代码规范 / Git 流程 / 部署命令写进 CLAUDE.md、让 Agent 替你守规矩⚠️ 坑 4· 觉得 Harness 离自己很远——我又不是做 Agent 产品的。其实任何接受输入、产出结果的工具、都可以 Harness 化。哪怕是一个部署脚本、加了 Agent 化后都能省 50% 的手工操作。7. 范式还在演进Loop Engineering 正在兴起本讲写于 2026 年初——彼时 Harness Engineering 已随着 Claude Code 的普及成为业界共识但 Agent 工程范式的演进并未就此停步。2026 年上半年**Loop Engineering循环工程**正在成为新的方向把 Harness 的主循环升级成多 Agent 协作 长时记忆 自动评估的闭环让 Agent 具备自我迭代能力。几个值得关注的方向长时记忆突破单次会话边界、让 Agent 跨任务记住上次学到的教训自动评估Agent 每次跑完、自动生成评估报告、驱动下一步改进多 Agent 协作从一个 Agent 一杆枪到多个 Agent 分工 互相校验自我修复检测到行为漂移后、自动回滚 重试 报警这意味着 Agent 工程范式仍在快速演进——Harness Engineering 是当下、Loop Engineering 是下一个浪尖。保持对范式跃迁的敏感度、才能不被技术更替甩在身后。8. 一句话备忘 未来不是更大的模型、而是更聪明的 Harness下一步不是更长的上下文、而是更聪明的循环。
