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 的源码。

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

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

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

我们和 Claude Code 加班从源码中提炼出 15 篇专题文档，覆盖了从核心循环到安全防护的每一个关键设计决策。不管你是想造自己的 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，上下文窗口不够用怎么办？（记忆管理、压缩方案是如何设计的超重要）
• 66 个内置工具同时存在，怎么协调？（如果所有工具上下文都给AI，那将直接爆炸）
• 怎么让用户感觉"快"，哪怕模型推理本身就要几十秒？（如何实现流水线设计）
• 用户让 AI 执行 rm -rf /，怎么拦住？（安全护栏很重要）

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

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

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

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

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

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

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

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

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

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

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

这是整个系统中最精妙的设计之一。当上下文快要超限时，不是一刀切地压缩，而是分 4 个级别逐步处理：

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

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

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

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

1. 权限模式 — 不同信任级别，限制可执行的操作范围
2. 规则匹配 — 基于命令模式的白名单/黑名单
3. Bash 命令深度分析 — 这里最硬核：用语法树分析（不是正则匹配）拆解 Shell 命令的真实意图，包含 23 项安全检查，覆盖命令注入、环境变量泄露、特殊字符攻击等
4. 用户确认 — 危险操作弹出确认对话框，但有 200ms 防抖保护，防止键盘连击导致误确认
5. Hook 校验 — 允许用户自定义安全规则，甚至可以动态修改工具的输入参数（比如自动给 rm 加上 --dry-run）

这五层任何一层拦住就不会执行，纵深防御。

66 个工具如何协同工作？

所有工具——读文件、写文件、跑命令、搜索、甚至第三方 MCP 工具——都遵循同一套接口规范。这意味着：

• 第三方工具和内置工具走完全相同的执行流水线，享受同样的安全检查和权限控制
• 只读工具自动并行执行，写操作自动串行，不需要手动管理并发
• 工具输出超过 100K 字符时自动落盘，模型只拿到摘要和文件路径，需要时再读取全文

多个 Agent 如何协作？

Claude Code 支持三种多 Agent 模式：

• 子 Agent — 主 Agent 分派任务给子 Agent，等结果返回
• 协调器 — 纯指挥官模式，协调器只能分配任务，不能自己读文件、写代码，强制分工
• Swarm — 多个命名 Agent 之间点对点通信，各自独立工作

为了防止多个 Agent 同时改同一个文件产生冲突，系统用 Git Worktree 给每个 Agent 一份独立的代码副本。

📚 专题深入

🎯 谁应该读这个？

📊 关键数据

🗺️ 阅读建议

只有 10 分钟？ → 读 快速入门

想理解核心原理？ → 按顺序读 主循环 → 上下文工程 → 工具系统

想自己造一个 AI Agent？ → 先读 最小必要组件，然后跟着 claude-code-from-scratch 的 11 章教程动手实现——~4000 行代码，每一步都对照源码讲解

想定制 Claude Code？ → 读 Hooks 与可扩展性 + 记忆系统 + 技能系统

关注安全？ → 读 权限与安全 + 代码编辑策略

🧭 路线图 / TODO

本仓库的分析基于约 v2.1.6x（2026 年 3 月底） 的源码快照。此后 Claude Code 又发布了 ~130 个版本，出现了一批快照里没有的重要新能力。这些内容没有源码可走读，我们计划换一种方法继续分析——黑盒实测 + 开源情报（官方 changelog、官方文档、公开博客）：安装最新版真实使用，观察行为、边界与失败模式，再对照官方资料交叉验证，推理出"它大概是怎么做的"（推理与实锤会明确区分）。

计划新增的专题：

• 可观测性：Metrics 与 Trace（#10 提议）—— Claude Code 自身如何打点：OpenTelemetry 指标/事件导出、成本核算、会话 transcript 作为 turn 级 trace。这部分快照里有源码，仍可源码走读
• 自治闭环：/goal、/loop 与 cron 调度（v2.1.71 / v2.1.139）—— 设定完成条件后跨 turn 自主工作直到达成；定时/模型自定节奏的循环任务
• Dynamic Workflows（触发词 "ultracode"）（v2.1.154–160）—— 用一段编排脚本在后台指挥几十到几百个 agent，带 token 预算控制、断点续跑与 /workflows 监控面板
• Auto Mode：权限进入分类器时代（v2.1.152 起免 opt-in）—— 从"规则 + 确认框"到 ML 分类器实时判断每个动作放行/拦截，并能理解口头边界（如"别 push"）
• 后台 Agent 舰队（v2.1.139–198）—— /bg 后台化、常驻 daemon、claude agents 全局面板、会话睡醒机制、完工自动 commit+push+draft PR、子 agent 默认后台运行
• 云端多 Agent 审查（v2.1.111–147）—— /ultrareview → /code-review：并行多 agent 分析 + 对抗式批判，带档位（low→ultra）与 CI 集成
• Agent Teams 与跨会话安全（v2.1.166–178）—— SendMessage 组队协作；"跨会话消息不携带用户权威"的防提示注入设计

欢迎在 issues 里投票或补充你最想看的主题。

🤝 贡献者

欢迎提 Issue 和 PR！如果你发现分析有误或有更好的理解角度，非常欢迎讨论。

🙏 致谢

感谢 LINUX DO 社区的支持与讨论。

💬 更多交流

加入 AI Agent 工坊 交流群

QQ 群号：1090526244

📈 Star History

📝 更新记录