系列说明
这套系列不是要复刻 Claude Code，也不是逐章翻译源码文档。
我更想做的是：把 Claude Code 源码里最值得学习的设计拆开，用普通开发者能理解的方式讲清楚。
Claude Code 表面是一个命令行工具，内部却更像一个 Agent Runtime。它要处理模型调用、工具执行、权限确认、上下文压缩、缓存成本、安全边界和长期记忆。单独看每个点都不复杂，组合起来才是它真正有价值的地方。
适合人群
- 普通程序员
- AI 编程工具用户
- 想做 AI Agent 的开发者
学习目标
- 理解 Claude Code 的整体运行架构
- 理解模型如何通过工具系统获得行动能力
- 理解提示词、上下文、缓存和权限如何共同约束 Agent 行为
- 提炼可以迁移到自己 Agent 项目里的工程模式
学习前准备
- 有基本编程经验
- 了解大模型对话和工具调用的基本概念
章节目录
19 章 01 Claude Code 的整体架构 从 main.tsx、feature()、REPL.tsx、AppState 和工具注册入口出发，理解 Claude Code 为什么是一套终端里的 Agent Runtime。 14 分钟 02 Claude Code 的 Agent Loop 从 query()、queryLoop()、State、Continue/Terminal reason、上下文预处理、模型调用和工具回写，拆解 Claude Code 的任务状态机。 15 分钟 03 Claude Code 的工具系统 从 Tool 接口、buildTool 默认值、tools.ts 注册过滤、MCP 合并、结果预算和渲染契约，拆解 Claude Code 如何把模型意图变成受约束的行动能力。 15 分钟 04 Claude Code 的工具执行流程 从 partitionToolCalls、runTools、runToolUse、checkPermissionsAndCallTool、StreamingToolExecutor 和 toolResultStorage，拆解 tool_use 到 tool_result 的完整执行链。 16 分钟 05 Claude Code 的计划模式 从 EnterPlanMode、ExitPlanMode、prepareContextForPlanMode、plan 文件、附件注入和权限恢复，拆解 Plan Mode 如何把探索、计划、审批和执行拆成状态机。 15 分钟 06 Claude Code 的系统提示词 从 systemPromptSection、SYSTEM_PROMPT_DYNAMIC_BOUNDARY、splitSysPromptPrefix、buildSystemPromptBlocks 和 buildEffectiveSystemPrompt，拆解系统提示词如何成为可缓存的行为控制面。 16 分钟 07 Claude Code 的提示词控制面 从行为引导措辞、模型发布注解、ant-only 门控、Undercover 模式和 GrowthBook 分流，拆解提示词如何变成可维护、可灰度、可回滚的行为控制面。 16 分钟 08 Claude Code 的工具提示词 从 BashTool、FileEditTool、FileReadTool、GrepTool、AgentTool 和 SkillTool 的 prompt 源码，拆解工具描述如何成为局部行为协议。 16 分钟 09 Claude Code 的上下文压缩 从 autoCompact、compactConversation、压缩提示词和微压缩入口拆解 Claude Code 如何在长任务里判断压缩时机、生成结构化摘要，并把必要工作现场接回下一轮。 18 分钟 10 Claude Code 的 Token 预算 从工具结果持久化、单消息聚合预算、ContentReplacementState 和 tokenCountWithEstimation 拆解 Claude Code 如何在内容进入上下文前控制大小，并避免并行工具调用导致系统性低估。 16 分钟 11 Claude Code 的 Prompt Cache 从 cache_control 断点、系统提示词分段、TTL 和 beta header 锁存、两阶段缓存中断检测、工具 Schema 缓存和动态内容后移几个源码机制，拆解 Claude Code 如何把 Prompt Cache 做成一套前缀稳定工程。 18 分钟 12 Claude Code 的权限系统 从 PermissionMode、PermissionRule、Bash 规则匹配、hasPermissionsToUseTool 三阶段管线、路径验证和危险规则剥离，拆解 Claude Code 如何把工具自动化放进可解释的安全边界。 17 分钟 13 Claude Code 的自动权限判断 从 classifyYoloAction、安全白名单、toAutoClassifierInput、二阶段 XML 分类器、转录投影、权限模板和拒绝追踪，拆解 Claude Code 的 auto 模式如何用独立分类器处理权限灰区。 16 分钟 14 Claude Code 的安全防线 从分类器输入隔离、路径和权限安全检查、Hooks 信任门控、退出码协议、沙箱适配器和 Bare Git Repo 防护，拆解 Claude Code 如何把文本风险收束到工具执行边界。 17 分钟 15 Claude Code 的多 Agent 机制 从 AgentTool、Fork、Coordinator、Teams、TaskList、Mailbox、权限同步和 Ultraplan 拆解 Claude Code 如何把单个 Agent Loop 扩展成可并行、可隔离、可审批的多 Agent 运行时。 24 分钟 16 Claude Code 的 Skill 与 Plugin 扩展系统 从 BundledSkillDefinition、loadSkillsDir、SkillTool、PromptCommand 白名单、MCP 技能桥接和 PluginManifest 拆解 Claude Code 如何把 Markdown、Hook、MCP、命令和市场打包成可治理的 Agent 能力扩展层。 22 分钟 17 Claude Code 的记忆系统 从 Memdir、Extract Memories、Session Memory、Transcript Persistence、Agent Memory、Team Memory 和 Auto-Dream 拆解 Claude Code 如何把会话信号转成可预算、可整理、可共享但受控的跨会话记忆。 28 分钟 18 Claude Code 的可观测性与版本演进 从 logEvent、AnalyticsSink、PII 类型标记、Datadog 允许列表、1P Exporter、OTel Span、Perfetto、优雅关闭和成本追踪拆解 Claude Code 如何让 Agent 行为可解释、可恢复、可演进。 22 分钟 19 Claude Code 的工程模式总结 把前面拆过的源码机制收束成可迁移的 Agent 工程模式：提示词控制面、缓存稳定、fail-closed、权限梯度、工具级提示词、结构化搜索、能力降维、可观测性和代码审查 Agent 落地。 20 分钟