书籍大纲：驾驭工程 — 从 Claude Code 源码到 AI 编码最佳实践

背景

基于对 Claude Code v2.1.88 的 1,902 个 TypeScript 源文件的逆向工程，我们提取了一整套驾驭工程（Harness Engineering）模式、上下文管理策略和 AI 编码最佳实践。本书将这些发现组织成一本面向 AI Agent 构建者的实战指南。

目标读者：希望理解顶级 AI 编码产品底层运作机制的 AI 工程师和 Agent 开发者。

---

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

第1章：AI 编码 Agent 的完整技术栈

• 技术栈概览：TypeScript + React Ink + Bun
• 入口点分析（main.tsx）：并行预取、延迟导入、Feature Flag
• 三层架构：应用层（TS）→ 运行时（Bun/Zig）→ 外部依赖（npm/JSC）
• 为什么 "on distribution" 很重要：模型编写自己的工具
• 通过 bun:bundle 的 feature() 实现构建时死代码消除
• 89 个 Feature Flag 全景：从 ABLATION_BASELINE 到 WORKFLOW_SCRIPTS

第2章：工具系统 — 40+ 个工具作为模型的双手

• Tool.ts 接口契约：name、description、prompt、inputSchema、call、checkPermissions、validateInput
• buildTool() 工厂函数和失败关闭默认值（isConcurrencySafe: false、isReadOnly: false）
• 工具注册管线（tools.ts）：基于 Feature Flag 的条件加载
• 三阶段渲染：renderToolUseMessage → renderToolUseProgressMessage → renderToolResultMessage
• 工具结果大小预算：单工具 maxResultSizeChars、单消息 MAX_TOOL_RESULTS_PER_MESSAGE_CHARS = 200K

第3章：Agent Loop — 从用户输入到模型响应的完整生命周期

• queryLoop() 状态机：State 类型的 7 个可变字段（messages、toolUseContext、autoCompactTracking、maxOutputTokensRecoveryCount...）
• 循环转换类型（Continue）：工具调用继续、max_output_tokens 恢复（最多 3 次）、token budget 继续、reactive compact
• 单次迭代的完整流程：context collapse → autocompact → API 调用 → 流式响应 → 工具执行 → stop hooks → 继续判定
• 消息标准化管线：normalizeMessagesForAPI → ensureToolResultPairing → stripAdvisorBlocks → stripExcessMediaItems
• prependUserContext vs appendSystemContext：上下文注入的位置和时序
• 中止/重试/降级：FallbackTriggeredError、对话中途切换模型、attemptWithFallback 循环

第4章：工具执行编排 — 权限、并发、流式与中断

• toolOrchestration.ts 的 runTools()：partitionToolCalls 将工具调用分为并发安全批次和串行批次
• isConcurrencySafe 判定逻辑：只读工具可并发，写入工具必须串行
• toolExecution.ts 单工具生命周期：validateInput → checkPermissions → autoClassifier → call → postToolUse hooks
• StreamingToolExecutor：流式工具执行器，边生成边处理
• 权限决策链：工具自身 checkPermissions → 通用权限规则 → YOLO 分类器 → 用户提示
• 工具结果处理：applyToolResultBudget → persistLargeToolResult → preview 生成
• Stop hooks：工具执行后的中断点，允许用户或系统在工具间插入控制

---

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

第5章：系统提示词架构

• 分段式组合：systemPromptSection() 的记忆化和缓存感知
• 静态与动态边界：SYSTEM_PROMPT_DYNAMIC_BOUNDARY 标记
• 缓存优化契约：边界前 = scope: 'global'（跨组织可缓存），边界后 = 每会话
• splitSysPromptPrefix() 的三条代码路径（MCP 存在时、全局缓存+边界、默认）
• DANGEROUS_uncachedSystemPromptSection() 及其使用时机（MCP 连接/断开）

第6章：通过提示词引导行为

