【学习笔记】深度拆解 Claude Code：12 个可复用的 Agentic Harness 设计模式

模型可以换工具也会变但这些设计很可能会一直存在。Kubernetes Patterns[1] 和 Prompt Patterns[2] 的作者Bilgin lbryam从源码里整理了 12 个可以复用的设计模式分成四类记忆与上下文、工作流与编排、工具与权限、自动化。一、记忆与上下文这五个模式其实是一条逐步演进的路径一开始只是给 Agent 一份固定的规则文件然后按目录去限制这些规则的作用范围再把记忆做成分层结构接着在后台做清理最后在上下文快满的时候对对话本身做压缩。1. 持久化指令文件模式Persistent Instruction File Pattern没有持久化指令文件时每个 Agent 会话都像从零开始。同样的约定、命令和边界需要一遍遍重复甚至第几次对话还会犯和第一次一样的错误。这个模式的做法其实很直接放一个项目级的配置文件每次会话自动加载。里面写清楚构建命令、测试方式、架构规则、命名约定这些内容。文件跟着代码仓库走而不是靠人每次复制粘贴。适用场景需要在多个会话里反复处理同一个代码库。权衡点有维护成本。这个文件需要跟着项目一起更新一旦过时反而会误导 Agent还不如没有。2. 作用域上下文组装模式Scoped Context Assembly Pattern一个指令文件在小项目里够用但项目一大就容易出问题要么越写越长最后没人看要么写得太泛对具体目录又没什么用。这个模式的思路是把指令拆到不同作用域里组织级、用户级、项目根目录、父目录、子目录。Agent 会根据当前所在的位置动态加载对应的规则。这样既能保持全局一致又能允许局部有差异。另外通过导入的方式可以把大的指令集拆开管理避免重复。适用场景Monorepo、多语言项目或者不同目录有不同规范的代码库。权衡点可读性会变差。规则分散在多个文件里后很难一眼看清 Agent 实际加载了哪些内容不同作用域之间也可能出现冲突。3. 分层记忆模式Tiered Memory Pattern如果一个 Agent 什么都用同一种方式记住最后往往什么都记不好。把所有记忆都塞进上下文每次会话都会浪费 token还容易撞上窗口限制重要信息反而被淹没。这个模式的做法是把记忆分层一个精简的索引始终放在上下文里比如控制在几百行以内和当前任务相关的内容按需加载完整的历史记录则留在磁盘上需要时再去查。适用场景需要跨多次会话保留偏好、决策或状态的 Agent。权衡点实现会更复杂。需要想清楚信息该放哪一层什么时候上升或下沉以及怎么保证索引和实际数据是同步的。4. 记忆整合模式Dream Consolidation Pattern即使做了分层记忆用久了还是会「变乱」重复内容越来越多旧信息和新信息打架索引也会慢慢膨胀。这个模式的思路是加一个后台整理机制在空闲时定期做清理去重、删旧、重组结构让记忆保持干净、可用。可以理解为给 Agent 做一次「垃圾回收」。像泄露代码里提到的autoDream就是在做类似的事情合并重复、处理冲突、控制索引规模。适用场景Agent 会长期运行、持续积累记忆而且不方便靠人工去维护。权衡点整理本身也要消耗 token而且不一定完全准确。如果清理太激进可能会把有用的信息一起删掉。5. 渐进式上下文压缩模式Progressive Context Compaction Pattern对话一长很快就会碰到上下文窗口的上限。要么早期内容被挤掉要么任务直接做不下去这两种情况都挺难受。这个模式的做法是「分层压缩」新的对话尽量保留细节稍旧的内容做轻量总结再往前的就逐步压缩甚至折叠成很短的摘要。可以理解为越久远的信息保留得越粗。像源码里提到的几层压缩本质上也是这个思路只是做得更细。适用场景对话轮次比较多比如 2030 轮以上的任务。权衡点压缩一定是有损的。信息在一轮轮总结中会丢失如果后面又需要这些细节Agent 可能会「编」而不是承认不知道。二、工作流与编排这一组模式的核心其实就是一个词分离。把读取和写入拆开把「查资料」和「改代码」的上下文拆开把顺序执行和并行执行也拆开。这样做的好处是随着任务变复杂系统不会越来越乱。大多数 Agent 的默认做法是把这些事情混在一起刚开始可能没问题但任务一多质量就很容易下降。6. 探索-规划-行动循环模式Explore-Plan-Act Loop Pattern如果一上来就让 Agent 改代码很容易出问题理解不完整改错文件漏掉依赖或者直接忽略现有的实现方式。这个模式的做法是把流程拆成三步而且权限逐步放开• 先探索只读代码、查信息、摸清结构• 再规划和用户对齐思路• 最后再动手改代码本质上就是先搞清楚再决定怎么做最后再执行。适用场景不熟悉的代码库或者涉及多个文件的复杂修改。权衡点会慢一点。多了探索和规划这两步小任务会显得有点「流程过重」。7. 上下文隔离子智能体模式Context-Isolated Subagents Pattern会话一长所有东西都会堆在同一个上下文里调研内容、规划讨论、代码修改、日志输出全混在一起。等真正开始改代码时很多无关信息已经在干扰判断了。这个模式的做法是把任务拆给不同的子 Agent每个都有自己的上下文和权限• 做调研的只负责看和分析不能改代码• 做规划的只负责设计方案• 真正执行的才有完整工具权限每个子 Agent 只接触自己需要的信息避免被「流噪声」影响。适用场景长会话、多阶段流程或者不同阶段对上下文要求差异很大的任务。权衡点需要额外协调。主 Agent 要决定每一步传什么信息传少了会丢细节传多了又回到上下文污染的问题。8. 分支-合并并行模式Fork-Join Parallelism Pattern有些任务其实可以拆开做但如果 Agent 一次只能处理一件事最后还是会变成一条一条顺序执行。比如跨很多文件的改动本来互不影响却要排队完成。这个模式的思路是把任务拆成多个分支并行处理每个子 Agent 在独立的代码副本里工作比如用git worktree互不干扰。等都完成后再把结果合并回来。适用场景可以拆成多个互不依赖子任务的场景。权衡点合并会更复杂。如果不同分支改到了同一部分代码冲突可能比顺序处理更难解决。三、工具与权限如果说前面的记忆模式是在解决「Agent 知道什么」工作流是在解决「它怎么做事」那这一部分关注的就是「它能做什么」。从泄露的代码来看在工具设计和权限控制上已经细到很具体的粒度远比现在大多数 Agent 框架要更严格。9. 渐进式工具扩展模式Progressive Tool Expansion Pattern如果一开始就把所有工具都开放给 Agent反而会变得更难用工具一多选择成本变高也更容易选错。这个模式的做法是先给一小部分常用工具够用就行其他工具按需再打开。比如读写文件、搜索这些作为默认能力复杂一点的工具等用到再加载。适用场景工具很多但大多数任务其实只用到一小部分。权衡点需要额外判断什么时候该开新工具。如果开得太晚Agent 可能已经走了弯路浪费了一些轮次。10. 命令风险分类模式Command Risk Classification Pattern如果让 Agent 随便执行 shell 命令风险很高但如果每一步都让用户确认很快就会点到麻木。这个模式的做法是在执行前做一层「风险判断」低风险的命令自动放行高风险的才需要人工确认或直接拦截。实现上通常是对命令做解析比如看做什么操作、带了哪些参数、影响范围多大再结合规则去判断风险等级。适用场景Agent 能执行 shell 命令或者会操作外部系统。权衡点规则不可能覆盖所有情况需要不断调整有时候会误判要么放过风险操作要么拦住本来安全的命令。11. 单用途工具设计模式Single-Purpose Tool Design Pattern如果所有操作都走通用 shell比如cat、sed、grep问题会慢慢出现命令不直观、不好审查也更难做权限控制。对模型来说也更容易用错。这个模式的做法是把常见操作拆成专门的工具比如读文件、改文件、搜索、匹配路径各自都有明确的输入和边界。这样不仅更好理解也更容易限制权限。适用场景需要频繁做文件操作或搜索的 Agent。权衡点灵活性会受限。专用工具不可能覆盖所有情况所以还是需要保留通用 shell 作为兜底。三、自动化最后这一类可以单独拿出来说因为它其实贯穿前面的所有部分。不管是记忆、工作流还是工具本质上都有一个共同问题有些步骤是每次都必须执行的但不能指望模型每次都记得。12. 确定性生命周期钩子模式Deterministic Lifecycle Hooks Pattern有些事情是必须每次都做的比如改完代码跑一遍格式化、执行前做校验、切换目录时重新加载配置。但这些步骤如果只是写在提示词里基本不可靠。模型会忘、会跳过甚至在复杂上下文里「理解偏了」。这个模式的做法是把这些动作挂到 Agent 生命周期的关键节点上自动执行完全不依赖提示词。比如工具调用前后、会话开始、工作目录变化时系统都会触发对应的钩子。简单来说凡是「不能出错、不能漏」的事情都不该交给模型记而应该交给系统兜底。适用场景存在必须严格执行、不能遗漏的步骤权衡点出了问题不太好排查因为这些逻辑是在对话之外跑的四、结语Harness这些模式不是空谈的理论而是从生产级代码中提炼出来的架构智慧。内存怎么分层、上下文怎么压缩、权限怎么控制、哪些流程必须自动执行——这些本质上都是架构层面的决策。模型会变工具也会换但这些东西不会很快过时。这次 Claude Code 的泄露让我们第一次比较完整地看到这些模式在一个真实、大规模使用的 agent 里是怎么落地的。这样的窗口可能不会一直存在但这些经验会留下来。如果你正在做 agent 应用值得认真研究这些模式。它们不是「锦上添花」的优化而是决定系统能不能长期稳定运行的基础。参考文献[1]Kubernetes Patterns:https://k8spatterns.com/[2]Prompt Patterns:https://promptpatterns.dev/[3]12 Agentic Harness Patterns from Claude Code:https://generativeprogrammer.com/p/12-agentic-harness-patterns-from【4】https://mp.weixin.qq.com/s/eUbRoyKxOjiAPuXZi8DPsQ