How Claude Code Works

Claude Code 架构学习笔记 — Agentic Coding System 深度分析

📘 在线阅读文档   |   English

🛠️ 想动手造一个？配套项目 Claude Code From Scratch — ~4300 行 TypeScript / Python 两个版本，13 章分步教程，clean-room 教育实现，从零造一个受 Claude Code 启发的 Coding Agent

---

⚖️ 声明 / Disclaimer：本项目是面向开发者的教育性架构分析。所有内容均为独立研究与推理，不代表 Anthropic 官方设计，也不保证与 Claude Code 真实内部实现一致。"Claude Code" 是 Anthropic 的商标，本项目与 Anthropic 无任何关联，亦不对外分发任何来自 Anthropic 的源码。

⚖️ 写在前面：2026.7.4: 距离3月底的源码泄露事件，到现在claude code又更新了许多新的功能，尤其是/goal /loop组成的 loop engineering, 以及dynamic workflow为代表的新的agent编排、观测和干预方法，这些新的功能的原理分析其实对于我们使用claude code帮助很大，因此我们近期也在持续逆向解析这些新的功能，不断更新该repo

Claude Code 是目前使用最广泛的 AI 编程 Agent，也是我们认为最好用的 AI 编程工具。它能理解整个代码仓库、自主执行多步编程任务、安全地运行命令——而这一切背后是 50 万行 TypeScript 源码中沉淀的工程智慧。

这份 50 万行 TypeScript 的源码以快照形式在社区流出后，我们第一次能在一个真实的、跑在百万开发者机器上的生产级 Coding Agent 里，亲眼看到它到底长什么样。但 50 万行——从哪里开始读？

这也是我们创建这个项目的初衷——我们都遇到了没有办法阅读这么庞大代码项目的问题，解决方案是和 Claude Code 一起读，让它写文档配合我们理解源代码。在此同时，我们想把这个过程文档化，就形成了这个项目。

我们和 Claude Code 加班从源码中提炼出 16 篇专题文档，覆盖了从核心循环到安全防护的每一个关键设计决策。不管你是想造自己的 AI Agent，还是想更深入地理解和使用 Claude Code，这里都是最短路径（应该？就算不是最短的，我们也会不断更新这个项目）。

🏗️ 系统架构

graph TB
    User[用户输入] --> QE[QueryEngine 会话管理]
    QE --> Query[query 主循环]
    Query --> API[Claude API 调用]
    API --> Parse{解析响应}
    Parse -->|文本| Output[流式输出]
    Parse -->|工具调用| Tools[工具执行引擎]
    Tools --> ReadTool[读文件]
    Tools --> EditTool[编辑文件]
    Tools --> ShellTool[Shell 执行]
    Tools --> SearchTool[搜索工具]
    Tools --> MCPTool[MCP 工具]
    Tools -->|结果回注| Query

    Context[上下文工程] --> Query
    Context --> SysPrompt[系统提示词]
    Context --> GitStatus[Git 状态]
    Context --> ClaudeMD[CLAUDE.md]
    Context --> Compact[压缩流水线]

    Perm[权限系统] --> Tools
    Perm --> Rules[规则层]
    Perm --> AST[Bash AST 分析]
    Perm --> Confirm[用户确认]

🤔 这份源码为什么值得深入研究？

大多数 AI Agent 框架都是"demo 级别"——跑通一个场景就宣布成功。Claude Code 不同，它是一个日活百万级开发者实际使用的生产系统，需要处理的问题远比 demo 复杂：

• 对话动辄上百万 token，上下文窗口不够用怎么办？（记忆管理、压缩方案是如何设计的超重要）
• 数十个内置工具同时存在，怎么协调？（如果所有工具上下文都给AI，那将直接爆炸）
• 怎么让用户感觉"快"，哪怕模型推理本身就要几十秒？（如何实现流水线设计）
• 用户让 AI 执行 rm -rf /，怎么拦住？（安全护栏很重要）

这些问题的解法，就藏在源码里。

🔍 从源码中发现的关键设计

以下内容均来自对源码的实际分析，不是猜测。

为什么 Claude Code 用起来感觉那么快？

它其实做了三件聪明的事：

1. 全链路流式输出 — 每生成一个 token 就立刻展示，不等模型全部想完。从 API 调用到终端渲染，整条链路都是流式的。
2. 工具预执行 — 模型说"我要读某个文件"的时候，这个文件其实已经在读了。系统在模型还在输出的同时就开始解析和执行工具调用，利用模型生成的 5-30 秒窗口，把约 1 秒的工具延迟藏起来了。
3. 9 阶段并行启动 — 启动时把不相关的初始化任务并行执行，关键路径压到约 235ms。

出错了怎么办？—— 静默恢复

普通程序遇到错误会报错给用户。Claude Code 的策略是：能恢复的错误，用户根本看不到。

比如对话太长超出了上下文窗口，它悄悄压缩上下文、自动重试，不弹错误框让你手动处理。token 输出达到上限？自动从 8K 升级到 64K 再重试。整个 Agent 循环有 7 种不同的"继续"策略，每种对应一种故障恢复路径。

这就是为什么用 Claude Code 的时候很少遇到报错——不是没有错误，而是大部分都被内部消化了。

对话太长怎么办？—— 4 级渐进式压缩

这是整个系统里做得最细的一处设计。当上下文快要超限时，分 4 个级别逐步处理：

1. 裁剪 — 先把历史消息中的大块内容（旧的工具输出）截断
2. 去重 — 几乎零成本地去除重复内容
3. 折叠 — 把不活跃的对话段落折叠起来，但不修改原始内容（可以展开恢复）
4. 摘要 — 最后手段，启动一个子 Agent 对整个对话做摘要

每一级都可能释放足够的空间，让后面的级别不需要执行。而且压缩后系统会自动恢复最近编辑的 5 个文件内容，防止模型忘记刚刚在干什么。

怎么防止 AI 执行危险操作？—— 7 层纵深防御

Claude Code 让 AI 直接在你电脑上跑命令，安全设计必须过硬。它不是靠一个"你确定吗？"对话框，而是搭建了 7 层防御体系：