深度分析 Claude Code 源码 – 沉淀出12种可复利的顶级 Harness 设计模式

Claude Code 公开仓库、官方文档和 Anthropic 工程文章放在一起看，会得到一个很清楚的结论：

它真正有价值的，不只是“模型会写代码”，而是 Anthropic 已经把一个生产级 AI 编码助手需要的很多关键机制做成了工程系统。

这也是为什么最近大家盯着 Claude Code，不只是想看它调用了哪些模型、用了哪些工具，而是想看一个能长期跑、能在真实代码库里工作、还能相对可控的 agent，到底是怎么被搭出来的。

对我来说，最值得研究的部分不是某个具体实现细节，而是它背后那些更稳定的模式。模型以后会换，工具接口也会变，但 Agent 的很多底层问题不会变：上下文怎么装配、记忆怎么保存、工作流怎么拆、权限怎么收、哪些动作必须自动执行。

如果把这些经验抽象出来，大致可以整理成 12 个可复用的设计模式，并且可以分成四组：

1. 记忆与上下文
2. 工作流与编排
3. 工具与权限
4. 自动化

一、记忆与上下文

这一组模式解决的是同一个问题：Agent 到底该知道什么，以及这些信息该以什么方式存在。

如果上下文没有设计，Agent 的状态会很快滑向两个极端：要么什么都记不住，每次重新开始；要么把所有东西都塞进会话，最后上下文被噪音撑爆。

1. 持久化指令文件模式

最基础的一层，是把那些“每次都要重复告诉 Agent 的东西”从对话里拿出来，做成持久存在的说明文件。

在 Claude Code 的体系里，CLAUDE.md 就承担了这类角色。项目的构建方式、测试命令、架构禁忌、代码规范、常用工作流，都可以直接写进仓库，让每次会话启动时自动加载。

这个模式的核心价值不复杂：不要让团队知识只活在一次次 prompt 里，而要让它变成随代码一起演化的资产。

适用场景：同一个代码库会被多次、多会话地反复处理。

权衡点：这类文件一旦不更新，就会从“帮忙”变成“误导”，所以它不是写一次就结束，而是要跟代码一起维护。

2. 作用域上下文组装模式

当项目变复杂之后，只靠一个根目录说明文件往往不够。

Monorepo、混合语言仓库、不同业务线共存的项目里，经常会出现这样的情况：全局有全局规则，某个目录又有自己独特的命令、依赖和禁区。如果所有内容都写到一个文件里，很快就会失控。

更可行的做法，是按作用域去组装上下文。组织级规则、用户级偏好、项目根目录规则、某个子目录的局部规范，可以分开存放，再由系统根据当前工作位置动态装配。这样既保留全局一致性，又能给局部留出空间。

适用场景：Monorepo、多技术栈项目、按目录分工明显的代码库。

权衡点：规则一旦分散，排查冲突会变难。人不容易一眼看清“当前这一刻 Agent 实际加载了哪些规则”。

3. 分层记忆模式

Agent 的记忆如果只有一种存法，最后通常会失效。

把所有历史都直接塞进上下文，看起来最省事，但代价很明显：token 成本高，窗口容易被打满，而且真正重要的信息反而可能被埋掉。Claude Code 相关文档里，一个很重要的思路就是分层：有些内容始终存在，有些内容按需加载，有些则留在外部状态里，需要时再取回。

换句话说，不同信息应该放在不同层级。稳定规则放静态文件，当前任务状态放会话或局部上下文，完整历史和长尾细节放磁盘或外部结构里。这样 Agent 才不会既记不住重点，又背着一堆没必要的细节前进。

适用场景：需要跨多次会话保留偏好、决策、项目状态的 Agent。

权衡点：实现上会复杂很多。你必须明确区分什么应该常驻、什么应该按需加载、什么应该下沉存储。

4. 记忆整合模式

即便做了分层，记忆也不会自动一直干净。

只要 Agent 长期运行，记忆系统就会慢慢变脏：重复记录越来越多，旧规则和新规则互相打架，索引越来越胖，真正有用的信息越来越难找。Anthropic 在相关文章里提出的思路，是给这套记忆加后台整理过程，而不是任由它无限膨胀。

这个模式本质上像是给 Agent 做一次定期清扫：去重、合并、删旧、处理冲突，把记忆维持在一个可继续使用的状态。

适用场景：长期运行、持续积累经验、又不可能靠人工频繁手动清理的 Agent。

