Performingartsdredger454/Claude-code-open-explain

Claude-code-open-explain

深度解读 Claude Code 的架构设计、运行链路与工程取舍

<p align="center"> <strong>不只告诉你“它做了什么”，还会讲清楚“它为什么这样设计”</strong> </p> <p align="center"> <a href="#这个项目是什么">这个项目是什么</a> • <a href="#如果你是新手先看这里">新手导读</a> • <a href="#阅读路线">阅读路线</a> • <a href="#目录">目录</a> • <a href="#声明">声明</a> </p>

---

这个项目是什么

Claude Code 可以理解为一个运行在本地终端里的 AI 编程编排器。

它自己不是模型本身，而是站在模型和你的电脑之间，负责做这些事：

• 收集当前工作目录、Git 状态、用户配置等上下文
• 动态组装 System Prompt 和工具描述
• 把请求发给模型，并流式接收返回结果
• 在本地执行文件读写、Shell、搜索、MCP 等工具
• 在执行前做权限校验、安全检查和上下文管理

本仓库的目标，不是搬运源码，也不是只贴结论，而是把 Claude-code-open 这份公开源码里真正重要的设计讲明白，尤其面向第一次接触 Agent CLI、Prompt Cache、MCP、多 Agent 这些概念的读者。

更具体地说，这个项目想解决的是两件事：

1. 帮你先建立 Claude Code 的整体架构脑图
2. 再帮你真正理解“它为什么要这样设计”

当前状态

当前仓库处于 Wave 1 draft 阶段。

这表示：

• 章节主线已经建立起来了
• 大部分关键判断已经开始绑定源码 evidence
• 但 evidence registry、section manifest 和正文仍在持续收口

所以你现在看到的是一套正在快速变深、但仍在继续校准的源码导读，不是已经完全封板的最终版教材。

这个项目不是什么

• 不是 Claude Code 的官方文档
• 不是 Claude Code 的源码镜像仓库
• 不是“看一眼目录就下结论”的浅层解读

这里更像一份“源码导读 + 架构讲义”。

为什么值得读

如果你曾经好奇"AI 编程助手到底是怎么工作的"，Claude Code 是一个难得的学习样本。

它的价值不在于某个聪明的算法，而在于它展示了一个真实的工程问题：如何把一个强大但不可控的大模型，变成一个既能做事、又不会失控的本地工具。

这个问题听起来简单，但实际上牵扯到一系列相互制约的设计决策：

安全与自由的平衡 模型需要足够的权限才能帮你改代码、跑命令，但如果权限过大，一个判断失误就可能删掉重要文件。Claude Code 用多层权限系统、路径校验、命令分析来解决这个矛盾——既不是"什么都不让做"，也不是"什么都直接做"。

性能与成本的权衡 每次调用模型都要花钱、花时间。如果每轮都把所有上下文重新发一遍，成本会迅速失控。Claude Code 通过 Prompt Cache、上下文压缩、分层装配来优化这个问题——让模型既能看到足够信息，又不会每次都从零开始。

简单与完整的取舍 核心 Agent Loop 可以写得很简单，但真实产品还要处理启动优化、MCP 集成、多 Agent 协作、Feature Flag、错误恢复。Claude Code 的选择是：让核心循环保持直接，把复杂度推到外围层——这样系统既容易理解，又足够完整。

如果你以后想做 AI Coding Agent、带工具调用的终端助手、或者任何需要"让模型安全地操作本地环境"的应用，Claude Code 都是一个非常好的参考样本。

更重要的是，它展示了一种成熟的工程思维：

不是"先把功能堆上去，再想办法优化"，而是从一开始就让架构约束（比如缓存需求）反向塑造数据放置方式；不是"把所有逻辑都塞进主循环"，而是明确分层，让每一层各司其职；不是"追求最新技术"，而是在稳定性、性能、安全性之间找到可落地的平衡点。

这些工程取舍，才是这份源码最值得学习的地方。

如果你是新手，先看这里

先建立 5 个最小概念

1. System Prompt：给模型的长期规则，决定角色、边界和风格。
2. Tool：模型不能直接操作电脑，只能先请求工具，再由 CLI 代为执行。
3. Agent Loop：一次回答如果需要多个工具，就会不断重复“模型思考 -> 调工具 -> 回传结果”。 4