• 极简主义指令："三行重复代码优于过早抽象"、"不要添加超出要求的功能"
• 渐进式升级："切换策略前先诊断原因，不要盲目重试，也不要一次失败就放弃"
• 可逆性意识："三思而后行" — 高风险操作确认框架
• 工具偏好引导："使用 Grep（而非 grep 或 rg）" — 通过工具描述重定向
• Agent 委托指引：fork vs. 全新 agent、"不要偷看 fork 输出"、"不要竞争"
• 输出效率：内部员工的散文式沟通风格 vs. 外部用户的精简要点
• 数值锚定："工具调用间的文字保持在 ≤25 词" — 1.2% 输出 token 削减

第7章：模型特定调优与 A/B 测试

• @[MODEL LAUNCH] 注解模式：标记模型敏感代码以便发布时扫描
• Capybara v8 的缓解措施：过度注释、虚假声明（29-30% 虚假声明率）、主动性、彻底性
• USER_TYPE === 'ant' 门控作为 A/B 测试暂存："在外部用户上验证后解除门控"
• 卧底模式（Undercover）：在系统提示词中压制模型名称、ID 和战略信息
• GrowthBook 集成：tengu_* Feature Flag、_CACHED_MAY_BE_STALE vs _CACHED_WITH_REFRESH
• 知识截止日期映射：按模型注入日期字符串到环境上下文

第8章：工具提示词作为微型驾驭器

• BashTool 提示词：Git 安全协议（绝不跳过 hooks、绝不 amend、优先指定文件 git add）、沙箱配置以 JSON 内联、工具偏好区域、后台任务说明
• FileEditTool 提示词："编辑前必须先读取"通过工具报错强制执行、最小唯一 old_string 提示（仅内部）、replace_all 用于重命名
• FileReadTool 提示词：默认 2000 行、offset/limit 渐进式读取、PDF 页码范围
• GrepTool 提示词："始终使用 Grep，绝不在 Bash 中调用 grep"、ripgrep 语法说明、多行匹配可选
• AgentTool 提示词：动态 agent 列表（内联 vs. 附件以保持缓存稳定性）、fork 指引、隔离模式
• SkillTool 提示词：预算约束的技能列表（上下文窗口的 1%）、三级截断级联、内置技能优先

---

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

第9章：自动压缩 — 上下文何时以及如何被压缩

• 阈值计算：contextWindow - MAX_OUTPUT_TOKENS_FOR_SUMMARY(20K) - AUTOCOMPACT_BUFFER(13K)
• 环境变量覆盖：CLAUDE_CODE_AUTO_COMPACT_WINDOW、CLAUDE_AUTOCOMPACT_PCT_OVERRIDE
• 熔断器：MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3（数据：1,279 个会话出现 50+ 次连续失败，每天浪费约 250K 次 API 调用）
• 压缩提示词剖析：9 段模板、<analysis> 草稿块（压缩后移除）、时间顺序强调
• 三种提示词变体：BASE（全对话）、PARTIAL（尾部）、PARTIAL_UP_TO（前缀保留）
• Prompt-too-long 重试：丢弃最旧的 API 轮次组、回退丢弃 20%、PTL_RETRY_MARKER

第10章：压缩后的文件状态保留

• 压缩前快照：cacheToObject(context.readFileState) 然后清空
• 压缩后恢复：POST_COMPACT_MAX_FILES_TO_RESTORE = 5、单文件上限 5K token、总预算 50K token
• 技能重注入：单技能 5K token 上限、总计 25K 预算、"技能文件顶部的指令通常是关键部分"
• 不重注入的内容：sentSkillNames（节省 4K token，模型仍持有 SkillTool schema）
• Delta 附件：延迟工具、agent 列表、MCP 指令在压缩后重新宣告

第11章：微压缩 — 精准上下文修剪

