Claude Code源码泄露:我扒出了Anthropic没说过的Agent架构设计

当Anthropic在2024年末开源Claude Code的核心代码时，开发者社区炸开了锅。这不是一次普通的功能发布——而是一次罕见的、直视AI Agent内部运作机制的机会。源码揭示了三个核心模块如何精密协作：状态持久化、工具调度、系统提示词控制。这三个模块共同构成了Claude Code的Agent骨架，也是理解现代AI编程助手架构的关键。

Claude Code的状态持久化不是简单的文件读写，而是一套精心设计的有状态重放机制，它让Agent能够跨越中断、恢复记忆、保持上下文连贯性。

会话状态的构成

Claude Code将每个编程会话的状态抽象为以下核心字段：

session_state = {
    "history": [...],        # 对话历史（含工具调用记录）
    "context": {...},        # 当前工作区上下文（文件树、git状态）
    "checkpoint": int,       # 检查点序号
    "tools": [...],          # 可用工具列表
    "env": {...}             # 环境变量与工作目录
}

源码中有一个关键设计决策：每次工具调用后立即生成检查点，而不是等对话结束后再保存。这意味着即便Claude Code被强制终止（Ctrl+C、系统崩溃、断电），重启后也能恢复到中断前的准确状态，不会丢失最后一个工具调用的结果。这个设计对于长时间运行的开发任务尤为重要——比如重构一个包含50个文件的复杂模块，中途被打断后不需要从头开始。

重放缓冲区的实现

状态持久化的核心在于replay_buffer模块。该模块维护一个环形缓冲区（默认大小128），保存最近128次工具调用的输入输出。当模型需要”回顾”之前的操作时，不是重新执行这些工具，而是直接从缓冲区读取结果。

这个设计的精妙之处在于：它用内存换取了速度。重新执行git log或ls这类命令虽然不慢，但在长对话中累积起来会显著拖慢响应时间。如果一个会话包含200次工具调用，每次回顾都重新执行，时间成本不可接受。重放缓冲区确保了O(1)的回顾速度——无论缓冲区多大，查询最近N次操作的时间复杂度始终是常数级别。

# 伪代码还原 replay_buffer 核心逻辑
class ReplayBuffer:
    def __init__(self, capacity=128):
        self.buffer = deque(maxlen=capacity)
        self.capacity = capacity
    
    def append(self, tool_call):
        """工具调用后立即写入检查点"""
        checkpoint = {
            "id": tool_call.id,
            "tool": tool_call.name,
            "input": tool_call.input,
            "output": tool_call.output,  # 直接缓存结果，不重新执行
            "timestamp": time.time()
        }
        self.buffer.append(checkpoint)
    
    def get_context(self, window=10):
        """返回最近N次工具调用的上下文"""
        return self.buffer[-window:]
    
    def search(self, tool_name, **filters):
        """支持按工具名和参数过滤历史"""
        return [c for c in self.buffer if c["tool"] == tool_name and ...]

持久化与恢复的时序

当Claude Code启动时，加载顺序严格按照以下顺序执行，任何一步失败都会阻止启动并报告详细错误：

1. 1. 读取全局配置（.claude-code/settings.json）——加载用户偏好设置
2. 2. 重建重放缓冲区（从.claude-code/history.jsonl逐行解析）——恢复历史状态
3. 3. 恢复工作目录状态（执行git status、pwd、ls等）——验证工作区一致性
4. 4. 注入系统提示词（从.claude-code/instructions加载）——准备任务上下文

源码中有一行注释揭示了设计哲学：”The session is the product, not just a convenience“（会话本身就是产品，而非仅仅是便利功能）。这解释了为什么Claude Code愿意为状态持久化投入如此多的工程复杂度——因为会话的连续性直接决定了Agent能否处理长任务。

崩溃恢复的完整性保证

Claude Code的状态持久化还包含一个写前日志（Write-Ahead Log）机制，用于处理写入过程中断的场景。每次修改状态前，先将变更记录追加到WAL，状态文件更新完成后再擦除WAL记录。如果更新过程中断，重启时会检测到WAL残留，自动执行回放恢复。这个机制确保了即使在写入.claude-code/history.jsonl时发生断电，状态文件也不会损坏。

工具调度控制面的实现细节

工具调度是Claude Code最复杂的模块之一，也是最能体现”Agent思维”的部分。它负责将LLM的输出转化为可执行的动作，并管理这些动作的执行生命周期。

工具注册表

Claude Code的工具通过一个中心化注册表管理，所有工具都遵循统一的接口规范：

总之，Claude Code的架构展示了状态持久化、工具调度和系统提示词三大工程选择。