Dive into Claude Code 架构拆解4个设计问题5层21个子系统全景图【免费下载链接】Dive-into-Claude-CodeA Systematic Analysis and Discussion of Claude Code for Designing Todays and Future AI Agent Systems项目地址: https://gitcode.com/gh_mirrors/di/Dive-into-Claude-CodeDive into Claude Code是一个针对 AI 编码智能体 Claude Codev2.1.88约 51.2 万行 TypeScript的源码级架构分析开源项目。它系统回答了每个生产级AI Agent都必须面对的 4 个核心设计问题把整个系统拆解为5 层 21 个子系统的全景图并提炼出 13 条设计原则与一份「构建你自己的 Agent」设计指南。一句话总结Claude Code 的代码库里只有1.6% 是 AI 决策逻辑其余98.4% 都是确定性基础设施——权限门控、上下文管理、工具路由与故障恢复。Agent 循环本身只是一个 while 循环真正的工程复杂度藏在它周围的系统里。核心数字速览Claude Code 架构规模一览在展开架构细节前先用一组数字建立整体感知维度数字含义代码规模1,884 文件 / ~512K 行分析对象为 v2.1.88 源码快照安全层7 层工具过滤 → 规则评估 → 沙箱层层设防上下文压缩5 个阶段预算缩减 → Snip → 微压缩 → 折叠 → 自动压缩工具54 个内置 MCP 外部工具经 5 步管道动态组装钩子事件27 个4 种执行类型shell / LLM / webhook / 子智能体验证扩展机制4 种Hooks、Skills、Plugins、MCP权限模式7 种从plan到bypassPermissions的渐进信任光谱这些数字本身就传递出一个架构信号最小脚手架最大 harness——与其在提示词上堆规则不如投资运行时的确定性基础设施。快速上手如何阅读这份架构拆解项目git clone https://gitcode.com/gh_mirrors/di/Dive-into-Claude-Code cd Dive-into-Claude-Code不同背景的朋友建议不同的阅读路径你是……建议入口然后读️ Agent 构建者README.md 的构建你自己的 Agent章节docs/architecture_zh.md 架构深度剖析️ 安全研究员README_zh.md 安全与权限章节docs/architecture.md 七层安全机制 产品经理关键亮点 价值观与设计原则论文 PDF 研究人员paper/Dive_into_Claude_Code.pdf 完整论文docs/agent-design-space-source-notes.md 设计空间源笔记4 个核心设计问题编码智能体架构的起点任何生产级 Coding Agent 都必须先回答 4 个问题Claude Code 给出的答案构成了其架构骨架设计问题Claude Code 的答案备选方案其他系统推理放在哪里模型负责推理harness 负责强制执行1.6% AI 98.4% 基础设施LangGraph 显式状态图、Devin 多步规划器多少个执行引擎一个queryLoop供 CLI、SDK、IDE 所有入口共用每个界面独立引擎默认安全姿态拒绝优先deny ask allow最严格规则胜出容器隔离SWE-Agent、git 回滚Aider最紧的资源约束有限的上下文窗口5 个前置管理阶段按条件触发计算预算、显式草稿区这套问题 → 答案的分析框架正是本项目的核心价值不是逆向某个实现而是给出可复用的设计空间。7 大组件Claude Code 系统结构全景从上图可以清晰看到 7 个组件的数据流User用户——提交提示词、批准权限、审查输出Interfaces接口层——交互式 CLI、无头 CLIclaude -p、Agent SDK、IDE/桌面/浏览器Agent Loop智能体循环——query.ts中的queryLoop异步生成器调用模型 → 分派工具 → 收集结果 → 循环Permission System权限系统——拒绝优先规则 auto 模式 ML 分类器 钩子拦截Tools工具层——最多 54 个内置工具 MCP 工具经assembleToolPool动态组装State Persistence状态与持久化——仅追加的 JSONL 转录、提示词历史、子智能体侧链Execution Environment执行环境——Shell含沙箱、文件系统、Web 抓取、MCP 连接关键设计所有接口最终汇聚到同一个queryLoop——交互 CLI、无头模式、SDK 与 IDE 共用同一条代码路径这大幅降低了多端行为不一致的维护成本。5 层 21 个子系统架构拆解全景图将 21 个子系统归纳为 5 个架构层是本项目最实用的拆解视角架构层职责关键子系统Surface 表层入口与渲染交互式 CLI、无头 CLI、SDK、IDEReact Ink 终端 UICore 核心层上下文组装与智能体循环queryLoop、5 阶段压缩管道、子智能体派生Safety/Action 安全行动层权限与工具7 权限模式、auto 分类器、27 钩子事件、工具池、Shell 沙箱State 状态层运行时状态与持久化JSONL 转录、CLAUDE.md 层级、自动记忆、侧链文件Backend 后端层执行环境Shell 执行、MCP 连接7 种传输、42 个工具子目录这张全景图值得打印出来贴在工位上——它把Agent 系统到底由哪些部分构成这个问题一次性讲透了。Agent Loop 拆解每一轮请求的 9 步管道核心是一个ReAct 模式的 while 循环组装上下文 → 调用模型 → 分派工具 → 检查权限 → 执行 → 重复。每个请求轮次严格走完 9 步管道设置解析 → 状态初始化 → 上下文组装 → 按条件执行上下文管理 → 模型调用 → 工具分派 → 权限门控 → 工具执行 → 停止条件检查其中两个容易被忽略但极其关键的细节模型调用前有 5 个上下文管理阶段按序检查预算缩减 → Snip → Microcompact → Context Collapse → Auto-Compact每个阶段按自身条件触发而非一刀切截断循环有 5 个停止条件无工具调用、达到最大轮次、上下文溢出、钩子干预、显式中止。故障恢复同样是内建能力输出 token 上限逐级放宽最多 3 次重试、每轮至多一次的按需压缩、提示过长降级链、流式回退与备用模型切换。循环本身容易复制这套恢复机制才难。权限系统深度剖析7 种模式与拒绝优先权限系统是 Claude Code 最较真的部分核心思想是deny-first拒绝优先宽范围的 deny 规则永远覆盖窄范围的 allow。7 种权限模式构成渐进式信任光谱模式行为信任级别plan执行前所有计划需用户批准最低default标准交互式审批低acceptEdits文件编辑与文件系统 Shell 命令自动批准中autoML 分类器独立评估工具安全性高dontAsk不弹窗deny 规则仍强制执行更高bypassPermissions跳过大部分提示安全关键检查保留最高bubble内部子智能体向父级升级请求特殊在这套机制之上论文归纳出7 个独立安全层工具预过滤、拒绝优先规则评估、权限模式约束、auto 模式 ML 分类器、Shell 沙箱、会话级权限状态、钩子拦截。授权管道为 4 阶段流程预过滤剥离被拒工具→ PreToolUse 钩子 → 规则评估 → 权限处理程序4 个分支。还有一个值得安全研究者注意的发现2 个已修复的 CVE 共享同一根因——钩子和 MCP 服务器在信任对话框弹出之前就已执行形成了结构性特权的预信任窗口。上下文与记忆把稀缺资源管成流水线上下文窗口是整个系统最紧的资源约束。Claude Code 的做法是9 个有序来源依次构建上下文系统提示 → 环境信息 → CLAUDE.md 层级 → 路径作用域规则 → 自动记忆 → 工具元数据 → 对话历史 → 工具结果 → 压缩摘要。其中CLAUDE.md 采用 4 级层级从企业级到个人级级别路径作用域Managed/etc/claude-code/CLAUDE.md系统级企业User~/.claude/CLAUDE.md每用户ProjectCLAUDE.md、.claude/rules/*.md每项目LocalCLAUDE.local.mdgitignore个人另一个反直觉的设计选择记忆是纯文件式的——没有嵌入向量、没有向量数据库靠 LLM 扫描记忆文件头按需选出最多 5 个相关文件。好处是完全可检查、可编辑、可版本控制。透明优先于智能再次体现。子智能体委托用上下文隔离换取专注当任务可以拆分时主智能体通过AgentTool把子任务委托给独立上下文的子智能体。内置 6 种类型Explore、Plan、General-purpose、Guide、Verification、Statusline支持通过.claude/agents/*.md自定义。三个关键设计点SkillTool vs AgentTool前者把指导注入当前上下文后者在分离上下文中运行子任务——中间过程不会污染父级上下文三种隔离模式Worktreegit worktree 文件系统隔离、Remote远程执行、In-process默认共享文件系统、隔离对话侧链转录每个子智能体有独立.jsonl文件父级只接收精炼后的结果摘要多实例协调直接复用 POSIXflock()零外部依赖。会话持久化可回退、可审计、可分叉会话历史通过 3 条通道持久化仅追加的 JSONL 转录、全局提示词历史、子智能体侧链文件。值得学习的工程取舍仅追加append-only优先于查询能力——每个事件人类可读、可版本控制、无需专门工具即可重建链补丁而非破坏性编辑压缩边界记录headUuid/anchorUuid/tailUuid会话加载时在读取时修补消息链磁盘上从不破坏性修改检查点支持--rewind-files回退存储于~/.claude/file-history/sessionId/注意会话级绕过标志与应用白名单不会在恢复会话时还原——临时授权与持久策略严格区分生命周期。可扩展性4 种机制3 个注入点Hooks、Skills、Plugins、MCP 四种扩展机制统一作用于 Agent Loop 的 3 个注入点注入点控制什么典型机制assemble()模型看到什么CLAUDE.md、技能描述、MCP 资源、钩子注入上下文model()模型能调用什么内置工具、MCP 工具、SkillTool、AgentToolexecute()动作是否/如何运行权限规则、Pre/PostToolUse 钩子、Stop 钩子工具池按 5 步管道动态组装基础枚举最多 54 个→ 模式过滤 → deny 预过滤 → MCP 集成 → 去重。而 27 个钩子事件、10 种插件组件类型、SKILL.md 的 15 个 YAML 字段则提供了从轻量注入到深度定制的完整梯度。可组合的多机制扩展——单一 API 做不到这种成本分级。延伸阅读资料文件导览资料说明README.md / README_zh.md项目主入口含完整社区资源目录docs/architecture.md / docs/architecture_zh.md架构深度剖析7 安全层、9 步管道、5 阶段压缩docs/agent-design-space-source-notes.mdAgent 设计空间源笔记含中文 docs/agent-design-space-source-notes_zh.mddocs/related-resources.md社区分析资源索引paper/Dive_into_Claude_Code.pdf完整论文 PDFassets/本文全部架构图源文件结语护城河是 harness不是模型这份架构拆解最有价值的结论是Agent 循环谁都能抄真正难的是横跨各层的 harness——钩子体系、ML 权限分类器、5 阶段压缩、子智能体隔离与恢复逻辑。如果你正在构建自己的 AI Agent 系统建议按 docs/architecture.md 中的设计问题 → Claude Code 答案 → 备选方案对照表逐一决策先想清楚 4 个核心问题再谈技术选型。这正是本论文从逆向工程升维到设计空间的地方。【免费下载链接】Dive-into-Claude-CodeA Systematic Analysis and Discussion of Claude Code for Designing Todays and Future AI Agent Systems项目地址: https://gitcode.com/gh_mirrors/di/Dive-into-Claude-Code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考