• 基于时间的微压缩：间隔阈值触发旧工具结果清理，保留最近 N 个
• 缓存微压缩（API 原生）：cache_edits 块删除工具结果但不使缓存前缀失效
• consumePendingCacheEdits() / getPinnedCacheEdits()：编辑生命周期管理
• 可压缩工具集：FileRead、Bash、Grep、Glob、WebSearch、WebFetch、FileEdit、FileWrite
• notifyCacheDeletion() / notifyCompaction()：防止缓存中断误报

第12章：Token 预算策略

• 工具结果持久化：DEFAULT_MAX_RESULT_SIZE_CHARS = 50K → 磁盘 + 预览消息
• 单消息预算：MAX_TOOL_RESULTS_PER_MESSAGE_CHARS = 200K（防止 N 个并行工具洪泛）
• Token 计数：规范方式（来自 API usage）vs. 粗略估算（4 字节/token，JSON 为 2）
• 并行工具调用 token 计数：向后遍历以捕获所有交错的 tool_results
• 图片/文档估算：保守 2000 token（真实公式：width*height/750）
• 文件类型感知估算：JSON 按 2 字节/token 防止对密集格式的低估

---

第四篇：提示词缓存 — 隐藏的成本优化器

第13章：缓存架构与断点设计

• Anthropic API 提示词缓存：前缀匹配、cache_control: \{ type: 'ephemeral' \} 标记
• 三级缓存范围：global（跨组织）、org（单组织）、null（不缓存）
• 缓存 TTL 层级：默认 5 分钟、符合条件的用户 1 小时
• should1hCacheTTL()：锁存的会话稳定资格检查
• Beta Header 锁存：afkModeHeaderLatched、fastModeHeaderLatched、cacheEditingHeaderLatched — "一旦发送就持续发送，避免浪费约 50-70K token 的缓存"

第14章：缓存中断检测系统

• 两阶段检测：recordPromptState()（调用前）→ checkResponseForCacheBreak()（调用后）
• PreviousState 追踪：15+ 字段，包括 systemHash、toolsHash、cacheControlHash、perToolHashes、betas、effortValue
• 中断解释引擎：识别哪个字段变化，生成人类可读原因
• TTL 过期检测：时间间隔 > 5分钟 或 > 1小时 → "可能是 TTL 过期"
• 服务端归因："当所有客户端标志为 false 且间隔在 TTL 内时，约 90% 的中断是服务端原因"
• Diff 文件生成：createPatch() 生成前后提示词状态对比

第15章：缓存优化模式

• 日期记忆化：getSessionStartDate() 只捕获一次，避免午夜缓存失效
• 月度粒度：工具提示词中的 getLocalMonthYear() 最小化缓存失效
• Agent 列表改为附件：从内联提示词（占全球 cache_creation token 的 10.2%）移至 system-reminder 消息
• 技能列表预算：上下文窗口的 1%，级联截断防止无限增长
• $TMPDIR 占位符：标准化每用户临时路径以实现跨用户缓存共享
• 条件性段落省略：功能禁用时 → 段落从提示词中消失（而非"功能 X 已禁用"）
• 工具 Schema 缓存：getToolSchemaCache() 每会话计算一次，防止 GrowthBook Flag 切换导致序列化 schema 变动

---

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

第16章：权限系统

• 权限模式：default → acceptEdits → plan → bypassPermissions → auto → dontAsk
• 权限规则匹配：精确匹配、前缀匹配（npm:*）、通配符（git add *）
• 验证 → 权限 → 分类 管线：失败关闭的执行顺序
• 危险模式检测：isDangerousBashPermission() 阻止对解释器的工具级别放行
• UNC 路径 NTLM 泄漏防护：对 \\ 路径跳过 fs.existsSync()

第17章：YOLO 分类器

