在AI辅助编码的赛道上，Claude Code作为Anthropic推出的官方CLI工具，凭借强大的上下文管理、持久化记忆和智能工具调用能力，成为开发者提升效率的重要帮手。不同于普通的代码生成工具，Claude Code更像一个“智能编码伙伴”，能够理解项目规则、记住用户习惯、动态适配编码场景，甚至在对话过程中自动优化自身行为。本文将从核心架构出发，逐层拆解Claude Code的关键模块，包括Agent系统、Prompt拼接机制、Memory记忆系统、上下文窗口管理及Hooks扩展机制，带你读懂其背后的工作逻辑，让你不仅会用，更能理解其运作本质。
一、Claude Code核心架构总览：一个多模块协同的智能系统
Claude Code的核心架构围绕“对话驱动、工具赋能、记忆支撑”三大核心展开，整体可分为五大模块：Agent系统（任务执行核心）、Prompt系统（行为定义核心）、Memory系统（持久化记忆核心）、Context Window管理（上下文控制核心）和Hooks系统（扩展能力核心）。这些模块相互协同，构成了一个能够自主决策、持续学习、灵活扩展的智能编码助手。
简单来说，当用户输入一个编码需求（比如“帮我看看auth模块的bug”）时，Claude Code的工作流程大致如下：首先通过Prompt系统明确自身行为边界和任务目标，然后由Agent系统调用合适的工具（如读取文件、执行命令）获取关键信息，同时通过Memory系统调取历史记忆（如用户的编码偏好、项目规则）辅助决策，在对话过程中由Context Window管理模块动态压缩上下文、释放空间，确保对话流畅进行，最后通过Hooks系统执行自定义扩展逻辑（如日志记录、安全校验）。
整个系统的设计哲学是“高效、可控、可扩展”，既保证了AI决策的准确性和高效性，又通过灵活的配置和扩展机制，适配不同开发者和团队的个性化需求。接下来，我们将逐一拆解每个核心模块的工作原理。
二、Agent系统：Claude Code的“任务执行大脑”
Agent系统是Claude Code的核心执行单元，负责接收用户需求、调用工具、管理子任务，相当于整个系统的“大脑”。不同于单一的AI模型响应，Claude Code的Agent系统支持主Agent与子Agent协同工作，能够根据任务复杂度动态拆分任务、分配权限，确保任务高效推进。
2.1 Agent的核心类型与调用方式
Claude Code的Agent主要分为两种类型：主Agent和子Agent，两者协同工作，各司其职。主Agent负责接收用户的核心需求，统筹全局任务，决定是否需要拆分任务给子Agent；子Agent则负责执行具体的细分任务（如代码审查、记忆提取），执行完成后将结果反馈给主Agent，由主Agent汇总后回复用户。
子Agent的调用主要有两种方式：Fork模式和指定subagent_type模式，这两种方式的核心差异在于上下文继承和使用场景，具体区别如下：
Fork模式（不指定subagent_type）：子Agent继承主Agent的完整对话上下文，共享缓存，Prompt风格以“指令”为主，适合用于调查、研究类任务，比如“帮我分析这段代码的性能瓶颈”，主Agent可以Fork一个子Agent，让其专注于性能分析，同时共享当前的代码上下文和项目信息。
指定subagent_type模式：子Agent零上下文启动，拥有独立缓存，Prompt风格以“完整汇报”为主，适合需要独立视角或特定角色的任务，比如“帮我从安全视角审查这段迁移脚本”，主Agent可以指定一个“code-reviewer”类型的子Agent，让其以独立的安全审查角色开展工作，不受主上下文的干扰。
例如，当用户需要“找个独立视角看看这个迁移安全吗”时，主Agent会调用指定类型的子Agent，其调用逻辑如下（简化版）：
Agent(subagent_type="code-reviewer",prompt="Review migration 0042_user_schema.sql. Adding NOT NULL to 50M-row table with backfill. Is it safe under concurrent writes?")这个子Agent会以“代码审查者”的身份，独立审查迁移脚本的安全性，不继承主Agent的上下文，确保审查结果的客观性。
2.2 Agent的行为约束与工具调用规则
为了确保Agent的行为可控、高效，Claude Code为Agent设置了严格的行为约束，这些约束被注入到主模型的System Prompt中，核心包括三条：
Never delegate understanding：不允许将“理解需求”的任务委托给子Agent，主Agent必须先自身理解用户需求，再给出具体的执行指令，避免出现“子Agent理解偏差”导致任务失败。比如，用户要求“修复这个bug”，主Agent必须先明确bug的具体位置和原因，再给子Agent下达“修改某行代码”的具体指令，而不是简单地让子Agent“根据你的发现修复bug”。
Don't peek：在Fork子Agent执行任务时，主Agent不会实时读取子Agent的输出文件，而是等待子Agent执行完成后，通过通知机制接收结果，避免主Agent与子Agent之间出现“竞争条件”，确保任务执行的稳定性。
Don't race：在子Agent返回结果之前，主Agent不会猜测或编造结果，确保回复的准确性和可信度。比如，子Agent正在审查代码，主Agent不会提前给出“代码安全”或“存在漏洞”的结论，必须等待子Agent完成审查后，再根据其反馈汇总结果。
同时，Agent在调用工具时也有明确的偏好和规则，比如“优先使用专用工具，而非Bash命令”，例如读取文件时优先使用Read工具，而不是用Bash的cat命令；编辑文件时优先使用Edit工具，而不是用sed命令，这样可以提高工具调用的效率和准确性，同时降低操作风险。
三、Prompt系统：Claude Code的“行为准则手册”
Prompt系统是Claude Code的行为定义核心，负责告诉AI“你是谁、你能做什么、你该怎么做”。不同于传统的单一Prompt字符串，Claude Code的Prompt系统采用“数组拼接+缓存分级”的设计，能够兼顾性能和灵活性，同时确保AI的行为符合预期。
3.1 Prompt的总体结构与拼接流程
当Claude Code调用Claude API时，发送的请求中，System Prompt是一个数组，而非单个字符串，每个数组元素都有不同的缓存策略，这样的设计可以最大化利用Anthropic API的Prompt缓存功能，降低请求成本、提升响应速度。其总体结构如下：
{"model":"claude-sonnet-4-...","system":[{"type":"text","text":"静态内容...","cache_control":{"scope":"global"}},{"type":"text","text":"动态内容...","cache_control":null}],"messages":[{"role":"user","content":"<system-reminder>CLAUDE.md 内容...</system-reminder>"},{"role":"user","content":"帮我修复 bug"},{"role":"assistant","content":"让我看看..."}]}从结构上看，System Prompt主要分为两部分：静态部分和动态部分，中间通过一个“SYSTEM_PROMPT_DYNAMIC_BOUNDARY”分界线隔开，其拼接流程由src/constants/prompts.ts中的getSystemPrompt()函数控制，具体如下：
静态部分（全局可缓存）：包含AI的身份介绍、系统规则、编码指南、行为准则、工具使用偏好、语气风格和输出效率指南等内容，这些内容在所有用户之间共享，只要内容不变，就可以复用缓存，无需重新处理，从而节省时间和成本。
动态部分（不缓存）：包含Session指引、Memory行为规则、环境信息（OS、Shell、日期、模型名）、语言偏好、输出样式配置、MCP服务器指令和暂存区指令等内容，这些内容虽然标记为“动态”，但绝大部分在会话内保持不变，通过memoize缓存，只在首次调用时计算一次。其中，MCP服务器指令是唯一的变量，因为MCP服务器可能在两个对话回合之间连接或断开，需要每次重新计算。
需要注意的是，CLAUDE.md（项目规则文件）的内容并不在System Prompt中，而是作为第一条User Message注入到对话中，这样设计的原因是CLAUDE.md内容可能很大，放在System Prompt中会干扰全局缓存，而放在消息中可以利用消息级缓存，同时避免占用System Prompt的缓存空间。
3.2 Prompt的缓存策略：静态与动态的协同优化
Prompt的缓存策略是Claude Code性能优化的关键之一，其核心是根据内容的“复用性”，将System Prompt分为全局可缓存和不缓存两部分，具体如下：
全局可缓存（cacheScope: 'global'）：包含身份介绍、系统规则、编码指南等静态内容，这些内容在所有用户之间共享，只要内容不变，就可以复用缓存，无需重新处理，从而大幅降低API请求的成本和响应时间。
不缓存（cacheScope: null）：包含Memory规则、环境信息、MCP服务器指令等内容，这些内容虽然在会话内不变，但不同用户、不同会话的内容可能不同，因此不通过API缓存，但通过memoize在会话内保持不变，避免重复计算。
其代码实现位于src/utils/api.ts的splitSysPromptPrefix()函数中，该函数会找到静态部分和动态部分的分界线，将System Prompt拆分为四个块：计费头（不缓存）、CLI前缀（不缓存）、静态内容（全局缓存）和动态内容（不缓存），确保缓存策略的落地。
3.3 易混淆点：Memory内容的注入路径
很多人会混淆“Memory相关规则”和“Memory实际内容”的注入位置，实际上，两者被分别注入到不同的地方，职责完全不同：
Memory行为规则：注入到System Prompt的动态部分，是一段固定的模板文本（约3K tokens），包含记忆的4种类型定义、如何保存记忆、何时访问记忆、什么不该保存等规则，告诉AI“怎么用记忆”，但不包含任何用户数据。这段内容通过systemPromptSection缓存，会话内只计算一次，所有用户的规则模板都是相同的。
Memory实际内容：注入到第一条User Message中，与CLAUDE.md一起被包裹在<system-reminder>标签中，包含用户的具体记忆数据（如用户偏好、项目信息）、CLAUDE.md的完整内容和当前日期，告诉AI“记忆里有什么”。这段内容通过memoize缓存，会话内每个回合的值相同，即使后台写入了新的记忆，本会话也无法看到，需要等到下一次会话才能加载。
这种分离设计的核心优势是：规则具有通用性，适合放在System Prompt中复用缓存；而记忆内容具有用户特异性，放在User Message中可以避免干扰全局缓存，同时确保每个用户的记忆数据独立、安全。
四、Memory系统：Claude Code的“持久化记忆大脑”
Memory系统是Claude Code最具特色的模块之一，它让AI能够“记住”跨会话的信息，包括用户的身份、偏好、项目上下文、反馈意见等，从而实现“持续学习”，让AI的响应越来越贴合用户的需求。Claude Code的Memory系统采用六层架构，覆盖了从单会话到跨会话、从个人到团队的全场景记忆需求，设计精巧且实用性强。
4.1 Memory系统的六层架构
Claude Code的Memory系统从低到高分为六层，每层负责不同场景的记忆管理，层层递进，构成了完整的记忆体系，具体如下：
4.1.1 层级1：Auto Memory（跨会话持久化）
Auto Memory是最基础的记忆层级，负责跨会话持久化用户的核心记忆，目录位于~/.claude/projects/<项目路径>/memory/，包含以下文件：
MEMORY.md：记忆索引文件，最多200行、25000字节，注入到第一条User Message中，每行指向一个具体的记忆文件，方便AI快速浏览有哪些记忆。
user_role.md：用户相关记忆，记录用户的身份、技能水平、偏好等信息，比如“用户是有10年Go经验的高级工程师，第一次接触React前端”。
feedback_testing.md：反馈相关记忆，记录用户对AI工作方式的指导，比如“不要在测试中mock数据库，曾因此出过生产事故”。
project_goals.md：项目相关记忆，记录项目的动态、目标、截止日期等信息，比如“周四开始代码冻结，手机端要发版”。
reference_linear.md：外部引用记忆，记录外部系统的指引，比如“pipeline bug在Linear的INGEST项目追踪”。
Auto Memory的触发方式是：每次查询结束后，后台Fork一个子Agent，自动提取对话中的有用信息，写入对应的记忆文件，无需用户手动操作。其核心代码位于src/services/extractMemories/目录下。
4.1.2 层级2：Session Memory（单会话内持久化）
Session Memory负责单会话内的结构化笔记，记录当前会话的任务状态、文件信息、错误记录等内容，方便AI在会话过程中快速回顾上下文，同时为后续的自动压缩提供支持。其文件位于~/.claude/session-<id>/memory/MEMORY.md，是一个结构化的Markdown文件，包含9个Section：
Session Title：会话的简短标题（5-10个单词），用于快速识别会话主题。
Current State：当前正在处理的任务，以及未完成的任务。
Task specification：用户要求构建的内容，以及相关的设计决策。
Files and Functions：重要的文件及其包含的内容。
Workflow：常用的Bash命令及其执行顺序。
Errors & Corrections：遇到的错误及其解决方法，以及失败的尝试。
Codebase and System Documentation：重要的系统组件及其工作原理。
Learnings：有效的方法、无效的方法以及需要避免的问题。
Key results：用户要求的具体输出结果。
Worklog： step-by-step的工作记录，简洁明了。
Session Memory的触发条件是：当对话的token数超过阈值（至少10K tokens）、两次更新间至少增长5K tokens，且两次更新间至少有3次工具调用时，后台Fork子Agent自动更新，确保Session Memory始终反映当前会话的最新状态。
4.1.3 层级3：AutoDream（跨会话离线巩固）
AutoDream负责跨会话的离线记忆巩固，相当于AI的“睡眠整理”功能，能够从多个会话的碎片信息中提炼出稳定、有价值的知识，写入Auto Memory中，让记忆更具系统性。其触发条件是：距离上次巩固至少24小时，且至少有5个新的会话，触发后，后台Fork子Agent，读取多个会话的记录和现有记忆，进行高层次的整合。其核心代码位于src/services/autoDream/目录下。
4.1.4 层级4：Agent Memory（角色分域持久记忆）
Agent Memory是按角色分域的持久记忆，用于存储不同Agent角色的专属记忆，避免不同角色的记忆相互干扰。其分为三种scope（作用域）：
user：用户级记忆，路径为~/.claude/agent-memory/<type>/，跨项目共享，记录用户针对所有项目的通用偏好。
project：项目级记忆，路径为<cwd>/.claude/agent-memory/<type>/，可在项目内共享，记录项目专属的Agent记忆。
local：本地级记忆，路径为<cwd>/.claude/agent-memory-local/<type>/，仅本地可见，记录个人专属的Agent记忆。
其核心代码位于src/tools/AgentTool/agentMemory.ts，负责Agent记忆的路径解析和scope管理。
4.1.5 层级5：Team Memory（团队共享记忆）
Team Memory用于团队共享记忆，方便团队成员之间同步项目规则、反馈意见等信息，目录位于~/.claude/projects/<项目路径>/memory/team/，支持通过Anthropic API进行checksum增量上传和同步，同时具备严格的安全机制，通过40+条gitleaks规则进行secret扫描，防止敏感信息泄露。其核心代码位于src/services/teamMemorySync/目录下。
4.1.6 层级6：CLAUDE.md（用户手动维护）
CLAUDE.md是用户手动维护的记忆层级，用于记录项目规则、编码规范等固定信息，支持全局、项目级和本地级三个层级，加载优先级从低到高依次为：/etc/claude-code/CLAUDE.md（企业管理级）、~/.claude/CLAUDE.md（用户级）、项目根目录/CLAUDE.md（项目级）、项目根目录/.claude/CLAUDE.md（项目隐藏级）、项目根目录/.claude/rules/*.md（项目规则目录）、项目根目录/CLAUDE.local.md（本地级），后加载的内容会覆盖先加载的内容。CLAUDE.md还支持@include指令，可引用其他文件，方便规则的复用和管理。
4.2 Auto Memory系统详解：核心记忆的写入与提取
Auto Memory是整个Memory系统的核心，负责跨会话的核心记忆管理，其写入和提取机制直接决定了AI的“记忆能力”。下面我们详细拆解Auto Memory的目录结构、记忆类型、写入路径和提取流程。
4.2.1 目录结构与文件格式
Auto Memory的目录位于~/.claude/projects/<sanitized-git-root>/memory/，其结构如下：
~/.claude/projects/<sanitized-git-root>/memory/ ├── MEMORY.md# 索引文件（≤200行，≤25000字节）├── user_role.md# type: user — 用户相关记忆├── user_frontend_level.md# type: user — 同一类型的另一个文件├── feedback_testing.md# type: feedback — 反馈相关记忆├── project_auth_rewrite.md# type: project — 项目相关记忆├── reference_linear.md# type: reference — 外部引用记忆└── team/# Team Memory 子目录├── MEMORY.md ├── ci_gotchas.md └── deploy_rules.md需要注意的是，四种记忆类型（user/feedback/project/reference）是通过每个记忆文件frontmatter中的type字段标注的，不是“每种类型一个文件”，同一类型可以有多个文件，每个文件聚焦一个具体主题。例如，user类型可以有user_role.md、user_frontend_level.md两个文件，分别记录用户的身份和前端水平。
每个记忆文件的格式如下（包含frontmatter和正文）：
--- name: 用户是高级后端工程师 description: 用户是一名有10年Go经验的高级工程师，第一次接触React前端 type: user --- 用户是一名高级后端工程师，深耕Go语言十年。 目前第一次接触项目的React前端部分。 解释前端概念时，应该用后端类比来帮助理解。 比如把组件生命周期类比为请求处理中间件链。MEMORY.md索引文件的格式如下，每行指向一个记忆文件，包含记忆的核心信息，方便AI快速浏览：
- [用户是高级后端工程师](user_role.md) — Go专家，React新手，用后端类比解释前端 - [测试必须用真实数据库](feedback_testing.md) — 不要 mock 数据库，曾因此出过生产事故 - [Auth中间件重写](project_auth_rewrite.md) — 法务合规驱动，不是技术债清理 - [Linear项目INGEST](reference_linear.md) — pipeline bug 在这里追踪4.2.2 四种记忆类型的核心用途
四种记忆类型是语义分类标签，每种类型有明确的用途、保存时机和示例，具体如下：
user（用户记忆）：用于记录用户的角色、偏好、知识水平，当了解到用户的任何个人信息时保存，例如“用户是数据科学家，专注于日志分析”。
feedback（反馈记忆）：用于记录用户对AI工作方式的指导，当用户纠正或确认AI的做法时保存，例如“不要在测试中mock数据库”。
project（项目记忆）：用于记录项目的动态、目标、截止日期，当了解到代码或git无法推断的项目信息时保存，例如“周四开始代码冻结，手机端要发版”。
reference（引用记忆）：用于记录外部系统的指引，当了解到外部资源的位置和用途时保存，例如“pipeline bug在Linear的INGEST项目追踪”。
4.2.3 记忆写入的两条路径
Claude Code的长期记忆写入有两条独立路径，互斥但互补，确保记忆写入的灵活性和可靠性：
路径A：主模型直接写。由System Prompt中的memory行为指令驱动，当用户明确要求“记住某个信息”时（比如“记住我喜欢用tabs缩进”），主Agent直接调用Write工具，将信息写入对应的记忆文件。这种路径的开关由isAutoMemoryEnabled()控制，不受其他flag影响。
路径B：后台extractMemories子Agent自动提取。由stopHooks.ts中的extractMemories()函数驱动，当对话回合结束后，后台Fork一个子Agent，自动分析对话内容，提炼值得保存的信息，写入记忆文件。这种路径的开关由tengu_passport_quail feature flag控制，且如果主模型在本轮已经写过记忆文件，路径B会跳过，避免冲突。
4.2.4 记忆提取的完整流程
记忆提取（路径B）的完整流程包含5重门禁、节流检查、Fork子Agent执行等步骤，具体如下：
检查5重门禁：确保是主Agent（不是子Agent）、tengu_passport_quail flag为true、Auto Memory功能已启用、不在远程模式、没有正在进行的提取（互斥锁），全部通过后才能进入下一步。
计算新消息数量：基于游标lastMemoryMessageUuid，计算上次提取后新增的消息数量，确保子Agent只分析最新的对话内容。
检查互斥条件：如果主Agent在本轮已经写过记忆文件，就跳过提取，避免冲突，只推进游标。
节流检查：由tengu_bramble_lintel flag控制，默认每1轮执行一次提取，设为2则每隔1轮执行一次，会话结束时的尾随执行跳过节流。
扫描现有记忆文件：构建现有记忆清单，方便子Agent判断哪些记忆需要更新、哪些需要新增。
构建提取Prompt：向子Agent发送提取指令，明确可用工具、记忆类型、保存规则等。
Fork子Agent执行提取：子Agent拥有受限权限，只能读代码和写memory目录，最多执行5轮工具调用（通常2-4轮即可完成：第1轮读取需要更新的文件，第2轮写入文件，偶尔3-4轮更新索引），避免陷入无限循环。
更新游标：提取成功后，将游标推进到最后一条消息，记录分析数据。
4.3 Memory系统的长度限制与截断策略
为了确保Memory系统不占用过多的存储空间和上下文空间，Claude Code在记忆的存储、召回、同步、压缩各环节都设有明确的限制，以下是核心限制的汇总：
MEMORY.md索引文件：最多200行、25000字节，超限后截断到前200行，并追加警告。
记忆文件扫描：最多扫描200个文件，解析frontmatter时只读取前30行。
记忆召回注入：单文件最多200行、4096字节，会话累计注入不超过61440字节（60KB），超限后停止注入新记忆。
Session Memory：单Section最多2000字符，总计不超过12000 tokens，压缩时进一步截断到8000字符/Section。
Team Memory：单文件最多250000字节，单次PUT请求最多200000字节，超出后分批上传，服务端有动态条目数上限。
这些限制的设计哲学是“从松到紧”，写入时相对宽松，召回注入时逐层收紧，确保上下文窗口预算始终可控，同时不影响记忆的实用性。
五、Context Window管理：Claude Code的“上下文管家”
Claude模型有固定的上下文窗口限制（比如200K tokens），而一次完整的编码会话（文件读取、工具调用、搜索结果）很容易积累大量tokens，若不做处理，会导致API报错或模型无法生成足够长的回复。因此，Claude Code设计了四级渐进式压缩流水线，负责动态管理上下文窗口，在腾出空间的同时，保留关键信息，兼顾效率和实用性。
5.1 压缩的核心约束与阈值
Claude Code的压缩机制需要同时满足四个核心约束：腾出空间（为后续对话预留token预算）、保留关键信息（当前任务状态、未完成工具调用、用户最新指令）、复用Prompt缓存（避免成本翻倍）、不阻塞用户（后台完成压缩）。为了实现这些约束，系统设置了明确的压缩阈值，位于src/services/compact/autoCompact.ts中：
AUTOCOMPACT_BUFFER：13000 tokens，为自动压缩预留的空间。
WARNING_BUFFER：20000 tokens，警告阈值，超过后提示用户上下文空间不足。
ERROR_BUFFER：20000 tokens，错误阈值，超过后可能导致API报错。
MANUAL_COMPACT_BUFFER：3000 tokens，手动执行/compact命令时预留的空间。
MAX_SUMMARY_TOKENS：20000 tokens，摘要的最大长度。
MAX_CONSECUTIVE_FAILURES：3次，连续压缩失败3次后放弃。
压缩的触发阈值由getAutoCompactThreshold()函数计算，等于有效上下文窗口大小（模型上下文窗口大小减去预留输出token数）减去AUTOCOMPACT_BUFFER，例如，模型上下文窗口为200K tokens，预留输出20K tokens，有效窗口为180K tokens，触发自动压缩的阈值就是180K - 13K = 167K tokens。
5.2 四级渐进式压缩流水线
Claude Code在每次API调用前，会按固定顺序执行四级压缩流水线，各级不互斥，可在同一个查询内依次运行，从最轻量的裁剪到全量摘要，逐步释放上下文空间：
5.2.1 Level 1：Snip Compact（裁剪历史）
这是最轻量的压缩方式，几乎零API开销，核心是从对话历史的头部直接删除最旧的消息，同时采用“protected tail”策略——最后一条assistant消息及其之后的消息永远不被裁剪，确保当前任务的上下文不丢失。裁剪的数量按token预算计算，被裁剪的消息UUID会存入snipMetadata.removedUuids，且不修改REPL的完整滚动历史，只影响发给API的消息数组。
Snip Compact可通过/snip命令手动触发，也会在每次查询前自动运行snipCompactIfNeeded()函数，释放的token数会传递到下游的自动压缩阈值判断，确保阈值计算的准确性。需要注意的是，Snip Compact是ANT-only功能，在外部公开版本中被DCE（死代码消除）删除。
5.2.2 Level 2：Micro Compact（压缩工具结果）
Micro Compact负责清除旧的工具调用结果内容，将大块输出替换为“[Old tool result content cleared]”，保留消息结构，不删除消息本身，从而释放大量token空间。可压缩的工具包括Read、Bash、Grep、Glob、WebSearch等，其执行有两条路径：
Time-based Microcompact（基于时间间隙）：优先执行，若当前时间与最后一条assistant消息的时间间隔≥60分钟（Anthropic API缓存的TTL为1小时），则清除旧工具结果，保留最近5个，同时重置Cached MC状态。
Cached Microcompact（基于缓存编辑API）：若时间间隙不足60分钟，则通过API的cache_edits指令，让服务端删除缓存中的工具结果，本地消息内容不修改，避免破坏缓存。
其中，Cached Microcompact是ANT-only功能，外部公开版本中仅保留Time-based Microcompact。
5.2.3 Level 3：Context Collapse（上下文折叠）
这是最独特的压缩方式，采用“投影”而非“改写”的思路，不修改持久化的对话历史，而是在生成API prompt时，动态折叠旧消息段，用摘要占位符替代，类似IDE中的代码折叠——折叠后看到摘要，展开后原文仍在。
Context Collapse维护一个append-only的commit log，记录被归档的消息范围和摘要内容，每次查询前，通过projectView()函数重放commit log，生成折叠后的投影视图。其触发阈值为双级：当上下文达到有效窗口的90%时，将旧消息段入队；达到95%时，强制触发ctx-agent生成摘要，执行折叠。
Context Collapse与Auto Compact互斥，当Context Collapse开启时，Auto Compact会被抑制，避免两者竞争上下文空间。需要注意的是，这也是ANT-only功能，外部公开版本中被DCE删除。
5.2.4 Level 4：Auto Compact与Reactive Compact（全量压缩）
当前三级压缩不足以将token控制在阈值内时，进入全量压缩，分为两种模式：
Auto Compact（主动式，公开功能）：在API调用前检测到token超阈值时触发，先尝试用Session Memory进行压缩（trySessionMemoryCompaction()），若Session Memory存在且有效，就用其替代旧消息，保留尾部原文，无需额外API调用；若失败，则Fork子Agent生成对话摘要（≤20K tokens），替换所有旧消息，同时恢复关键文件和Skill定义。
Reactive Compact（反应式，ANT-only）：在API调用后收到413 prompt_too_long错误时触发，先尝试Context Collapse drain（提交所有入队的折叠），若失败，再执行全量摘要压缩，同时还能处理媒体过大错误（剥离过大图片/PDF），最大化利用上下文空间。
对于外部公开版本，实际可用的压缩路径只有Time-based Microcompact、Session Memory Compact（若开启）和Full Compact，其余功能均被DCE删除。
六、Hooks系统：Claude Code的“扩展插件机制”
Hooks系统是Claude Code的扩展能力核心，允许开发者在系统的关键时刻插入自定义逻辑，就像Git Hooks一样，能够灵活扩展系统的功能，满足个性化需求。Hooks支持多种事件类型和Hook类型，执行机制安全可控，是团队定制化Claude Code的重要方式。
6.1 Hook的事件类型
Claude Code支持25+种Hook事件类型，覆盖工具调用、会话生命周期、压缩、子Agent、配置变更等多个场景，核心事件类型如下：
工具相关：PreToolUse（工具执行前，可阻止执行）、PostToolUse（工具执行后，可检查结果）、PostToolUseFailure（工具执行失败后）、PermissionDenied（权限被拒绝后）、PermissionRequest（权限请求时）。
会话生命周期：UserPromptSubmit（用户提交消息时）、SessionStart（会话开始时）、SessionEnd（会话结束时）、Stop（模型完成回答时）、StopFailure（Stop Hook失败时）。
压缩相关：PreCompact（压缩前）、PostCompact（压缩后）。
子Agent相关：SubagentStart（子Agent启动时）、SubagentStop（子Agent停止时）。
配置变更：ConfigChange（配置变更时）、CwdChanged（工作目录变更时）、FileChanged（文件变更时）。
6.2 Hook的配置示例与执行机制
Hook的配置位于~/.claude/settings.json中，支持按事件类型匹配，指定自定义逻辑，示例如下：
{"hooks":{"PreToolUse":[{"matcher":"Bash","hooks":[{"type":"command","command":"echo '工具 $TOOL_NAME 即将执行: $TOOL_INPUT' >> ~/claude-audit.log"}]}],"Stop":[{"matcher":"*","hooks":[{"type":"command","command":"notify-send 'Claude 完成了回答'"}]}]}}这个配置表示：当执行Bash工具前，将工具名称和输入写入审计日志；当模型完成回答时，发送系统通知。
Hook的执行机制如下：当某个事件触发时，系统会按来源优先级（从低到高）加载Hook：userSettings（全局）→ projectSettings（项目共享）→ localSettings（本地私有）→ policySettings（企业管理）→ pluginHooks（插件注册）→ sessionHooks（会话临时），然后执行Hook，每个Hook有10分钟的超时保护，执行结果分为三种：退出码0（成功）、退出码2（阻塞性错误，可能阻止后续操作）、其他退出码（非阻塞性警告）。
6.3 四种Hook类型
Claude Code支持四种Hook类型，每种类型有不同的用途和示例，具体如下：
command：执行Shell命令，用于简单的系统操作，例如记录日志、发送通知。
prompt：让LLM进行验证，用于复杂的逻辑判断，例如检查输入是否安全。
agent：多轮Agent验证，用于复杂的安全审查、代码校验等任务。
http：POST到外部服务，用于与外部系统集成，例如将Hook事件同步到企业审计系统。
七、总结：Claude Code的核心优势与应用场景
通过对Claude Code核心模块的拆解，我们可以发现，它之所以能成为优秀的AI编码助手，核心优势在于“智能协同、持续学习、灵活扩展”：Agent系统实现了任务的高效拆分与执行，Prompt系统确保了AI行为的可控性与一致性，Memory系统让AI能够持续学习用户偏好和项目规则，Context Window管理确保了对话的流畅性，Hooks系统则提供了强大的扩展能力，适配不同场景的个性化需求。
Claude Code的核心应用场景包括：
代码开发与调试：帮助开发者读取代码、分析bug、编写测试用例，提升编码效率。
项目管理：记录项目目标、截止日期、任务状态，同步团队信息，提升协作效率。
代码审查：通过子Agent进行独立的代码审查，确保代码质量和安全性。
团队协作：通过Team Memory共享项目规则、反馈意见，实现团队知识同步。
对于开发者而言，深入理解Claude Code的底层架构，不仅能更好地使用工具，还能通过自定义Hook、配置CLAUDE.md等方式，让工具更贴合自己的编码习惯和团队需求。未来，随着AI技术的不断发展，Claude Code的记忆能力、工具调用能力和扩展能力还将不断提升，成为开发者不可或缺的“智能编码伙伴”。
