7张图看懂Claude Code：从架构图解到工程实现
这篇文章用7张架构图解的方式，系统讲解Claude Code的工程实现。
为什么要关注Claude Code？
2026年3月31日，Anthropic的Claude Code CLI工具因npm发布包意外暴露了.map文件，导致完整源码泄露。
🏖️
这虽然说不是一次主动的开源，但对开发者来说，这是个难得学习的机会——能看到工业级Agent系统的内部实现。
好像这样说有点“不道德”了，但学习一下总没错，这次泄露的规模有多大？
•
59.8MB的source map文件
•
约512,000+行TypeScript代码
•
约1,900个文件
这些代码揭示了一个经过精心设计的、工业级的Agent Harness系统。
Claude Code的核心架构可以用一个公式概括：
代码块
Plain Text
Claude Code = 单循环 + Harness
Harness环境，就是五大核心子系统（工具、知识、观察、行动、权限），给予Agent充分操作的环境。
🥛
这也是Claude Code 作为 Harness 的最核心设计哲学：不成为智能体本身，而是为智能体（Claude 模型）提供一个功能完备的操作环境。
本文用架构图解的方式，系统讲解Claude Code的工程实现。
整体架构：30+模块如何协作？
Claude Code的源码按照功能职责清晰划分为30+个顶层目录，每个目录对应一个Harness子系统。
架构分层视图
🏆
这个分层架构清晰展示了Claude Code的设计哲学：不试图成为智能体本身，而是为智能体提供一个功能完备的操作环境。
核心模块职责
核心循环：Agent如何运行？
📌
Claude Code的Harness体系建立在最基础的Agent Loop之上。
QueryEngine的四大职责
QueryEngine.ts（约46K行）作为LLM查询引擎，承担了关键职责。
🌟
（1）流式响应处理
用户可以实时看到模型生成的内容，不是等待完整响应返回。这种设计对于终端交互体验至关重要。
（2）工具调用循环
当模型的stop_reason为"tool_use"时，QueryEngine自动执行对应的工具，将结果追加到消息列表中，然后再次调用模型。
这是Agent Loop的核心机制。
工具系统：Agent的双手如何设计？
•
工具系统是Harness的核心组成部分。它定义了Agent在环境中能够执行的每一个原子操作。
三大设计原则
从上述工具分层可以提炼出三条核心设计原则：
🌟
•
原子性（Atomicity）
每个工具只做一件事，职责单一且明确。
例如FileReadTool只负责读取文件，FileEditTool只负责编辑文件。这种设计使得模型的工具选择更加精准。
🥖
•
可组合性（Composability）
工具之间可以灵活组合。
模型可以先使用GrepTool搜索代码，再用FileReadTool读取匹配文件，然后用FileEditTool修改目标位置。每个工具的输出都是下一个工具的自然输入。
🏖️
•
自我描述性（Self-Describing）
每个工具都通过Zod v4 Schema精确定义了输入输出格式，模型通过工具描述就能理解何时以及如何使用它。
此外，ToolSearchTool实现了"延迟工具发现"，允许Agent在运行时动态发现和使用新工具。
知识加载：如何按需注入知识？
在Harness工程中，"知识"不是预先灌入系统提示的静态信息，而是按需加载的动态资源。
•
通过skill的渐进式披露策略 + 3层的用户请求决策树机制：
多智能体协调：如何团队协作？
当单个Agent无法独立完成复杂任务时，Harness需要提供多智能体协调能力。下图中，顶部为流程子智能体生成简要流程，其他则为6中的Claude code中自带的多智能体架构模式。
写在最后：Harness工程师的五大职责
🏝️
基于Claude Code的源码分析，Harness工程师的核心职责可以归纳为以下五个维度：
Claude Code给我们的最重要启发是：
一个好的Agent产品， 是在为AI提供好的操作环境，重在"驾驭"AI，而不是重在创造AI。
🚅
当我们将工程精力从"试图编程智能"转向"为智能构建世界"时，Agent系统的能力上限将由模型本身的智能水平决定，而不是被Harness设计所限制。