• 二次 Claude API 调用用于自动批准决策
• 安全白名单：只读工具完全跳过分类器
• 分类器输出：\{ thinking, shouldBlock, reason \}，结构化输出 Schema
• 拒绝追踪：连续 3 次或总计 20 次拒绝 → 回退到用户提示
• 模板系统：外部用户与 Anthropic 内部用户使用不同提示词
• 调试基础设施：CLAUDE_CODE_DUMP_AUTO_MODE=1 导出分类器请求/响应

第18章：Hooks — 用户自定义拦截点

• Hook 事件类型：PreToolUse、PostToolUse、PermissionRequest、SessionStart/End、FileChanged 等
• 执行模型：异步生成器、超时处理（默认 10 分钟、SessionEnd 为 1.5 秒）
• 信任门控：交互模式下所有 Hook 都需要信任对话框确认
• 退出码语义：0 = 允许、2 = 阻塞错误 → 入队为任务通知
• 配置快照追踪：检测并响应 settings.json 变更

第19章：CLAUDE.md — 用户指令作为覆盖层

• 加载顺序：托管 → 用户 → 项目 → 本地（优先级递增）
• @include 指令：传递性文件包含，防止循环引用
• 前置元数据 paths: 范围限定：将指令限制在匹配的文件模式
• HTML 注释剥离：`` 中的作者注释在注入前移除
• 注入提示词："这些指令覆盖任何默认行为，你必须严格遵守"
• 大小预算：建议每文件 40K 字符

---

第六篇：高级子系统

第20章：Agent 集群与多 Agent 编排

• AgentTool：通过独立的 AsyncLocalStorage 上下文生成子 agent
• Fork 模式：后台执行、共享提示词缓存、"不要偷看输出"
• 协调者模式（COORDINATOR_MODE）：多 Worker 编排，任务分配与验证
• 队友 Agent：进程内集群协作、TeammateAgentContext、TeamCreateTool/TeamDeleteTool
• 验证 Agent：PASS/FAIL/PARTIAL 判定附带证据（仅内部 A/B 测试）
• Agent 间通信：SendMessageTool、UDS_INBOX Unix Domain Socket 消息传递

第21章：Effort、Fast Mode 与 Thinking

• Effort 级别：low/medium/high/max、优先级链（环境变量 → 应用状态 → 模型默认 → 兜底）
• Fast Mode：Opus 4.6 加速输出、组织状态缓存、冷却管理（限速/过载）
• Thinking 配置：adaptive vs. enabled（预算）vs. disabled
• Ultrathink：关键词触发检测、模型支持门控
• 按模型默认值：Opus + Pro → medium effort，Max/Team Premium 可配置

第22章：技能系统 — 从内置到用户自定义

• 技能的本质：可调用的提示词模板，通过 SkillTool 注入对话
• 内置技能清单：skills/bundled/ 下的 batch、loop、scheduleRemoteAgents 等
• 用户自定义技能：loadSkillsDir.ts 的发现和加载机制、.claude/skills/ 目录结构
• MCP 技能桥接：mcpSkillBuilders.ts 将 MCP server 能力转化为可调用技能
• 技能搜索系统：EXPERIMENTAL_SKILL_SEARCH、本地索引构建、关键词匹配与评分
• 技能生命周期：RUN_SKILL_GENERATOR（生成）、SKILL_IMPROVEMENT（改进）、skillChangeDetector（变更检测）
• 预算约束的技能列表：上下文窗口的 1%、三级截断级联、内置技能优先保留描述
• 技能与 Hook 的交互：技能作为 Hook 触发源、技能内的 slash command 执行

第23章：未发布功能管线 — 89 个 Feature Flag 背后的路线图

• KAIROS 助手模式：后台自主 agent、<tick> 唤醒机制、autoDream 记忆整理、push notification
• PROACTIVE 模式：自主工作、terminal focus 感知、sleep/wake 循环
• VOICE_MODE：流式语音转文字、push-to-talk 键绑定
• WEB_BROWSER_TOOL：Bun WebView 集成（非 Playwright）
• BRIDGE_MODE + DAEMON：远程控制服务器、CCR 镜像
• COORDINATOR_MODE 的完整编排：worker 分配、验证、汇报
• 从 feature flag 看产品路线图：哪些接近发布、哪些仍在实验

