深度解剖ClaudeCode核心架构：50万行代码背后的代理循环设计哲学

三年前第一次接触ClaudeCode时，我以为它只是个包装精美的CLI工具。深入源码后才发现，这套1884个TypeScript文件、超过50万行代码的系统，本质上只有一个核心循环。

最小可行代理：一条永恒循环

query.ts中的while-true循环就是全部秘密。用户输入→messages数组→ClaudeAPI→响应→stop_reason判断→工具执行或返回文本。这个模式简单到令人发指，却支撑起整个生产级系统。

关键洞察在于：核心越简单，外围越复杂。所有50万行代码都在为这个简单循环添加保护带。

12层渐进式安全带的构建逻辑

第一层是工具调度。buildTool工厂为每个工具定义完整生命周期：validateInput→checkPermissions→call→renderToolResultMessage。添加新工具只需注册处理程序，无需修改核心循环。

第二层引入计划机制。EnterPlanModeTool要求代理先列步骤再执行，官方数据显示这使任务完成率翻倍。TodoWriteTool则将大目标拆解为可管理的小任务。

第三层实现子代理隔离。forkSubagent.ts创建独立进程，全新messages数组避免污染主对话上下文。worktree模式更进一步，在隔离的git工作目录中运行。

上下文管理的三层压缩策略

当token预算逼近阈值时，autoCompact触发API总结旧消息。snipCompact移除僵尸消息和过时标记。contextCollapse则重构整个上下文结构。

这种分层设计确保长会话不会崩溃，同时保留关键信息完整性。

类型安全的设计模式矩阵

品牌类型（BrandedTypes）防止SystemPrompt与普通字符串混淆。辨识联合（DiscriminatedUnions）确保Message处理的类型安全。延迟Schema（lazySchema）优化Zod验证性能。

这些模式共同构成编译时错误捕捉网络，将运行时风险降至最低。

多代理协作的集群架构

TeamCreateTool创建领导代理+队友的工作模式。共享任务看板和消息收件箱，隔离messages数组和文件缓存。SendMessageTool驱动请求-响应协商流程。

coordinatorMode实现自主认领机制，队友自己扫描并认领可用任务，无需中央调度。

可复用的核心设计原则

AsyncGenerator全链路流式传输贯穿整个架构。功能开关+编译时DCE实现生产包精简。环形缓冲区管理错误日志的有限内存。即发即弃写入模式保持顺序的非阻塞持久化。

这套架构的终极启示：简单核心+渐进式扩展+类型安全+无处不在的持久化，构成了生产级AIAgent的基石。