权衡点：整理本身也要消耗资源，而且不可能百分之百正确。过于激进的清理，反而可能删掉未来还需要的线索。

5. 渐进式上下文压缩模式

上下文窗口再大，也不是无限的。

长任务做着做着，总会遇到一个现实问题：早期对话越来越远，如果全保留，窗口很快超限；如果直接丢掉，又可能在后续阶段缺关键细节。Claude Code 这类系统的思路，不是简单截断，而是把历史信息按时间和重要度分级压缩。

新近内容尽量保留细节，稍旧内容做轻摘要，更早的部分压成高度概括的结构化结果。信息越老，保留得越粗。这不是完美方案，但它比“要么全留、要么全删”更接近生产系统需要的平衡。

适用场景：长会话、多轮交互、单个任务可能持续 20 轮以上的工作。

权衡点：压缩天然有损。一旦后续又需要很早之前的细节，Agent 可能只能依赖摘要，甚至产生错误推断。

二、工作流与编排

如果说前一组解决的是“Agent 该知道什么”，这一组解决的就是“Agent 该怎么做事”。

很多 Agent 一开始看起来都能跑，但任务一复杂就会越来越乱，原因通常不是模型变差了，而是阅读、分析、规划、修改、验证这些动作全部混在了一个线程里。

这一组模式的核心，其实就是分离。

6. 探索-规划-行动循环模式

直接让 Agent 看到需求就动手改代码，往往是最容易翻车的路径。

不熟悉代码库时，它可能还没搞清架构边界就开始修改；牵涉多个模块时，它可能先改了一个最显眼的文件，却没注意到真实依赖在别处。Claude Code 的官方工作流和 Anthropic 的工程文章，都在强调一个更稳的顺序：先探索，再规划，最后执行。

这个循环的意义不只是“更谨慎”，而是让权限和动作按阶段展开。前面先读、先查、先理解；中间对齐方案；最后再真正进入写入和执行阶段。

适用场景：陌生代码库、多文件改动、需要先摸清现状的复杂任务。

权衡点：比直接动手更慢。对于特别小的任务，这套流程可能显得有点重。

7. 上下文隔离子智能体模式

长任务里最常见的问题之一，不是模型不会做，而是上下文太脏。

调研记录、日志片段、架构讨论、修改尝试、失败输出，全塞在同一个线程里，最后真正写代码的时候，主线程已经背着太多无关材料。Claude Code 的 subagent 设计，解决的就是这个问题：把某些旁支任务拆给独立上下文窗口处理，主线程只拿回摘要。

这样一来，调研子 agent 可以专心查资料，规划子 agent 可以专心整理方案，真正执行的 agent 才保留最必要的信息去改代码。

适用场景：多阶段任务、长会话、不同阶段对上下文要求明显不同的工作。

权衡点：协调成本会上升。主线程必须决定该传什么、该省什么，传得不好就会变成新的信息丢失点。

8. 分支-合并并行模式

有些任务天然可以拆开并行做，只是很多 Agent 系统没有把这件事真正系统化。

比如一个大改动涉及多个相互独立的模块，理论上完全可以拆成几条支线同时推进。但如果所有事情都在一个线程里按顺序做，效率会很低，彼此之间还容易互相打断。

更成熟的做法，是把任务 fork 成多个独立分支，让不同子 agent 在各自隔离的副本里工作，最后再 join 回来。这和软件工程里的 branch/merge 思路非常接近，本质上是在把并行能力引入 agent 工作流。

适用场景：可拆成多个低耦合子任务的大型修改。

权衡点：合并难度会明显上升。一旦多个分支碰到同一块代码，冲突处理会比顺序执行更麻烦。

三、工具与权限

前两组解决了“知道什么”和“怎么做”，这一组关注的是另一件更现实的问题：Agent 到底能做什么，以及它被允许做到什么程度。

Claude Code 最值得研究的，不只是工具多，而是它对工具边界和权限边界的处理相当细。

9. 渐进式工具扩展模式

工具不是越多越好。

如果一开始就把所有能力全部开放给 Agent，模型需要面对的选择空间会急剧膨胀，不仅更容易选错工具，也更容易在无关能力上绕弯路。更好的策略，是先给一小组高频、低风险、足够完成大多数任务的核心工具，其他能力按需再扩展。

这背后的逻辑很像软件里的最小依赖集：先让系统在最小可用集合上运行，只有确实需要时，才引入新的工具面。