---

第七篇：AI Agent 构建者的经验教训

第24章：跨会话记忆 — 从遗忘到持久学习

• Memdir 架构：MEMORY.md 索引 + 主题文件，200 行 / 25KB 截断策略
• Extract Memories：fork agent 在查询结束时自动提取，权限隔离
• Session Memory：滚动会话摘要（10K 初始化 / 5K 更新间隔 / 3+ 工具调用）
• Transcript Persistence：JSONL 增量追加，会话恢复重建
• Agent Memory：user/project/local 三作用域，VCS 快照同步
• Auto-Dream：四层门控（Master/Time/Session/Lock），PID 锁，四阶段整合提示词
• 模式：多层记忆架构、后台 fork agent 提取、文件 mtime 即状态、预算约束注入、互补频率设计

第25章：驾驭工程原则

1. 提示词即控制面：通过系统提示词段落引导行为，而非代码限制
2. 缓存感知设计是刚需：每次提示词变更都有以 cache_creation token 计量的成本
3. 失败关闭，显式开放：工具默认为不安全/不可并发，必须显式声明安全
4. A/B 测试一切：ant-only 门控作为暂存，GrowthBook 用于运行时实验
5. 先观察再修复：promptCacheBreakDetection.ts 作为仪表盘驱动调试的典范
6. 锁存以求稳定：一旦进入某状态就不再摇摆（beta header、缓存 TTL 资格）

第26章：上下文管理作为核心能力

1. 为一切设定预算：工具结果、文件读取、技能列表、agent 描述都有 token 预算
2. 保留重要内容：压缩后最多 5 个最近文件、50K 总预算
3. 告知而非隐藏：截断通过输出元数据报告，模型可分页
4. 熔断失控循环：连续 3 次失败 → 停止尝试
5. 保守估算：JSON 按 2 字节/token、图片按 2K token

第27章：生产级 AI 编码模式

1. 编辑前先读取：通过工具报错强制执行，而非仅靠提示词指令
2. 渐进式自主：从手动到全自动的权限模式，带分类器回退
3. 防御性 Git：绝不跳过 hooks、绝不 amend（创建新提交）、绝不 force-push
4. 结构化验证：运行测试 → 检查输出 → 如实报告（不伪造绿色结果）
5. 范围匹配响应：对 X 的授权不延伸到 Y
6. 工具级提示词优于通用指令：每个工具携带自己的行为驾驭器

第28章：Claude Code 的不足之处（以及你能修复什么）

1. 缓存脆弱性：分散的注入点制造缓存中断风险 — 应集中构建
2. 压缩信息丢失：9 段摘要模板无法保留所有推理链
3. Grep 不是 AST：文本搜索遗漏动态导入、re-export、字符串引用
4. 静默截断：50K 工具结果阈值 → 写入磁盘 + 预览，但模型可能不会重新读取
5. Feature Flag 复杂性：89 个 flag、锁存状态和构建时门控产生涌现行为
6. Agent Loop 无法自省：模型不知道自己处于恢复循环的第几次重试

第29章：可观测性工程 — 从 logEvent 到生产级遥测

• 5 层遥测架构：事件入口 → 路由分发 → PII 安全 → 投递韧性 → 远程控制
• 队列-附着模式：logEvent() 零依赖设计，事件先入队后异步排空
• PII 安全：never 类型标记强制显式验证，_PROTO_* 双路路由
• 1P Exporter（807 行）：OTel BatchLogRecordProcessor + 自定义韧性层
  • 批次分片 + 短路逻辑 + 二次退避 + 401 降级 + 磁盘持久化
