驾驭工程：从 Claude Code 源码到 AI 编码最佳实践

📚 项目背景

• 仓库地址：https://github.com/ZhangHanDong/harness-engineering-from-cc-to-ai-coding
• 在线阅读：https://zhanghandong.github.io/harness-engineering-from-cc-to-ai-coding/
• 作者：张汉东
• 形态：这是一本开源的技术在线书籍（GitBook / mdBook 格式）。
• 来源：它是基于 claude-code-sourcemap（官方 Claude Code 源码还原版）逆向分析后，结合作者自身的 Agent 工程经验，使用 AI 辅助生成的深度架构解析指南。

⚡ 核心定位与价值

如果你想学习如何开发一个工业级的 AI Coding Agent，那么：

1. claude-code-sourcemap 是实物引擎的原始图纸（极其复杂，缺乏注释）。
2. claude-code-from-scratch 是概念验证模型（去除了工业级细节的单缸积木）。
3. 《驾驭工程》(本书) 则是设计与维修手册，它提炼了官方源码背后真正的工程决策。

📖 全书架构与核心洞察

全书分为七大篇章，完全按照工业级 Agent 的核心子系统进行拆解：

第一篇：架构 — Claude Code 如何运作

• 核心洞察：Agent Loop 不是 REPL。
• 详细拆解了 queryLoop() 状态机。指出 Claude Code 的大循环是一个“自修改状态机”，迭代之间有多达 10 个可变字段。它会根据 Token 预算、阻塞拦截、工具调用结果动态调整下一步动作，有 7 种 Continue 状态和 10 种终止原因。

第二篇：提示工程 — 系统提示词作为控制面

• 核心洞察：Prompt 是微型驾驭器。
• 解析了 Claude Code 是如何利用系统提示词（System Prompt）和工具提示词（Tool Prompt）来精确控制大模型行为的，包括针对特定模型（如 Opus vs Sonnet）的微调与 A/B 测试。

第三篇：上下文管理 — 200K Token 竞技场

• 核心洞察：Agent 能力的上限是由 Context Management 决定的。
• 揭秘了源码中最复杂的上下文防撑爆管线，从 Snip（片段裁切）到 Microcompact（微压缩），再到最终的 Autocompact。展示了当对话即将触及 200K 限制时，系统如何提取关键信息并“坍缩”早期对话。

第四篇：提示词缓存 (Prompt Cache)

• 核心洞察：隐藏的成本优化器。
• 分析了如何通过架构层面的断点设计，最大化利用 Anthropic 的 Prompt Caching 机制，从而在多轮对话中大幅节省 API 成本并降低延迟。

第五篇：安全与权限 — 纵深防御

• 核心洞察：从 YOLO 分类器到命令沙箱。
• 剖析了代码中对危险命令（如 rm -rf）的拦截机制。系统并非简单依赖关键字，而是内建了 YOLO（You Only Live Once）分类器，配合外部的 Stop Hooks 进行深度防护。

第六篇：高级子系统

• 探讨了 Agent 集群（Coordinator 模式），分析了 Claude Code 是如何在一场对话中孵化子 Agent（Sub-agent）来并行处理任务的。同时介绍了 Effort Level 和 Thinking Mode 的工程实现。

第七篇：经验教训

• 总结了“驾驭工程”的原则，探讨了 Claude Code 目前的不足以及未来 AI Agent 架构的演进方向。

🎯 总结

这本“马书”是非常少见的从商业级闭源产品源码反向分析出架构设计的优质中文资料。它将凌乱的 50 万行 TypeScript 源码重新组织为了可供人类学习的知识体系，非常适合作为研发私有化 AI Coding Agent 时的案头参考书。