Anthropic 内部架构曝光，Claude Code 如何用 Harness 驾驭强智能

在AI技术飞速迭代的当下大语言模型的突破让智能体Agent成为行业焦点。无数开发者和企业试图通过复杂的规则引擎、堆砌API胶水代码来赋予Agent智能却往往陷入系统脆弱、难以维护、换个场景就崩溃的困境。而2026年3月底Claude Code源码意外泄露事件为行业提供了一份珍贵的工业级研究标本。这个在生产环境中打磨过的Agent系统其架构设计的核心逻辑直指AI Agent构建的本质那就是Harness Engineering的核心价值不试图编程智能而是为智能构建稳固的基础设施。一、重新认知HarnessAI Agent的“缰绳”而非“骑手”在探讨Claude Code的架构之前我们首先要厘清Harness Engineering的核心定义。围绕大语言模型构建的、使Agent能够在特定领域中有效运作的完整基础设施体系就是Harness。用一个公式就能清晰概括其组成Harness 工具 知识 观察 操作接口 权限。翻译过来工具是Agent的双手支撑其完成具体操作知识是Agent的大脑赋予其专业判断力观察是Agent的眼睛帮助感知环境与任务状态操作接口是Agent的行动通道连接内外执行指令权限则是Agent的边界划定其操作的安全范围。而Claude Code的架构本质上可以浓缩为一个更简洁的公式一个Agent循环 一套完备的操作环境。Anthropic团队最清醒的认知正是区分了“智能”与“载体”的边界。模型是Agent本身是那个拥有智能潜力的“马”而Claude Code的Harness就是缰绳它不替代马奔跑却决定了马能跑多快、多稳、多远。很多团队在构建AI Agent时陷入了本末倒置的误区。他们花费大量精力编写复杂的决策树、设计层层嵌套的Prompt瀑布流试图用代码拼凑出智能行为。但现实是智能是学出来的不是写出来的。就如同我们无法通过打磨缰绳让一匹马凭空拥有奔跑的能力也无法通过优化工程代码让大语言模型凭空诞生智能。Harness Engineering的核心使命是为模型的智能提供适配的运行环境让模型的潜力得以充分释放。二、Agent循环AI Agent的核心骨架Harness的搭建根基所有AI Agent系统的底层逻辑都依托于一个基础循环。这个循环简单到可以用一句话描述模型接收消息 → 决定行动 → 执行工具 → 获取结果 → 再次决策。而在Claude Code的架构中QueryEngine模块正是这个循环的中枢。原版源码中这个用TypeScript编写的模块约有46K行在社区重构的Python端口中query_engine.py承担了相同的核心职责。QueryEngine负责处理流式响应、管理工具调用循环、设计重试逻辑和管控Token预算。社区重构项目中的QueryEnginePort类完整保留了这一核心功能定义了TurnResult数据结构以及提交消息、流式响应、压缩历史、持久化会话等关键方法。值得注意的是循环本身是Agent的核心骨架而Harness的设计则是在这个骨架上搭建各类能力模块且不改变循环的核心结构。工具系统、技能加载、上下文管理、子智能体编排所有这些功能模块本质上都是外挂在这个循环骨架上的“器官”让Agent的运行更高效、更稳定。在Claude Code的循环设计中有两个细节充分体现了Harness Engineering的巧思。其一是流式响应处理。用户在与Agent交互时最直观的体验就是能否实时看到生成的内容。Claude Code的流式处理与终端UI深度集成其底层采用React Ink技术栈在Python端口中通过ink.py模块实现了逐字渲染效果。这种设计直击用户痛点人在与Agent交互时需要即时感知其“思考过程”否则等待焦虑会快速累积而流式响应恰好解决了这一体验难题。其二是工具调用循环。当模型的停止原因为工具调用时QueryEngine会自动执行对应的工具将执行结果追加到消息列表然后再次调用模型。这个循环会持续到模型返回非工具调用的停止条件。这种设计将“何时停止”的决定权完全交给模型Harness的职责只是执行工具、反馈结果而非干预模型的决策逻辑充分尊重了模型的智能自主性。三、工具系统给Agent一双精准的“手”筑牢Harness的操作基石工具系统是Harness Engineering中最核心的组成部分直接决定了Agent能否精准完成各类操作。在Claude Code的原版源码中Tool.ts文件约有29K行基于Zod做Schema验证定义了所有工具的基础类型和接口。在Python重构版本中tools.py和tool_pool.py则承担了工具快照加载、按模式过滤、搜索和执行的核心职责。从架构设计来看Claude Code的工具系统遵循三大核心原则这也是Harness工具设计的黄金法则。一原子性单一职责让工具更精准原子性原则要求每个工具只完成一件事。读取文件、编辑文件、执行Shell命令、搜索代码、发起网络请求每一个工具的职责都清晰且单一。这种设计理念与微服务架构如出一辙单一职责让工具的边界清晰模型在选择工具时能更精准降低了误操作的风险。试想一下如果一个工具同时承担“读取文件并修改内容”的双重职责模型在决策时就会陷入混乱容易出现操作失误。而原子性的工具设计让每一次工具调用都目标明确为Agent的精准操作奠定了基础。二可组合性灵活联动构建操作工作流工具之间并非孤立存在可组合性让它们能够灵活联动。Agent可以先通过搜索代码工具定位目标文件再通过读取文件工具获取内容最后通过编辑文件工具修改内容。每一个工具的输出都能成为下一个工具的输入这种自然的组合能力让Agent的操作链形成了“工作流”效果。与传统的显式工作流编排不同Claude Code的工具组合无需预先设计流程而是由模型根据任务需求自主决定组合方式。这种灵活性让Agent能够应对复杂多变的任务场景无需依赖人工预设的操作流程。三自我描述性动态发现节省上下文空间每个工具都通过Schema精确定义输入输出格式模型只需通过工具描述就能理解其使用场景和调用方式。更具巧思的是延迟工具发现设计Agent无需在系统提示中预加载所有工具描述而是在运行时动态发现和使用新工具。这种设计极大地节省了上下文窗口空间是Harness工程化中极具实际价值的性能考量。在Python端口的tool_pool.py模块中专门实现了工具池的管理逻辑让动态工具发现和调用成为可能。在实际的编码会话中Agent可能需要前端框架知识、数据库设计规范等多种工具若预加载所有工具Token费用会快速消耗而延迟发现则完美解决了这一问题。工具是Agent的双手手的设计精度直接决定了Agent能完成的操作复杂度。Claude Code的工具系统设计为Harness搭建了稳固的操作基石让Agent拥有了精准、灵活的操作能力。四、知识与技能系统按需加载让Agent拥有“活的大脑”在AI Agent的运行中知识是赋予其专业能力的核心。但如果将所有知识一次性灌入系统不仅会造成上下文窗口的严重浪费还会增加模型的决策负担。Claude Code的技能系统完美诠释了Harness Engineering中“按需加载、渐进式披露”的知识管理理念。一动态知识存储按需加载拒绝全量灌入Claude Code的技能系统以结构化文件形式存储在skills/目录中每个技能文件都包含元数据和详细知识体。元数据定义了技能的触发条件和描述知识体则包含具体的专业内容。当模型判断需要某个技能时通过SkillTool加载对应的文件将内容按需注入对话上下文。这种设计的核心价值在于避免了上下文窗口的无效消耗。在一次编码会话中Agent可能需要前端、后端、数据库等多领域知识如果将所有知识一次性预加载Token预算会在短时间内耗尽。而按需加载的模式让Agent只在需要时获取对应知识最大化利用了上下文空间。二渐进式披露分层加载精准匹配需求更高级的知识管理策略是Claude Code采用的渐进式披露Progressive Disclosure策略。它将知识分为三个层级让Agent的知识获取更具层次感元数据层Agent首先看到的是知识的摘要信息用于快速判断是否需要该技能。这一层信息简洁明了占用极少的上下文空间让模型能快速做出决策。主体内容层当模型确认需要该技能后才加载详细的知识内容。这一层是知识的核心支撑Agent完成具体的任务操作。参考资料层只有当Agent需要深入分析时才加载参考资料。这部分信息作为补充不占用核心上下文空间。这种分层加载的方式就像给Agent搭建了一个分层知识库。Agent先浏览目录再查看具体章节最后查阅参考文献每一步都按需加载绝不贪多。在实际应用中这种策略不仅节省了Token成本还让模型的决策更高效避免了被冗余信息干扰。知识的价值从来不在于全量存储而在于精准调用。Claude Code的知识与技能系统让Agent拥有了“活的大脑”能够根据任务需求动态获取知识这也是Harness Engineering的核心亮点之一。五、上下文管理给Agent一份干净的“记忆”平衡空间与效率大语言模型的上下文窗口存在固定大小限制这是AI Agent运行中不可忽视的技术瓶颈。Harness Engineering的核心任务之一就是在“保留有用信息”与“腾出空间”之间找到平衡。Claude Code通过三层上下文管理策略为Agent打造了干净、高效的“记忆”体系。一子智能体隔离隔绝噪音净化主上下文当Agent处理复杂任务时往往需要拆解为多个子任务由子智能体执行。Claude Code的设计中每个子智能体都拥有独立的消息数组和工作目录其操作历史不会污染主会话的上下文。主会话只接收子智能体返回的最终结果摘要而非完整的执行过程。这种设计从根本上防止了子任务的执行噪音进入主对话让主Agent的上下文始终保持清晰。在处理多任务并行的场景中子智能体隔离策略能有效避免上下文混乱提升主Agent的决策效率。二上下文压缩智能取舍保留核心信息当对话内容逐渐累积接近上下文窗口限制时Claude Code会自动启动上下文压缩策略。系统会识别对话中的关键信息如代码变更、决策理由、用户反馈等保留核心内容丢弃冗余的细节描述。在Rust端的社区重构版本中runtime crate专门处理了会话状态和上下文压缩逻辑。采用系统级语言实现这一功能不仅提升了压缩的性能也增强了系统的可控性。上下文压缩不是简单的内容删减而是基于语义的智能筛选确保压缩后的上下文仍能支撑模型做出准确决策。三任务持久化扩展记忆实现会话续存Claude Code将目标任务持久化存储到磁盘文件中即使单个会话结束任务状态也能在下次启动时恢复。这种设计将Agent的“记忆”从易失的对话上下文扩展到了持久化的文件系统。源码中的session_store.py和history.py模块专门负责管理任务的生命周期。在实际的项目开发中一次复杂的编码任务可能需要多次会话才能完成任务持久化让Agent能够记住之前的操作进度无需重复沟通极大提升了交互效率。上下文总会在使用中逐渐填满Harness的上下文管理策略就是为Agent提前规划好“腾地方”的方案让其始终拥有干净、高效的记忆空间。六、多智能体协调从单兵作战到团队协作打造高效协作体系面对复杂的AI任务单一Agent往往难以独立完成。Harness Engineering需要提供多智能体协调能力让多个Agent形成协作体系共同完成任务。Claude Code在coordinator/目录中实现了一套成熟的多智能体编排系统其设计核心可总结为三大维度。一委派与隔离黑盒协作降低系统复杂度多智能体协调的核心思路是主AgentLead Agent根据任务需求委派子任务给子智能体。每个子智能体都是独立的实例拥有专属的消息数组、工作目录和权限边界与其他子智能体完全隔离。子智能体完成任务后只将结果摘要返回给主Agent而非暴露完整的执行过程。这种“黑盒委派”设计既保证了子任务的执行独立性又净化了主Agent的上下文同时大幅降低了系统的整体复杂度。主Agent无需关注子智能体的执行细节只需接收结果并进行后续决策让协作流程更简洁。二多元协作模式适配场景灵活编排Claude Code的多智能体系统支持多种经典的协作模式能够适配不同类型的复杂任务场景Pipeline流水线模式任务按顺序执行上一个任务的输出作为下一个任务的输入适合流程化的编码任务如前端页面构建、后端接口开发等。Fan-out/Fan-in分发聚合模式主Agent将任务拆分为多个并行子任务分发到不同子智能体执行完成后聚合结果适合大规模数据处理、多模块代码重构等场景。Expert Pool专家池模式根据任务类型从专家智能体池中选择对应领域的Agent执行任务适合需要专业领域知识的复杂场景如数据库优化、算法设计等。Producer-Reviewer生成审核模式一个Agent负责生成内容另一个Agent负责审核验证适合代码编写、文档撰写等需要质量把控的场景。Supervisor中心化调度模式主Agent作为调度中心统一分配任务、监控进度、协调资源适合任务关系复杂的大型项目。Hierarchical Delegation层级委派模式将复杂任务自顶向下拆解为多个层级的子任务由不同层级的Agent分别执行适合超大型系统的开发与维护。Anthropic的工程价值在于将这些经典协作模式标准化、工具化、可配置化让Agent能够根据任务特点自动选择最合适的协作架构无需人工干预。三文件系统隔离轻量沙箱保障数据安全在多智能体协作中数据隔离是核心需求。Claude Code利用Git Worktree实现了文件系统级的沙箱机制每个子智能体或并行任务都在独立的Worktree中工作修改的文件副本仅存在于自身目录不影响主分支或其他任务。任务完成后子智能体可通过Git Merge将结果合并回主分支。这种设计基于Git原生能力实现隔离无需引入额外的容器或虚拟机既轻量又可靠。在实际的团队协作开发场景中文件系统隔离能有效避免子任务之间的代码冲突保障项目数据的安全性和完整性。从单兵作战到团队协作Claude Code的多智能体协调系统为Harness搭建了高效的协作体系让Agent能够应对更复杂的任务挑战。七、权限系统给Agent划定安全边界筑牢Harness的安全防线AI Agent拥有强大的操作能力若缺乏权限管控极易引发安全风险。Harness Engineering中的权限系统是“安全工程”的核心环节。Claude Code通过多级权限模式和细粒度控制为Agent划定了清晰的安全边界让其在高效操作的同时始终处于可控范围内。一多级权限模式灵活适配平衡安全与效率Claude Code的权限系统支持四种权限级别可根据不同场景灵活选择每次工具调用前提示用户审批这是最安全的模式适合高风险操作如修改核心代码、执行系统命令等确保每一步操作都经过人工确认。规划阶段只读执行阶段需审批适合大型重构类任务允许Agent在规划阶段读取代码、制定方案执行阶段的关键操作则需用户审批。自动批准低风险操作针对无安全风险的操作如读取非核心文件、简单的代码注释修改等自动批准执行提升交互效率。完全跳过权限检查仅适用于沙箱环境或测试环境无需权限管控方便开发者调试和测试。多级权限模式的设计兼顾了安全性与效率既能在生产环境中规避风险又不会在低风险场景中过度限制Agent的操作。二细粒度控制精准管控规避操作风险在每次工具调用时权限Hook都会介入检查实现细粒度的权限控制。系统支持基于工具类型、操作类型读取 vs 写入、文件路径模式、命令白名单等多维度的规则配置。例如可配置仅允许Agent读取项目目录下的特定文件禁止修改核心配置文件可限制仅允许执行白名单中的Shell命令禁止执行高危命令。这种细粒度的控制让权限管理不再是“一刀切”而是精准到每一次操作。结合前文提到的文件系统隔离机制Claude Code的权限系统构建了多层次的安全防护体系。Agent拥有足够的操作空间完成任务却被严格的边界限制避免了误操作和安全风险。安全不是将Agent关进笼子而是为其划定一条足够大但明确的跑道让其自由奔跑的同时不偏离安全轨道。八、Bridge 与扩展性跨越终端的 Harness 延伸Claude Code 最初定位是一款面向开发者的终端工具能够直接在命令行环境中完成代码读写、项目构建、命令执行等一系列编码相关操作。但在实际的开发者工作流中IDE 才是真正的核心阵地代码编辑、调试、版本管理、项目导航等行为大多在编辑器内完成。为了让 Agent 能力真正融入开发者日常环境Anthropic 在源码中专门设计了 bridge 目录用来承载一套完整的桥接系统。Bridge 本质上是一个双向通信层它不改变 Harness 本身的核心逻辑而是为 Harness 提供跨环境运行的能力让 Claude Code 可以从独立终端工具无缝嵌入 VS Code 等主流 IDE 中。这套桥接体系包含了多个关键组件比如桥接主循环、标准化消息协议、权限审批桥接、安全认证机制以及会话生命周期管理模块等。从 Harness Engineering 的视角来看Bridge 系统的价值远不止“多平台运行”这么简单。它真正的意义在于扩展了 Agent 的操作边界把原本只存在于终端的执行环境延伸到了更丰富、更专业的 IDE 场景中。开发者不需要在终端和编辑器之间反复切换也不用手动复制粘贴代码、传递上下文而是可以在熟悉的界面里直接触发 Agent 能力同时享受 IDE 自带的代码高亮、语法检查、断点调试、Git 集成等增强能力。这种设计也让 Harness 具备了极强的可扩展性。未来只要遵循统一的桥接协议Agent 就可以继续接入更多平台比如网页编辑器、云开发环境、协作平台等而不需要重构底层的工具系统、权限系统或上下文管理逻辑。Bridge 让 Harness 从一个封闭系统变成一个可插拔、可迁移、可扩展的开放体系这也是工业级 Agent 框架必须具备的重要特征。九、性能优化工业级 Harness 的工程细节如果说架构设计决定了 Harness 的上限那么性能优化则决定了它能否真正落地到生产环境。Claude Code 在源码层面做了大量贴近工程实践的性能优化这些细节看似不起眼却直接影响用户体验、系统稳定性和运行成本也是 Anthropic 工程能力的集中体现。首先是并行预取启动机制。在应用启动阶段很多系统会按部就班加载依赖、初始化模块、解析配置导致启动缓慢。Claude Code 则在正式进入模块评估之前通过副作用代码并行启动各项初始化操作。比如提前加载工具池、预连接文件系统、预热模型调用接口、预解析项目结构等。当用户看到命令行提示符时这些耗时操作已经在后台完成用户几乎不需要等待即可开始交互。这是典型的用空间换时间的策略源码中的 prefetch.py 模块就是专门处理这类预取逻辑让整个系统“无感启动”。其次是懒加载与特性门控。Agent 系统往往包含大量工具、技能、协议适配模块如果全部在启动时加载不仅启动慢还会占用大量内存。Claude Code 采用懒加载模式重量级模块只有在真正被使用时才通过动态导入加载。未被激活的功能代码在构建时会被直接剔除最终打包产物更小、运行更快、内存占用更低。这种设计尤其适合轻量化部署场景也让系统在长时间运行时更加稳定。在技术栈选型上Claude Code 同样体现出极强的工程理性。原版使用 TypeScript 保证类型安全与大规模代码可维护性运行在 Bun 上追求极致性能社区重构版本则分别使用 Python 提升易用性、Rust 强化执行效率与安全性。终端界面基于 React Ink 实现用前端组件化的思路构建命令行 UI既保证交互流畅又便于维护和扩展。CLI 解析使用成熟的 Commander.js 或 argparse降低重复造轮子的成本。工具参数校验使用 Zod 或 dataclass在运行时保证类型安全减少因参数错误导致的执行失败。代码搜索依赖 ripgrep 这类高性能工具确保在大型项目中快速定位目标代码。外部工具集成则遵循 MCP SDK、LSP 等标准化协议让 Agent 可以无缝对接语言服务、构建工具、测试框架等生态组件。认证层面采用 OAuth 2.0 和 JWT保证多环境、多设备下的安全访问。每一项技术选型都不是为了炫技而是围绕 Harness 的核心目标在性能、安全、可维护性、扩展性之间找到最佳平衡点。十、Harness 工程师的五大核心职责通过对 Claude Code 源码架构的全面拆解我们可以清晰地总结出 Harness 工程师在实际工作中的核心职责。Harness 工程师不是简单的 API 开发人员也不是普通的后端工程师他们是 AI Agent 系统的“基建建筑师”决定了智能体能走多远、做多稳、做多强。第一大职责是实现工具为 Agent 打造一双精准可靠的手。工程师需要设计原子化、可组合、自我描述的工具接口确保每个工具职责单一、输入输出明确、错误处理完备。工具的设计质量直接决定 Agent 的操作精度一个糟糕的工具会让模型频繁出错、执行失败而一个优雅的工具能让 Agent 像人类开发者一样流畅完成复杂编码任务。第二大职责是策划知识为 Agent 构建专业大脑。Harness 工程师不能把所有文档一股脑塞给模型而是要设计结构化、分层级、可触发的技能体系实现按需加载、渐进式披露。他们需要梳理领域知识、开发规范、最佳实践、历史决策记录设计合理的触发条件让 Agent 在需要时自动调取最合适的知识既不浪费上下文又能保证决策质量。第三大职责是管理上下文为 Agent 维持干净高效的记忆。LLM 的上下文窗口永远是稀缺资源Harness 工程师必须设计上下文压缩、历史摘要、子任务隔离、会话持久化等机制确保有限空间里始终存放最有价值的信息。一个优秀的上下文管理系统可以让 Agent 持续运行数小时甚至数天而不出现信息混乱或记忆溢出。第四大职责是控制权限为 Agent 划定安全边界。Harness 工程师是 Agent 系统的安全负责人需要设计多级权限审批、细粒度操作控制、文件系统沙箱、命令白名单、风险行为拦截等机制。既要让 Agent 拥有足够的行动自由又要杜绝越权操作、误删文件、执行危险命令等风险在效率与安全之间保持平衡。第五大职责是收集训练信号反哺下一代模型。Harness 不仅是运行环境还是数据采集系统。每一次工具调用、每一步决策、每一次成功或失败的执行都是宝贵的训练数据。Harness 工程师需要设计埋点、日志、会话回溯机制把 Agent 在真实场景中的感知、推理、行动过程记录下来用于优化模型能力、改进提示词、升级工具设计形成持续迭代的闭环。优秀的 Harness 不仅服务当前 Agent还能让未来的模型变得更聪明。十一、从“编程智能”到“为智能构建世界”Harness Engineering 的真正使命Claude Code 源码泄露事件意外为行业打开了一扇窗让我们看到了头部机构在构建工业级 Agent 时的真实思考。它不是一个堆砌功能的玩具项目也不是一个依赖复杂 Prompt 才能运行的演示系统而是一套完整、严谨、可扩展、可安全运行的 Harness 体系。从工具系统到知识管理从上下文工程到多智能体协调从权限治理到性能优化Claude Code 在每一个模块上都展现出成熟的工程决策。但所有技术细节最终指向一个共同的核心认知智能无法被工程代码“编写”出来只能被合适的环境“释放”出来。很多团队在做 Agent 时容易陷入误区认为只要模型足够强就能解决一切问题或者认为只要规则足够复杂就能让 Agent 表现得更智能。于是他们堆砌决策树、嵌套大量提示词、编写繁重的胶水代码试图用工程手段“制造智能”结果往往是系统脆弱、难以维护、稍微换个场景就全面崩溃。Harness Engineering 告诉我们工程师的真正价值不是编写智能而是为智能构建世界。模型是马Harness 是缰绳缰绳不能代替马奔跑但能决定马跑得稳不稳、快不快、远不远。工程师的工作是为模型提供可靠的工具、清晰的知识、干净的记忆、安全的边界和高效的运行环境让模型本身的智能可以顺畅、稳定、持续地发挥出来。未来 AI Agent 会进入越来越多的领域软件开发、运维自动化、办公协作、数据分析、工业控制等场景都会出现大量智能体。而决定这些智能体能否真正落地的不再只是模型参数大小而是 Harness 的工程水平。一个优秀的 Harness可以让普通模型发挥出接近顶尖模型的效果一个糟糕的 Harness即便用上最强模型也只能做出脆弱不堪的演示系统。Claude Code 的架构带给我们的不仅是技术参考更是一种理念升级。从今天开始放下“用代码编写智能”的执念转向“为智能构建基础设施”的长期主义。当我们把工程力量用在正确的方向上AI Agent 才能真正从实验室走向生产环境从简单任务走向复杂协作从偶尔可用变成稳定、可靠、值得信赖的生产力工具。Harness 不创造智能但它让智能有了可以奔跑的大地有了可以远行的方向有了可以持续成长的未来。