• Datadog：策展式允许列表（30+ 事件）、用户分桶、15 秒批刷新
• API 三事件模型：query/success/error + TTFT/TTLT 性能指标
• 调试三通道：debug（可能含 PII）/ diagLogs（PII-free）/ errorLogSink（ant-only）
• 分布式追踪：OTel 三级 span（interaction/llm/tool）+ Perfetto 可视化
• 优雅关闭：级联超时（终端→清理→hooks→analytics→forceExit），5 秒失败保险
• 成本追踪：USD/token/行变更，会话间持久化

---

附录

附录 A：关键文件索引

文件	职责
main.tsx	CLI 入口点，并行预取
Tool.ts	工具接口契约
tools.ts	工具注册，Feature Flag 条件加载
query.ts	Agent Loop 主循环，queryLoop 状态机
services/tools/toolOrchestration.ts	工具执行编排，并发分区
services/tools/toolExecution.ts	单工具执行生命周期
services/tools/StreamingToolExecutor.ts	流式工具执行器
constants/prompts.ts	系统提示词构建
constants/systemPromptSections.ts	段落注册表，带缓存控制
services/api/claude.ts	API 调用构建，缓存断点放置
services/api/promptCacheBreakDetection.ts	缓存中断检测系统
services/compact/compact.ts	压缩编排
services/compact/autoCompact.ts	自动压缩阈值与触发器
services/compact/microCompact.ts	精准上下文修剪
utils/api.ts	splitSysPromptPrefix()、工具 Schema 构建
utils/toolResultStorage.ts	大结果持久化
utils/claudemd.ts	CLAUDE.md 加载与注入
utils/permissions/yoloClassifier.ts	自动模式分类器
skills/bundled/	内置技能目录
tools/SkillTool/	技能工具实现
skills/loadSkillsDir.ts	用户自定义技能发现
skills/mcpSkillBuilders.ts	MCP 到技能桥接

附录 B：环境变量参考

变量	效果
CLAUDE_CODE_AUTO_COMPACT_WINDOW	覆盖上下文窗口大小
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE	以百分比覆盖自动压缩阈值
CLAUDE_CODE_EFFORT_LEVEL	覆盖 effort 级别（low/medium/high/max/auto/unset）
CLAUDE_CODE_DISABLE_FAST_MODE	禁用 fast mode
CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS	覆盖文件读取 token 限制
CLAUDE_CODE_SIMPLE	最小系统提示词模式
CLAUDE_CODE_DUMP_AUTO_MODE	导出 YOLO 分类器请求/响应
DISABLE_AUTO_COMPACT	禁用自动压缩
CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY	覆盖工具并发上限（默认 10）
CLAUDE_CODE_BLOCKING_LIMIT_OVERRIDE	覆盖上下文硬限制

附录 C：术语表

术语	定义
驾驭工程（Harness Engineering）	通过提示词、工具和配置（而非代码逻辑）引导 AI 模型行为的实践
Agent Loop	AI agent 的核心执行循环：接收输入 → 调用模型 → 执行工具 → 判断是否继续
提示词缓存（Prompt Cache）	Anthropic API 特性，缓存消息前缀以减少重复 token 处理
压缩（Compaction）	总结对话历史以释放上下文窗口空间
微压缩（Microcompact）	精准移除特定工具结果，而非完整压缩
锁存（Latch）	一旦进入即保持稳定的会话级状态，防止缓存振荡
Feature Flag（tengu_*）	通过 GrowthBook 运行时配置的实验门控
DCE（死代码消除）	Bun 的 feature() 实现编译时移除门控代码
技能（Skill）	可调用的提示词模板，通过 SkillTool 注入对话上下文
并发分区（Partition）	将工具调用分为可并行和必须串行的批次

附录 D：89 个 Feature Flag 完整清单

（按字母顺序列出所有 feature flag 及其功能分类：基础设施/用户功能/实验/遥测）