基于 1,884 个 TypeScript 文件、512,000+ 行代码的全量源码分析。 揭示 Anthropic 旗舰级 AI 编程工具背后的工程哲学：1.6% 的 AI 决策逻辑 + 98.4% 的确定性基础设施。
Claude Code 的架构遵循"最小脚手架、最大操作线束"原则。模型负责推理，而线束（harness）负责执行。
整个系统被分解为 5 个架构层、7 个功能组件，其中核心的 Agent Loop 只是一个简单的 while-true 循环——
真正的工程复杂性存在于围绕它的上下文管理、权限控制、安全防护和状态持久化等子系统中。
Claude Code 的 Agent Loop 仅占总代码量的约 1.6%，其余 98.4% 都是确定性的基础设施代码。 这意味着整个系统的工程复杂度并不在"如何让模型做决策"上，而在于"如何安全、可靠、高效地执行模型的决策"。 Agent Loop 是一个 AsyncGenerator，遵循 ReAct 模式，但真正的精华在于围绕它构建的五层上下文压缩管线、七层安全防护机制和四级记忆层级体系。
Agent Loop 的核心是 query.ts 中的 queryLoop() 异步生成器。它遵循经典的 ReAct（Reasoning + Acting）模式：
收集上下文 → 调用模型 → 分发工具 → 验证结果。每次迭代都是一个完整的 9 步管线。
模型回复中不包含任何 tool_use，说明任务完成或模型选择直接回答。
达到配置的最大交互轮数限制，防止无限循环。
上下文窗口无法进一步压缩，系统安全退出。
某个 Hook 事件处理器主动中断了循环。
用户通过 Ctrl+C 或程序信号主动中止。
Claude Code 使用 StreamingToolExecutor 进行工具执行：只读工具（如文件读取、搜索）可以并发执行以降低延迟，
而修改状态的工具（如文件写入、Bash 命令）则串行执行以保证一致性。当流式执行器不可用时，自动降级为同步的 runTools 回退路径。
Claude Code 的工具系统是其执行能力的核心。系统维护一个最多 54 个内置工具的工具池，通过 assembleToolPool()
动态装配。工具分为并发安全型和独占型，分别对应不同的执行策略。
Read, Write, Edit, Glob, Grep 等。提供文件读写、搜索、模式匹配能力。Edit 工具支持精确字符串替换。
真正的编排骨干。用于运行测试、构建项目、Git 操作、进程管理。支持超时和后台执行。
WebFetch 和 WebSearch，用于获取网页内容、API 调用和网络搜索。
生成独立的子代理处理复杂子任务。拥有隔离的上下文窗口，仅向父代理返回摘要。
通过 Model Context Protocol 连接外部服务（Slack、GitHub 等），动态扩展工具池。
图片生成、TodoWrite 任务追踪、AskUserQuestion 用户交互等辅助功能。
工具分类为 concurrent-safe（并发安全）和 exclusive（独占）两类。并发安全型工具如文件读取、搜索等可以并行执行， 独占型工具如文件写入、Bash 命令等必须串行执行。这种分类机制在保证正确性的前提下最大化了执行效率。
权限系统是 Claude Code 安全架构的核心支柱。它实现了"deny-first with human escalation"（拒绝优先、人工升级）的安全策略， 提供 7 种权限模式形成一个信任谱——从最保守的 plan 模式到完全放开的 bypassPermissions 模式。
| 模式 | 信任级别 | 行为描述 |
|---|---|---|
| plan | 最保守。模型只能制定计划，不能执行任何实际操作。 | |
| default | 默认模式。读操作自动放行，写操作和 Bash 命令需要用户确认。 | |
| acceptEdits | 自动接受文件编辑，但 Bash 命令仍需确认。 | |
| auto | ML 分类器自动评估操作安全性。学习用户信任模式，减少审批疲劳。 | |
| dontAsk | 不弹出确认对话框，但仍有规则层面的限制。 | |
| bypassPermissions | 完全放开。跳过所有权限检查，仅限受信环境使用。 | |
| bubble (内部) | 子代理内部模式。权限请求冒泡到父代理的终端进行裁决。 |
权限规则的求值顺序是"deny 优先"：任何一条 deny 规则命中即拒绝操作，即使有其他 allow 规则匹配。 无法识别的操作一律升级为人工确认。这种设计确保了安全下限——宁可多问一次用户，也不放过一次潜在的危险操作。 此外，会话恢复时权限不会被恢复（no permission restoration on resume），每次恢复都重新建立信任。
上下文窗口是整个系统的绑定资源约束。Claude Code 为此构建了一套精密的四级记忆层级体系和五层压缩管线， 确保在有限的 token 预算内最大化信息密度。
记忆检索不使用向量数据库或 embedding，而是基于 LLM 扫描文件头部的透明机制。 这种"文件即记忆"的设计让记忆对用户完全可见可编辑——用户直接编辑 CLAUDE.md 文件就能修改 AI 的行为。
在每次调用模型 API 之前，系统都会依次执行 5 个压缩阶段，确保上下文不超出 token 限制：
Claude Code 从设计第一天起就假设 token 是稀缺资源。上下文组装使用 memoization 避免重复计算， 使用 lazy loading 确保未使用的指令不消耗 token。整个压缩管线的设计目标不是"塞入更多信息"， 而是"在有限空间内保留最高价值的信息"。
Claude Code 采用经典的"纵深防御"（Defense in Depth）策略，部署 7 个独立的安全层。 任何一层都可以独立阻止一个操作——即使其他层全部失效，单层也能兜底。
安全评估不仅看操作类型，还看操作的可逆性。读取文件是高度可逆的（无副作用）， 写入文件是中等可逆的（可通过 Git 回滚），而删除文件或执行不可逆 Bash 命令则需要更高的信任级别。 这种基于可逆性的风险评估贯穿整个权限系统的设计。
Claude Code 提供了四种渐进式的扩展机制，按上下文开销从低到高排列： Hooks → Skills → Plugins → MCP Servers。每种机制在不同的抽象层级上扩展系统能力。
Hook 是最轻量的扩展机制，通过事件监听器在 Agent Loop 的生命周期关键节点注入自定义逻辑。 每个 Hook 可以修改工具输入/输出、注入额外上下文、甚至阻止操作执行。
上下文开销最低。通过 JSON 配置事件监听器，不消耗 token。适合安全策略注入和 CI/CD 集成。
中等开销。以 Markdown 文件形式提供领域知识和最佳实践，按需加载到上下文。
较高开销。可注册新工具和指令，但会占用上下文窗口空间。
最高开销也最强大。通过 Model Context Protocol 连接外部服务，提供实时数据和操作能力。
Claude Code 采用"主代理 + 子代理"（lead-agent-plus-subagents）模式。 主代理负责协调和决策，子代理负责执行具体的子任务。每个子代理运行在隔离的上下文窗口中， 仅向父代理返回结果摘要——这种设计防止了子代理的对话历史膨胀父代理的上下文。
每个子代理拥有独立的上下文窗口。Sidechain 日志独立存储子代理的对话历史，防止父上下文膨胀。
子代理使用内部的 bubble 权限模式——遇到需要权限的操作时，请求冒泡到父代理的终端进行裁决。
子代理只能访问主代理分配的工具子集，不能直接访问所有系统资源或用户交互工具。
Claude Code 的状态管理采用"append-only"（仅追加）设计，所有会话操作都以 JSONL 格式追加写入日志文件。 这种设计让系统具备了强大的恢复能力——可以从日志重建任意时间点的状态，支持恢复（resume）、 分叉（fork）和回退（rewind）操作。
每次工具调用、模型响应、权限决策都以 JSON 行追加到会话日志。支持断点续传和状态恢复。
跨会话的全局历史记录，用于长期趋势分析和上下文关联。
使用文件锁机制协调多个 Claude Code 实例的并发访问，防止状态文件冲突。
从 append-only 日志重建完整状态，支持 resume（恢复）、fork（分叉）和 rewind（回退）。
多个独立的安全层共享失败模式。即使 6 层防护全部失效，第 7 层仍能兜底。 安全不是单点机制，而是多层冗余的系统工程。
用户通过 7 种权限模式沿信任谱逐步升级。从 plan（只读）到 bypass（全权）， 信任是挣来的，不是默认授予的。ML 分类器在 auto 模式下学习用户的信任模式。
从第一天起就假设 token 是稀缺资源。五层压缩管线、memoization、lazy loading—— 一切设计都围绕"在有限空间内最大化信息价值"。
风险评估按操作的可逆性加权。读操作（无副作用）自动放行， 写操作（可 Git 回滚）中等审查，删除操作（不可逆）严格管控。
所有状态变更记录为 JSONL 日志，支持完整的时间旅行式恢复。 不依赖数据库，不使用复杂的状态机——文件系统就是最好的数据库。
模型推理、线束执行、人类裁决。三者职责清晰，不可越权。 模型不能绕过权限系统直接执行操作，用户始终保有最终否决权。
源码泄露还揭示了一些通过 feature flags 隐藏但尚未发布的计划特性：
afk-modeAFK 模式——允许 Claude Code 在用户不在时自主运行，适合长时间后台任务。
advisor-tool顾问工具——可能是一种"只建议不执行"的辅助决策模式。
Browser Automation浏览器自动化——让 Claude Code 具备操控浏览器的能力。
KAIROS Daemon名为 KAIROS 的后台守护进程——用于后台索引和持续监控，类似 Chyros 记忆守护进程的进化版。
Claude Code 的架构展现了一个成熟的 AI 编程工具应该如何构建：不是简单地包装一个 LLM API， 而是围绕"安全执行、可靠运行、人机协作"三大目标，构建了一套完整的工程体系。 它的核心哲学可以归结为一句话——模型负责思考，基础设施负责执行，人类保有最终决策权。
从五层子系统分解到七层安全防护，从四级记忆层级到五层上下文压缩，从七种权限模式到 27 种 Hook 事件—— 每一个子系统都体现了"最小化 AI 决策范围、最大化确定性工程保障"的设计理念。 这或许是当前市面上最成熟的 agentic coding 工具架构之一。