拆解 Claude Code：一个把五层架构做到极致的编码 Agent
用课程框架当透镜，拆解 Claude Code 的五层地基、透明度、错误恢复与上下文管理。
为什么拿 Claude Code 当样本
Claude Code 是 Anthropic 推出的命令行编码 Agent——一句话说，它是「一个住在你终端里、能读写代码库、能跑命令、能自主规划多步任务的编程智能体」。
它值得拆，不是因为它最火，而是因为它把我们课程里讲的每一层抽象，都做了一个看得见摸得着的工程对应物。Loop、Tool、Planning、Memory、Multi-Agent 这五层，在很多 Agent 产品里是混在一起的一坨；在 Claude Code 里几乎每一层都能找到独立、显式、可配置的设计。它是一面理想的「框架照妖镜」——你拿任何一个透镜去照它，都能照出清晰的结构。
这篇拆解的玩法是：不复述产品功能列表，而是把课程的框架一个个架上去，看真实产品在这些框架下长什么样。
透镜一：技术地基五层
先用 Module A 的「五层地基」横扫一遍。下表是每一层在 Claude Code 里的具体落地形态：
| 地基层 | Claude Code 的实现 | 关键设计点 |
|---|---|---|
| Loop | gather → act → verify 三阶段动态循环，底层是标准 ReAct | 五种终止条件：success / max_turns / max_budget_usd / during_execution / max_structured_output_retries——终止靠成本上限和异常，而非写死步数 |
| Tool | 13 个核心内置工具（文件/搜索/执行/Web/编排）+ MCP 外接 | 权限精确到命令级（Bash(npm run test *)）；只读工具可并发、写操作串行；ToolSearch 按需加载工具 schema |
| Planning | plan mode：只读探索 → 产出计划 → 人工审批 → 执行 | 把「高风险一步」拆成「低风险两步」，规划与执行解耦 |
| Memory | 双轨：CLAUDE.md（项目/团队级）+ Auto Memory（用户/跨项目级） | 四层级覆盖（Managed > User > Project > Local）+ @import + 目录树向上查找 |
| Multi-Agent | 三层：Subagent（单向摘要回传）/ Agent Teams（双向协作）/ Background（异步） | 不同层解决不同问题：Subagent 治 context 膨胀，Teams 治协作涌现 |
这张表本身就是个洞察：五层不是均匀发力的。Loop 和 Tool 是稳定的地基，Planning（plan mode）是最精巧的那一块，Multi-Agent 里只有 Subagent 稳定、Agent Teams 还标着 experimental。一个成熟产品敢把高级功能标「实验性」，恰恰说明它知道哪些层经得起生产、哪些层还在打磨。
值得单独点一句 Loop 的终止条件。大多数人会下意识用「最多 N 步」来兜底一个 Agent，而 Claude Code 的兜底是成本上限 + 异常类型。这是一种对模型自主判断的制度性信任——它不假设「Agent 会跑飞所以要掐步数」，而是假设「Agent 会自己判断何时收手，我只需要管住钱包和异常」。这个选择决定了它的用户是在 delegate（委派），而不是在 co-pilot（陪驾）。
透镜二：挑三个维度往深里看
地基五层是骨架，接下来用 L3 能力维度和 Harness 子系统当透镜，挑三个最有看点的维度钻进去。
维度 A：透明度（它怎么让你看见它在想什么）
L3 透明度维度问的是：用户能不能理解 Agent 此刻在干什么、为什么。Claude Code 的答案藏在几个不起眼的工程细节里：
- 每个工具调用都带 description。不是「正在执行命令」，而是「丢弃本地改动并对齐远端 main」这种动作级的人话说明。这让旁观者无需读懂命令本身就知道意图。
- plan mode 本身就是透明度装置。它强制 Agent 在动手前把完整计划摊在你面前等审批——这等于把「Agent 的意图」从黑盒里掏出来变成可读文本。
- Hooks 提供多种生命周期事件（PreToolUse / PostToolUse / Stop / PreCompact 等）。你可以在任意节点挂钩子观测甚至拦截，把「Agent 在做什么」变成可编程的可观测流。
透明度在这里不是「多打印几行日志」，而是被拆进了交互设计（plan mode）、工具契约（description）和可观测基础设施（Hooks）三个层面。
维度 B：错误恢复（它撞墙之后怎么办）
L3 错误恢复维度看的是 Agent 撞墙后的自主性。一个经典实例：工具调用返回 python: command not found，Agent 不重复敲同一条命令，而是推断出 macOS 默认没有 python、改用 python3，然后成功。这是「失败 → 诊断 → 调整工具 → 重试 → 验证」的标准恢复闭环，关键在于它调整了策略而非盲目重试。
往上一层看，错误恢复在 Claude Code 里有制度化的兜底：Loop 的 error_during_execution 终止条件保证异常不会被无限吞掉；Subagent 把可能失败的探索性子任务隔离在独立 context 里，即使子任务跑偏也不污染主线。错误恢复不只是「Agent 聪明」，更是架构层面给了它「失败可隔离、异常有出口」的安全网。
维度 C：上下文管理（它的记忆怎么不爆）
这是 Harness「知识子系统」最硬核的部分。Claude Code 的上下文管理是双轨制：
- CLAUDE.md：解决「团队规范怎么传给 Agent」。它进 git、四层级叠加、支持
@import拆分、目录树向上查找——本质是把项目知识编译进每次会话的起点。 - Auto Memory：解决「个人工作流怎么被记住」。存在
~/.claude/下，读取时先吃前 200 行（或 25KB）再按需展开 topic 文件，跨项目持续积累。 - 多层 Compaction Pipeline：当上下文逼近上限，它按「旧工具输出 → 压缩对话 → 保留最近交换 → 重新注入根 CLAUDE.md → 用户可指定焦点」的顺序腾空间。注意最后两步——它在压缩后重新注入 CLAUDE.md，保证再长的会话也不会把项目规范挤出窗口。
再加一个 ToolSearch 的细节：MCP 工具的 schema 不预加载，而是按需发现。这让接入再多 MCP server，启动时的 context 开销也接近不增长——把多工具场景的上下文成本从 O(n) 压到接近 O(1)。上下文工程在这里的核心命题始终如一：窗口是稀缺资源，什么该常驻、什么该按需、什么该压缩，每一类都有专门机制。
关键洞察：最值得偷师的两个设计决策
决策一：plan mode——用「拆步」消化高风险。 Agent 最危险的时刻是「自主执行不可逆操作」。Claude Code 没有用「更准的风险分类器」去硬刚这个问题，而是用一个交互结构绕开它：先只读探索、产出计划、人工审批，再执行。一个高风险步骤被拆成两个低风险步骤。这是把「准确率问题」转化成「流程问题」的典范——因为再准的分类器也有那 1%，而 1% 的误判落在不可逆操作上就是灾难。
决策二：双轨记忆——两种粘性分开养。 CLAUDE.md 管团队知识，Auto Memory 管个人工作流。它没有把二者揉成一个「记忆系统」，而是按「谁拥有这份知识、它该在什么范围生效」清晰切开。结果是项目知识随 git 在团队内扩散，个人知识随用户跨项目沉淀——两条独立的积累曲线。对做 Agent 的人来说，这提示了一个常被忽略的设计问题：记忆的「作用域」和「归属」往往比「记多少」更重要。
对你自己做 Agent 的启发清单
把 Claude Code 当镜子照完，沉淀成一份可直接拿去用的清单：
- Loop 的终止条件想清楚是「步数」还是「预算+异常」。前者把 Agent 当不可信的脚本，后者把它当可委派的同事——这个选择会反向定义你的产品定位（co-pilot vs delegate）。
- 工具权限做到命令级，别只做工具级。
Bash全开还是只放npm run test *，安全边界差一个数量级。 - 高风险不可逆操作，优先用「拆步+审批」而不是「更准的判断」。流程解耦比模型准确率更可靠。
- 记忆按「作用域 × 归属」分轨设计。团队级进 git、用户级跨项目，别揉成一锅。
- 上下文当稀缺资源精算：区分常驻（项目规范）、按需（工具 schema 延迟加载）、压缩（旧输出），并保证压缩后核心规范被重新注入。
- 透明度拆进三层落地：工具调用带人话 description、关键节点可审批、生命周期可挂钩观测——而不是简单堆日志。
- 错误恢复要架构兜底，不只靠模型聪明：把易失败的探索隔离进子上下文，给异常留显式出口。
- 高级功能敢标「实验性」：先把基础能力打磨稳定再推复杂协作，而非一次性端出所有功能。
照着 Claude Code 这面镜子，你会发现做 Agent 的难点很少在「让模型更聪明」，而几乎全在「给模型搭一个让它的聪明能安全落地的结构」——这正是 Harness 与五层地基这两套框架的全部意义。