适用场景：工具很多，但多数任务只会用到其中少数能力的系统。

权衡点：需要很好地判断“何时该扩、扩到哪里”。扩太晚会影响效率，扩太早又会把系统重新拖回复杂状态。

10. 命令风险分类模式

只要 Agent 能执行 shell 或外部操作，权限问题就一定会出现。

如果完全放开，风险太高；如果每一个动作都让用户确认，体验又会迅速恶化。Claude Code 在权限模式、sandbox、受保护路径和风险判断上的设计，背后体现的是同一个模式：先对动作分类，再决定哪些自动放行、哪些需要确认、哪些直接拦截。

重点不在于某一个规则，而在于这是一条连续控制曲线，不是简单的“允许 / 不允许”二选一。

适用场景：Agent 可以执行命令、修改文件、访问外部系统的环境。

权衡点：分类规则永远不可能完美，系统需要持续修正误判，否则要么放过危险操作，要么拦住本来安全的动作。

11. 单用途工具设计模式

如果所有操作都通过通用 shell 完成，灵活性当然很强，但问题也会跟着放大。

一方面，命令形式对模型不够直观，容易用错；另一方面，通用命令很难做细粒度审查和权限控制。Claude Code 这类系统明显更偏向专用工具思路：读文件、改文件、搜索路径、查看差异，各自都是边界清晰的单用途工具，shell 只作为兜底。

这种模式的关键价值，是把高频动作结构化。对于模型来说，更容易正确调用；对于系统来说，更容易审计和限权。

适用场景：文件操作、代码搜索、差异查看等高频、可标准化的任务。

权衡点：专用工具不可能覆盖所有场景，所以系统通常仍然需要保留一个通用执行面作为 fallback。

四、自动化

最后这一组只有一个模式，但它其实贯穿前面所有部分。

因为很多工程上必须执行的动作，根本不应该交给模型“记得去做”。

12. 确定性生命周期钩子模式

有些动作属于那种一旦漏掉就会出问题，但它们又常常很机械：执行某类命令前先做检查、修改文件后自动格式化、切换目录后重新加载配置、工具调用前后做审计。

如果这些步骤只是写在 prompt 里，它们迟早会被忘、被跳过，或者在复杂上下文里被误解。Claude Code hooks 的价值，就在于把这些动作挂到系统生命周期节点上，让它们自动触发，而不是靠模型自觉。

本质上，这是把“应该每次都发生的行为”从意图层下放到执行层。凡是不能遗漏的事情，都应该交给系统，而不是寄希望于模型稳定记忆。

适用场景：存在必须严格执行、不能遗漏、不能依赖主观判断的步骤。

权衡点：自动逻辑一旦变多，排障会更难，因为它们往往发生在对话之外，需要额外的日志和可观测性支持。

五、结语：真正值得学的不是某个功能，而是 Harness 思维

如果把这 12 个模式放在一起看，你会发现它们讨论的其实不是“某个酷炫功能”，而是生产级 Agent 最根本的四件事：

1. 它该知道什么
2. 它该如何推进任务
3. 它被允许做什么
4. 哪些动作不能依赖模型记忆

这些问题，本质上都属于 harness，而不是 prompt 小技巧。

Claude Code 真正给行业的启发，也正在这里。它不是在教大家怎么把一个模型调得更像工程师，而是在展示：如果你想让 Agent 长期、稳定、可控地工作，就必须把记忆、上下文、工作流、工具、权限和自动化当成同等重要的系统设计问题。

还有一个我很看重、但没有单独放进这 12 个编号里的补充点，是长任务里的结构化交接。Anthropic 在 long-running harness 的文章里反复强调，真正成熟的 agent，不该依赖一个超长会话硬撑到底，而应该依赖外部状态来完成接班。进度文件、测试状态、提交记录、阻塞点说明，都是这个思路的一部分。

模型会迭代，工具也会换代，但这些模式不会很快过时。

如果你正在做 agent 应用，值得认真研究的不是“Claude Code 有没有某个隐藏技巧”，而是这些模式如何组合成一个能落地、能演进、能长期运行的系统。这些东西不是锦上添花，它们往往才是 Agent 从 demo 走向生产的分水岭。

如果你对 AI 知识、AI 落地工作方法感兴趣，欢迎关注。后续我会持续分享行业趋势、实战经验与可直接落地的方法，内容力求务实、易懂、可复用。

每天更新一点，帮你把复杂的 AI 世界看明白、跟上节奏、不掉队。