深度解析：Claude Code 源码架构与 Harness Engineering 实践

📌 一句话摘要

本文通过对 Claude Code 逆向源码的深度分析，揭示了其基于 Harness Engineering 的 Agent 架构设计，重点探讨了状态持久化、工具调度及系统提示词控制面等核心机制。

📝 详细摘要

文章以 Harness Engineering 为理论框架，对 Claude Code（v2.1.88）的逆向源码进行了系统性剖析。核心观点认为，Agent 的能力不仅取决于模型单体，更取决于其外围的「Harness」系统。源码揭示了 Claude Code 维护的四条核心不变量：轨迹拓扑完整性、缓存前缀稳定性、能力面分层暴露以及连续性外化。文章详细拆解了 QueryEngine 作为会话宿主的职责、query.ts 作为恢复图而非线性循环的设计逻辑，以及系统提示词（System Prompt）如何作为「运行时法律」通过结构化分区和缓存边界来治理模型行为。此外，还分析了其复杂的工具执行流水线、并发调度策略以及利用专用侧向查询（Side Query）处理窄任务的工程实践。

💡 主要观点

1. Agent 系统设计的核心在于维护四条运行时不变量。 包括轨迹拓扑不可破（工具调用必须匹配结果）、缓存前缀不可漂（保护 Prompt Cache）、能力面分层暴露（按需激活工具）以及连续性外化（依赖外部工件而非仅靠消息历史）。
2. 系统提示词是第一控制面，而非简单的文案层。 System Prompt 被建模为宿主协议的一部分，通过显式的静态前缀与动态边界划分，在定义行为法则的同时最大化缓存复用效率。
3. 主循环 query.ts 本质上是一个复杂的恢复图。 它不是简单的「采样-执行」循环，而是通过显式的状态转换处理 Token 溢出、权限拒绝和轨迹中断，目标是不断修正并维持一条合法的执行轨迹。
4. 采用专用 Prompt Worker 处理窄任务以保持主循环纯净。 架构中引入了侧向查询机制，将记忆选择、模式分类、UI 摘要等特定任务分配给专用模型调用，避免主模型在长上下文中过载。

💬 文章金句

• 值得迁移的不是某个函数，而是它在替哪条不变量付账。
• 系统提示词在这里不是文案层，而是 runtime law。哪个 prompt 赢，直接决定了后续能力面、任务边界、消息协议、输出语义。
• 不要把所有智能都塞给主对话模型。把 recall、policy judgment、UI summary、memory maintenance 这些窄任务分配给专用 prompt worker，主 loop 才能保持干净。
• 真正值得迁移到未来 agent 设计里的，主要是 principle，以及少量已经被证明有效的 workaround。

📊 文章信息

阅读完整文章