我读完了 Claude Code 的全部源码，最大的发现是：它的架构简单到令人震惊

事情的起因

上周，有人发现 Anthropic 的 Claude Code npm 包里意外包含了 source map 文件。通过这个 60MB 的 .map 文件，社区还原了约 1884 个 TypeScript 源文件——这意味着 Claude Code 的完整内部实现被公开了。

作为一个每天都在用 AI 编程工具的开发者，我当然不能错过这个机会。

最大的发现：核心架构是一个 while 循环

我以为 Claude Code 的架构会是这样：

用户输入 → 意图分类器 → RAG 检索 → 任务规划器 → DAG 编排 → 执行器 → 输出

实际上，它的核心是这样的：

while True:
    response = call_claude(messages, tools)
    if no_tool_calls(response):
        return response.text
    for tool in response.tool_calls:
        result = execute(tool)  # 权限检查在这里
        messages.append(result)

点击放大

没有意图分类器。没有 RAG。没有 DAG。没有规划器。

就是一个 while 循环：调模型 → 执行工具 → 把结果喂回去 → 循环。

Anthropic 的设计哲学叫 "Less scaffolding, more model"——少搭框架，多信模型。当模型足够聪明时，复杂的编排框架反而是多余的。

五个让我印象深刻的设计

1. 工具并发分区

Claude Code 不会傻傻地逐个执行工具调用。它用 partitionToolCalls 函数自动把只读操作并行化（最多 10 个同时），写操作串行化。一个简单的 reduce 函数，把性能提升了好几倍。

2. grep 打败了 RAG

Anthropic 试过 RAG（向量检索），但内部测试发现直接用 ripgrep 搜索效果更好。理由很实际：不需要维护索引、不需要外部 embedding 服务、完全本地不泄露代码、精确匹配不会遗漏。

当模型够聪明（知道该搜什么）且上下文够大（200K tokens）时，暴力搜索赢了。

3. 五层权限模型

让 AI 操作文件系统和终端是很危险的。Claude Code 用五层检查来平衡能力和安全：工具自检 → 用户规则 → 沙箱策略 → 权限模式 → Hook 拦截。大多数操作在前两层就秒过了，只有"不寻常"的操作才弹确认。

4. 自动压缩而非丢弃

上下文窗口到 75-92% 时自动触发 compaction——把旧对话总结成摘要，保留关键信息，丢弃冗余细节。不是删除记忆，是整理记忆。

5. React 写的终端 UI

整个终端界面是用 React + Ink 写的——对话框、权限弹窗、进度条全是 React 组件。终端也可以组件化开发。

我做了一个免费教程网站

读源码是一件痛苦的事。1884 个文件、4 万多行核心代码，直接看很容易迷失。

所以我把学到的一切整理成了一个 8 章节的互动教程网站，用通俗的语言 + Mermaid 图表讲清楚每一个核心概念。不需要你读一行源码，就能理解 Claude Code 是怎么做出来的。

教程地址：https://stevenchouai.github.io/claude-code-sourcemap/

内容包括：

1. 核心理念 — 为什么一个 while 循环就够了
2. 启动流程 — CLI 工具的分层加载设计
3. Agent 循环 — QueryEngine 的流式多轮架构
4. 工具系统 — 8 个核心工具 + 并发优化
5. 安全模型 — 五层权限的分层防御
6. 上下文管理 — 压缩策略 + grep vs RAG
7. Sub-Agent — Task 工具和分身系统
8. 自己动手 — 50 行 Python 写出 Agent 核心

中英双语，免费开源。

对我的启发

这次源码阅读让我重新思考了 AI 工具开发：

不要过度设计。 一个 while 循环 + 好的工具 + 好的提示词，就是生产级 AI Agent 的全部。

信任模型的推理能力。 与其写一堆规则来帮模型做决定，不如给它好工具让它自己判断。

把精力放在工具和安全上。 这才是 Agent 开发中真正需要用心的部分。

如果你也对 AI Agent 的内部原理感兴趣，欢迎来看教程。如果觉得有用，给仓库点个 Star 就是最好的支持。

---

作者：Steven Chou · GitHub · X @StevenChouAI