概述
所有读者：把 Claude Code 当作范例级 agent harness 反向拆解——提取可迁移到自研 agent 的设计原则。
为什么单独一章讲 Claude Code
本站的 Harness Engineering 讲”agent harness 应该怎么构建”，Context Engineering 讲”上下文应该怎么管理”。这些都是产品中立的理论。
这一章不同——这一章只讲一个产品：Claude Code。
为什么值得单列：Claude Code 是 Anthropic 自己造的、也是自己在用的 agent harness。它承载了 Anthropic 关于 harness 和 context engineering 的全部判断落地。研究它，等于同时拿到了两份资料：
- 一个高完成度的工程参考——生产级 CLI + Desktop + Web + IDE 插件，跑了几千万小时
- 一份”他们自己相不相信那些论文”的可观测证据——论文里讲的”渐进披露""上下文衰退""注意力预算”在它的设计里有没有真正被当一回事
所以这一章的定位是：把 Claude Code 作为 case 拆解，然后把拆出来的原则回授到自研 agent 的设计。不是产品使用手册。
Claude Code 的独特之处
相比把”agent 产品化”做得比较表层的同类（Cursor / Windsurf / Devin / Aider），Claude Code 有几个别家没有或者做得浅的决定：
| 决定 | Claude Code 做法 | 为什么值得研究 |
|---|---|---|
| 系统提示词分层 | 静态骨架 + CLAUDE.md 项目级 + ~/.claude/ 用户级 + auto memory + session 级 guidance，分多次注入 | 直接把”prompt 缓存命中”和”个性化”两个目标做成了设计原则，不是事后优化 |
| 上下文压缩 | 自动触发的 compaction，保留语义骨架、丢弃可重新派生的内容 | 把”哪些 token 有长期价值”这件事做成了显式策略 |
| 记忆系统 | 三级（项目 / 用户 / auto memory）+ MEMORY.md 索引常驻 + 单条文件按需加载 | 渐进披露原则的范例应用 |
| 沙箱与权限 | permission modes 作为用户 per-turn 可见的状态机，hooks 作为事件级拦截 | 把”信任边界”做成了产品 surface，不是藏在 config 里 |
| Subagent（Agent tool） | 主 agent 通过 Agent tool 委派子任务，子 agent context 完全独立 | 上下文防火墙——多 agent 的意义不是并行，是隔离 |
| Hooks | pre/post tool、stop、prompt-submit 事件钩子，由 harness 保证执行 | 区分了”prompt 级”和”process 级”两类需求，承认 prompt 不万能 |
这些在后续各篇里逐个展开。
阅读顺序
| # | 主题 | 读完能回答 |
|---|---|---|
| 1 | 本页（Overview） | 为什么研究 Claude Code，读什么 |
| 2 | 系统提示词组装 | 静态骨架、CLAUDE.md、session guidance 怎么拼成最终 prompt，为什么这么拼 |
| 3 | 上下文压缩 | 压缩何时发生、保留什么、跨 session 怎么承接 |
| 4 | 记忆系统 | 6 种记忆类型、MEMORY.md 索引设计、subagent 作为上下文防火墙 |
| 5 | Agent 运行循环 | 一轮到底发生了什么：query async generator、14 步流水线、streaming tool executor、abort 全链路 |
| 6 | 权限系统 | 7 mode × 8 source × 11 reason × 10 hook 事件的信任决策层 |
| 7 | 执行环境 | 3 种 isolation 模式 (none / worktree / remote)、跨平台进程沙箱、CCR 云端架构 |
| 8 | 设计启示 | 抽出的跨主题原则（抽象） |
| 9 | 应用到自研 Agent (AI SDK) | 把原则落到 AI SDK 的 8 个嵌入点 · 3 个 trap · MVP 蓝图（可执行，按钩子切） |
| 10 | 生命周期状态流 | 一次对话里状态怎么在 8 个点之间流动 · 4 个状态桶 · 读写矩阵（按状态切） |
前 7 篇描述 Claude Code 怎么做，第 8 篇抽出抽象原则，第 9 篇把原则落到 AI SDK 代码行（按钩子切），第 10 篇追踪状态跨 8 点的流动（按状态切）——9 和 10 互补，是同一套代码的两个视角。
章节组织：2-4 讲静态组成（prompt、compaction、memory），5 讲动态运行（一轮循环），6-7 讲安全边界（信任 + 物理隔离）；8-10 是理论 → 应用的三重——第 8 讲抽象原则、第 9 讲按钩子切的代码地图、第 10 讲按状态流切的动态走读。
本章不做什么
- 不是 Claude Code 使用手册。装它、配 MCP、写 slash command 这些事官方文档讲得很清楚。链接：docs.claude.com/claude-code
- 不猜内部实现。本章只讨论可观测行为——发给模型的 system prompt 长什么样、工具返回的 error 文本是什么、permission
mode 切换时 UI 表现、
CLAUDE.md加载顺序。具体算法（比如 compaction 的触发阈值、记忆 ranking）除非 Anthropic 公开发表过，否则不做断言。 - 不和 Cursor / Devin 做功能对比。对比表容易写成营销稿。个别地方为了说清”Claude Code 做了什么别家没做的决定”会引用，但不构建完整对比矩阵。
- 不等同于”Anthropic 官方立场”。本章是第三方学习总结。一些设计启示是基于可观测行为的推断，不是 Anthropic 官方文档。
方法论：可观测 vs 推测
写这章时严格区分两种断言：
- 可观测：作为 Claude Code 实例本身能看到的东西——system prompt 里的文本、工具的 schema、
CLAUDE.md加载行为、error message 的措辞、permission mode 的 UI 表现 - 公开文档：docs.claude.com、Anthropic 博客、官方 changelog
- 推测：基于以上两类信息推出的设计意图——会明确标注”推测”或”可能是”
一旦你读到没有标注推测的内容，那它是可观测或公开文档支持的。
适合谁读
- 正在自研 agent 产品，想知道一个成熟的 harness 里哪些决定值得抄
- 已经在用 Claude Code，想知道它为什么这么设计（而不只是”怎么用”）
- 在做上下文工程，想看 Context Engineering 章讲的那些原则有没有一个完整的工程实例
不适合：只是想学 AI 基础、还没开始写 agent 的读者——建议先读 Agent = Model + Harness。
延伸阅读
- Harness Engineering——Anthropic 关于 harness 构建的论点，本章的理论背景
- Context Engineering——注意力预算、三支柱模型，本章多处引用
- docs.claude.com/claude-code——Claude Code 官方文档（使用向）