how-claude-code-works：一份能读进生产级 Agent 源码的逆向笔记
Deep dive into Claude Code internals — architecture, agent loop, context engineering, and more. / 深入解析 Claude Code 源码：架构、Agent 循环、上下文工程、工具系统等
秒懂
- 它是什么？
- 这个仓库把 50 万行 Claude Code 源码拆成 18 篇专题文档，覆盖主循环、上下文压缩、权限防御与多 Agent 协作。它的价值在于给出可验证的实现细节，而不是泛泛的架构图。
- 适合谁用？
- 想造自己的 Coding Agent 的工程师、需要给团队解释 Claude Code 行为边界的平台开发者，以及想理解上下文压缩或权限分类器如何落地的研究者，都值得把这份文档当起点。它给出的机制描述具体到可以复现，比如 4 级压缩的触发顺序、7 种 Continue Sites、tree-sitter 的 23 项检查。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 30 天前。
- 用什么语言写的？
- GitHub 没有给出这个仓库的主要语言。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
一份给读不下去源码的人准备的路线图
50 万行 TypeScript 的源码快照流到社区后，多数人面对的问题不是找不到资料，而是不知道从哪一行读起。这个仓库的解法很直接：让 Claude Code 自己配合读源码，再把过程沉淀成文档。作者承认自己也读不完这么大的项目，于是用 AI 辅助理解，把结论整理成 18 篇专题。每篇针对一个具体机制，比如主循环的故障恢复、上下文压缩的触发条件、权限系统的分层。它不是源码注释的搬运，而是按设计决策组织的分析笔记。对想造 Agent 的开发者来说，这份文档的价值在于告诉你生产级系统在哪些地方花了心思，而这些心思在 demo 项目里通常看不到。
从快照里挖出的三处关键设计
文档里最值得读的是几个反直觉的机制。第一是工具预执行：模型还在生成文本时，系统已经解析出它要读哪个文件并提前读取，用模型推理的 5 到 30 秒窗口把约 1 秒的工具延迟藏起来。第二是静默恢复：对话超长时悄悄压缩上下文并自动重试，token 上限到了就自动从 8K 升到 64K，整个循环有 7 种不同的继续策略。用户很少看到报错，不是因为没错误，而是大部分被内部消化了。第三是启动优化：9 个阶段的初始化任务并行执行，关键路径压到约 235ms。这三个设计都指向同一个目标，让用户觉得快，尽管模型推理本身就要几十秒。
4 级压缩流水线：上下文管理的细活
对话动辄上百万 token 时，压缩不是一刀切的摘要。文档描述的 4 级渐进式方案很具体：先裁剪历史消息里的大块工具输出，再去重，然后折叠不活跃的对话段落，最后才启动子 Agent 做摘要。每一级都可能释放足够空间，让后面的级别不必执行。压缩后系统会自动恢复最近编辑的 5 个文件内容，防止模型忘记刚才在改什么。这个设计说明一个道理：上下文管理不只是窗口大小的问题，而是如何在保留关键状态和节省 token 之间做分层决策。对想实现类似机制的开发者，这一章给出的细节比多数框架的文档都实在。
7 层防御：权限系统不是弹窗那么简单
让 AI 直接跑命令，安全设计就得靠多层拦截。文档列出了 7 层：工作区信任、权限模式、规则匹配、Bash 语法树分析、工具级校验、沙箱隔离、用户确认。最硬核的是第 4 层，用 tree-sitter 解析 Shell 命令的 AST，而不是正则匹配，覆盖 23 项静态检查，包括命令注入和环境变量泄露。用户确认框也不是孤立的，它和 Hook、LLM 分类器竞速，带 200ms 防抖。这套设计的关键在于任何一层拦住就不会执行，纵深防御的意义是单点失效不至于全盘崩溃。对做 Agent 安全的人来说，这一章值得反复读。
多 Agent 协作与工具系统的统一接口
数十个工具能协同工作，靠的是同一套接口规范。第三方 MCP 工具和内置工具走完全相同的执行流水线，享受同样的安全检查。只读工具自动并行，写操作自动串行，不用手动管理并发。工具输出超过 100K 字符时自动落盘，模型只拿到摘要和文件路径。多 Agent 场景下，系统提供子 Agent、协调器、Swarm 三种模式，用 Git Worktree 给每个 Agent 独立代码副本，避免同时改一个文件产生冲突。这些设计说明一个工程判断：Agent 系统的复杂度主要来自资源隔离和并发控制，而不是模型调用本身。
快照之后的逆向：黑盒分析的边界
仓库不满足于分析泄露快照，还继续追踪新功能。第 17 和第 18 篇覆盖 /goal、/loop 和 Auto Mode，这些是快照之后才出现的。作者明确标注这些章节基于静态串分析和明文反代抓包，属于黑盒逆向。这意味着细节可能有误差，比如 /loop 的解析规则或 Auto Mode 的分类器行为，都是观察推测而非源码确认。这种诚实标注值得肯定，但读者要明白边界：快照分析是白盒，新功能分析是灰盒。如果你要基于这些文档做工程决策，最好把黑盒逆向的部分当假设，而不是事实。
配套项目与文档的局限
仓库还链接了一个配套项目 Claude Code From Scratch，约 4300 行 TypeScript 和 Python 两个版本，13 章分步教程，clean-room 教育实现。这个项目适合动手验证文档里的概念，但要注意它是受 Claude Code 启发的实现，不是克隆，也不保证行为一致。文档本身有两个明显局限：一是基于 2026 年 3 月的泄露快照，Claude Code 持续更新，部分机制可能已变化；二是仓库不附带原始源码，你无法逐行核对分析结论。另外文档是中文写的，英文只有 README 的翻译版，非中文读者能获取的细节会少很多。
编辑结论
想造自己的 Coding Agent 的工程师、需要给团队解释 Claude Code 行为边界的平台开发者，以及想理解上下文压缩或权限分类器如何落地的研究者，都值得把这份文档当起点。它给出的机制描述具体到可以复现，比如 4 级压缩的触发顺序、7 种 Continue Sites、tree-sitter 的 23 项检查。但不要把它当官方架构说明书，README 自己声明内容来自独立研究与推理，且快照之后的新功能如 /goal、/loop、Auto Mode 是基于抓包的黑盒逆向，细节可能随 Claude Code 更新而失效。不适合只想学怎么用 Claude Code 的日常用户，也不适合需要逐行核对源码的严谨读者，因为仓库不附带原始代码，你无法验证每一处推断。动手前先确认两件事：文档基于 2026 年 3 月的泄露快照，之后的版本行为可能已变；配套的 clean-room 实现 Claude Code From Scratch 是教育项目，别把它当生产级参考。
社区笔记