1.5 Harness 架构深度解析：Claude Code 为什么强？

Harness 架构深度解析Claude Code 为什么强[进阶选读]本篇深度解析 Claude Code 的底层架构设计。如果你的目标是快速上手用好 Claude Code可以先跳过等用顺手之后再回来读。读完之后你对 CLAUDE.md、Hooks、MCP 的理解会上一个台阶——知道自己在调什么而不只是知道怎么调。时效说明本文内容以 2026 年 3 月为基准。很多人都问过这样一个问题Claude Code 最懂工程究竟强在哪里这个问题背后还有另一个问题同样是调用 Claude 模型为什么 Claude Code 能做到裸 API 做不到的事答案只有一个词Harness。先做一个对比实验感受 Harness 的存在。用裸 API 和 Claude Code 分别执行同一个任务# 方式一裸 API 调用没有 Harnesscurlhttps://api.deepseek.com/v1/chat/completions\-HAuthorization: Bearer$DEEPSEEK_API_KEY\-HContent-Type: application/json\-d{ model: deepseek-chat, messages: [{role:user,content:找出当前目录下所有 TODO 注释并列出文件名和行号}] }# 方式二通过 Claude Code有 Harnessclaude-p找出当前目录下所有 TODO 注释并列出文件名和行号--output-format text裸 API 的回答它会告诉你你可以用grep -rn TODO .命令来搜索——因为它没有手脚只能说。Claude Code 的回答它会直接执行Grep工具搜索 TODO返回完整的文件名、行号和上下文——因为 Harness 给了它行动的能力。同一个大脑有没有 Harness结果天壤之别。同一个模型有无 Harness 的能力差距——左侧只能说右侧能干活8.1 Harness 是什么Anthropic 官方文档给出了这样的定义Claude Code serves as the agentic harness around Claude: it provides the tools, context management, and execution environment that turn a language model into a capable coding agent.Claude Code 是包裹在 Claude 模型外面的智能体编排框架提供工具、上下文管理和执行环境把一个语言模型变成有能力的编码 Agent。注意这个定义里的三个关键词工具、上下文管理、执行环境。模型本身只会生成文本。是 Harness 给了它读文件的能力、写代码的能力、搜索代码库的能力、在终端执行命令的能力。没有 HarnessClaude 就是一个只会说话的大脑——有智力没有手脚。业界对 Harness 的核心共识是Agent Harness 包裹 LLM 的运行时基础设施管理工具调度、上下文工程、安全执行、状态持久化和会话连续性。LLM 只负责推理决策。2026 年的关键洞察竞争差异化的重心已从 Model 转移到 Harness。同一个模型在不同 Harness 中的表现差距远大于不同模型在同一个 Harness 中的差距。8.2 Harness 的五个组件Agent Model Harness。模型是核心但它不能独立行动。真正让它变成 Agent 的是包裹在它周围的五个 Harness 组件。┌─────────────────────────────────────────────────────┐ │ Harness │ │ │ │ ┌─────────┐ ┌──────────┐ ┌───────────┐ │ │ │ Tools │ │ Context │ │ Memory │ │ │ │ (手脚) │ │ (记忆 │ │ (长期存储)│ │ │ │ │ │ 加载器) │ │ │ │ │ └────┬────┘ └────┬─────┘ └─────┬─────┘ │ │ │ │ │ │ │ └──────────────┼────────────────┘ │ │ │ │ │ ┌────────▼────────┐ │ │ │ Model │ │ │ │ (推理决策) │ │ │ └────────┬────────┘ │ │ │ │ │ ┌──────────────┼────────────────┐ │ │ │ │ │ │ │ ┌────▼────┐ ┌────▼─────┐ │ │ │ │ Hooks │ │Permissions│ │ │ │ │ (神经 │ │ (安全 │ │ │ │ │ 反射) │ │ 围栏) │ │ │ │ └─────────┘ └──────────┘ │ │ └─────────────────────────────────────────────────────┘模型不直接接触外部世界所有交互都通过 Harness 的组件中转。Harness 是模型和现实之间的唯一接口。Harness 整体架构——Model 居中五个组件Tools/Context/Memory/Hooks/Permissions环绕共同构成完整的 Agent 运行环境8.2.1 Tools模型的手脚Read、Write、Edit、Bash、Grep……这些工具赋予模型与文件系统、终端、网络交互的能力。没有工具模型只能说不能做。Claude Code 内置了 20 个工具覆盖软件工程的五个原子操作原子操作代表工具能做什么读Read、Glob、Grep读文件、搜索内容、匹配路径写Write、Edit、NotebookEdit创建/修改文件执行Bash运行任何 Shell 命令联网WebFetch、WebSearch查资料、抓页面编排Task启动子 Agent 并行工作工具设计背后有一个深刻的哲学——少而精。Claude Code 没有内置重构工具、测试工具、部署工具它只给了最基础的原语。重构是 Read Edit Bash 的组合涌现测试是 Bash Read 的组合涌现部署还是 Bash。这就像计算机只需要几条指令就能图灵完备一样。Harness 不需要为每种场景造一个工具它只需要确保基础工具的组合空间足够大。Bash 是个例外。Bash 工具是一个图灵完备的逃逸舱——通过它Claude 可以执行任何 Shell 命令安装依赖、运行测试、调用 API、操作数据库。这意味着 Claude Code 的能力上限理论上等于操作系统的能力上限。这也是为什么 Harness 需要权限控制的原因。8.2.2 Context模型的记忆加载器CLAUDE.md、系统提示词、对话历史、工具定义——这些上下文在每一轮循环中被注入模型决定了模型看到什么、知道什么。上下文管理的精妙之处是它不只是被动的信息传递还包括主动的压缩和重注入策略详见 8.4 节。8.2.3 Memory模型的长期存储跨会话的记忆持久化让模型能记住你的偏好、项目规则和历史决策。CLAUDE.md显式记忆你主动写进去的规则和背景~/.claude/memory/隐式记忆Claude 自动积累的项目知识没有 Memory每次对话都从零开始。有了 MemoryClaude 知道你的项目用什么框架、代码风格是什么、有哪些约定不能违反。8.2.4 Hooks模型的神经反射事件驱动的自动化机制在工具执行前后触发自定义逻辑。比如每次保存文件前自动格式化每次提交前自动运行 lint每次 Bash 命令执行后自动记录日志Hooks 让 Harness 有了条件反射的能力——不需要模型主动决策某些行为会自动发生。8.2.5 Permissions模型的安全围栏哪些工具可以自由使用哪些需要人工审批哪些完全禁止——权限系统是 Harness 的安全底线。它解决了一个核心矛盾你希望 Agent 足够自主以提高效率但又不希望它自主到失控。8.3 Agentic LoopHarness 的心脏如果 Harness 是一台机器Agentic Loop 就是它的发动机。整个 Claude Code 的运转归根到底就是一个循环① 用户输入任务 │ ▼ ② 模型推理该做什么需要哪个工具 │ ▼ ③ 执行工具读文件/写代码/运行命令 │ ▼ ④ 工具结果回注到上下文 │ ▼ ⑤ 模型继续推理任务完成了吗 │ ┌───┴───┐ 完成 未完成 │ │ ▼ └──→ 回到 ② ⑥ 输出最终回复关键点在于步骤 ② 和步骤 ④ 之间的循环。模型不是一次性给出最终答案的。它可能先读一个文件看完结果后决定再搜索一下搜索完又决定编辑某行代码编辑完再运行测试——每一步都是一次循环。一个复杂任务可能跑几十轮循环。Agentic Loop 完整流程——从用户输入到任务完成中间经历推理→工具执行→结果回注的多次循环循环什么时候结束满足下面两个条件之一模型主动停止Claude 认为任务完成生成纯文本回复不再请求工具调用。API 返回stop_reason: end_turn。达到最大轮次Harness 设置了--max-turns限制防止无限循环。这就是为什么有时候 Claude 花了 20 秒还没给你回答——它在认真跑循环不是卡住了。8.4 上下文管理被低估的关键能力大多数人讨论 Agent 框架时只关心工具和循环。但 Harness 最精巧的部分其实是上下文管理。Claude 的上下文窗口是有限的200K tokens。一个真实的编码任务——读 20 个文件、搜索 50 次、执行 30 条命令——产生的对话历史会迅速膨胀到几十万 tokens。如果不管理要么爆掉上下文窗口要么模型开始遗忘早期信息。Claude Code 的解决方案是自动压缩。当对话历史接近上下文窗口的 92% 时Harness 会触发一次压缩操作对话历史180K tokens │ ▼ 压缩触发92% 阈值 ┌────────────────────────────────┐ │ 保留最近的消息完整 │ │ 压缩早期消息 → 摘要 │ │ 重注入CLAUDE.md 内容 │ │ 重注入系统提示词 │ │ 重注入工具定义 │ └────────────────────────────────┘ │ ▼ 压缩后对话历史~80K tokens │ ▼ 继续工作注意最后三行——CLAUDE.md、系统提示词、工具定义在每次压缩后都会重新注入。这意味着即使对话历史被截断了模型仍然知道项目的规则、自己有哪些工具、应该遵循什么约定。这就是为什么你在 CLAUDE.md 里写的东西那么持久——不是因为模型记住了它而是 Harness 在每次压缩后都重新塞给模型。理解了这个机制你就知道 CLAUDE.md 应该写什么不是写你好我叫张三这类一次性信息而是写每次压缩后都需要重新提醒模型的项目规则和约定。8.5 开源还是闭源一个被误解的事实很多人以为 Claude Code 是开源的。毕竟它在 GitHub 上有一个仓库github.com/anthropics/claude-code截至 2026 年 3 月已有 81K stars。但打开仓库的 LICENSE 文件你会看到© Anthropic PBC. All rights reserved. Use is subject to Anthropics Commercial Terms of Service.Claude Code 不是开源软件它是专有软件。GitHub 仓库里有什么安装脚本、插件模板、GitHub Action、文档、示例配置。核心的 Agentic Loop、工具执行引擎、上下文管理器——这些 Harness 的核心代码——以编译后的 npm 包anthropic-ai/claude-code分发源码并不可见。2026 年 1 月GitHub 上出现了一个 issue#22002请求 Anthropic 将 Claude Code CLI 以 Apache 2.0 或 MIT 许可证开源。截至目前这个 issue 仍然是 Open 状态。8.6 Claude Agent SDK可编程的 Harness虽然 Claude Code CLI 本身不开源但 Anthropic 在 2025 年发布了Claude Agent SDK——一套可编程的 Harness 接口。# TypeScript 版本npminstallanthropic-ai/claude-agent-sdk# Python 版本pipinstallclaude-agent-sdkAgent SDK 提供了与 Claude Code 完全相同的 Agentic Loop、内置工具、上下文管理、权限系统、Hooks、Sub-Agent 支持和 MCP 集成。区别在于Claude Code 是面向终端用户的交互式产品Agent SDK 是面向开发者的编程库。用 Agent SDK你可以构建自己的 Harness——一个定制化的 Agent 应用嵌入到你自己的产品、工作流或 CI/CD 系统中fromclaude_agent_sdkimportAgentClient clientAgentClient(api_key...)# 创建一个有工具能力的 Agentresultclient.run(prompt审查这个 PR 的安全问题,tools[Read,Grep,Glob,Bash],max_turns20,allowed_tools{Bash:[npm test,npm run lint]}# 只允许特定命令)print(result.text)如果说 Claude Code 是一辆出厂配置的整车Agent SDK 就是发动机总成——你可以把它装进任何车身里。8.7 Harness 生态竞争与张力Claude Code 的成功证明了一件事模型 Harness 10× 生产力。这个公式吸引了大量第三方工具来构建自己的 Harness。截至 2026 年 3 月主要 Harness 产品格局产品定位特点Claude Code官方 CLI深度集成 ClaudeHarness 最完整OpenCode前 SST第三方多平台Client-Server 架构119K stars月活 65 万CursorIDE 集成编辑器原生体验支持多模型WindsurfIDE 集成Codeium 出品强调 Flow 模式Codex CLIOpenAI 官方对标 Claude Code2026 年发布OpenCode 的故事值得一说。它用 Client-Server 架构解决了 Claude Code 的单表面局限——TUI、桌面 App、IDE 插件、Slack 机器人共享同一个后端。截至 2026 年 3 月OpenCode 的 GitHub star 数超过了 Claude Code 本身。但 2026 年 1 月Anthropic 采取了一个争议性举措封堵了第三方工具通过消费者 OAuth Token 调用 Claude API 的通道。这直接影响了 OpenCode、Cursor、Windsurf 等工具的用户——他们之前可以用 Claude Pro 订阅的 Token 在这些第三方工具里使用 Claude封堵后必须购买独立的 API Key。这件事揭示了 Harness 生态的核心张力模型提供商希望控制 Harness 层因为 Harness 决定了 API 调用量和用户体验第三方 Harness希望模型层是可替换的商品因为这样它们才能建立独立的价值这个张力不会消失它会持续塑造整个 AI 工具生态的格局。8.8 为什么 2026 年是 Harness 之年2025 年的关键词是 Agent。2026 年的关键词是Agent Harness。为什么因为行业已经意识到模型本身正在商品化——Claude、GPT、Gemini、DeepSeek 的能力差距在缩小。但同一个模型在不同 Harness 中的表现差距远大于不同模型在同一个 Harness 中的差距。几个佐证数据点Claude Code 在 2025 年 11 月达到10 亿美元年化收入——这是一个 Harness 产品的收入不是模型本身的收入Anthropic 在 2026 年 3 月收购了BunJavaScript 运行时明确表示要加强 Claude Code 的基础设施。收购一个运行时来加强一个 Harness——这说明 Anthropic 把 Harness 视为战略级资产开源社区出现了Agent Harness作为独立品类GitHub 上以 “harness” 为关键词的新仓库数量在 2026 年 Q1 翻了三倍对我们开发者来说这意味着什么理解 Harness 比理解模型更重要。模型的能力由 Anthropic/OpenAI 决定你无法改变。但 Harness 的配置——CLAUDE.md 怎么写、工具权限怎么设、Hooks 怎么接、MCP 怎么连——这些全在你手中。你在这门课里学的每一讲本质上都是在调教 Harness。8.9 小结核心要点一句话总结Harness 是什么包裹 LLM 的运行时基础设施把模型的智力转化为行动力五个组件Tools手脚、Context记忆加载器、Memory长期存储、Hooks神经反射、Permissions安全围栏Agentic Loop推理 → 工具调用 → 结果回注 → 继续推理复杂行为从循环中涌现上下文压缩92% 阈值触发压缩CLAUDE.md 在每次压缩后重新注入——这就是它持久的原因开源误解Claude Code 核心代码闭源GitHub 仓库只有脚本和文档Agent SDK可编程的 Harness 接口用于构建定制化 Agent 应用Harness Model同一模型在不同 Harness 中的差距大于不同模型在同一 Harness 中的差距思考题如果你要为自己的团队构建一个定制化的 Harness比如专门用于数据分析你会保留 Claude Code 的哪些内置工具去掉哪些新增哪些为什么Claude Code 的上下文压缩策略是摘要早期消息 重注入 CLAUDE.md。你能想到这种策略的局限性吗在什么场景下会出问题从商业角度看Anthropic 选择开放 Agent SDK、封闭 Claude Code CLI的策略是否合理如果你是 Anthropic 的竞争对手你会怎么应对参考资料以下是 Harness 主题下质量最高的一手资料AI 实验室官方文档Anthropic: Effective Harnesses for Long-Running Agents — 官方定义 Harness 架构Initializer Coding Agent 两阶段设计Anthropic: Building Effective Agents — 2024 年 12 月发表的行业奠基性文章Workflow vs Agent 区分Harness 概念前身Anthropic: Building Agents with the Claude Agent SDK — Agent SDK 官方文档OpenAI: Harness Engineering — 2026 年 2 月正式提出harness engineering概念约 1500 个自动化 PROpenAI: Unrolling the Codex Agent Loop — Codex CLI agent loop 详解学术论文Building Effective AI Coding AgentsarXiv 2603.05344 — 学术界对 Harness 概念的首次严肃形式化scaffolding vs harness 的边界定义行业高影响力文章Simon Willison: How Coding Agents Work — 提出Coding agent harness for LLM的经典定义Inngest: Your Agent Needs a Harness, Not a Framework — 重点看 Harness vs Framework 的区分Swyx / Latent Space: Is Harness Engineering Real? — 行业讨论核心观点是竞争优势在 Harness 而非 ModelLangChain: Deep AgentsGitHub — 开源 Harness 实现仅调 Harness 就让 Terminal Bench 提升 13.7 分Lilian Weng: LLM Powered Autonomous Agents — 2023 年的奠基综述虽未用harness一词但定义了同一架构Parallel.ai: What is an Agent Harness — 最佳独立解释文定义 Harness 6 大组件区分 Harness/Framework/Orchestrator