ClaudeCode中学习到的12个可复用的AgenticHarness设计模式

公众号名称：无处不在的技术

作者名称：爱海贼的无处不在

发布时间：2026-05-05 18:24

持续内容输出，点击蓝字关注我吧

前言

来看一段AI大模型对它的介绍

在 2026 年 4 月，那场突如其来的 Claude Code 源码泄露事件，像一束刺眼的光，照进了原本封闭而神秘的 AI 工程世界。

第一次，我们不再只是透过产品的外壳去猜测，不再通过零碎的接口文档拼凑轮廓，而是真正意义上，看见了一个生产级 AI 编码助手的“内脏”——它如何思考、如何组织、如何在混乱中维持秩序。

那一刻，技术圈几乎集体沉默了一瞬，然后迅速沸腾。

有人在拆解架构，有人在复现流程，有人在争论设计优劣。GitHub、X、论坛、微信群……所有地方都在讨论同一件事：“原来它是这样工作的。” 但慢慢地，很多人开始意识到——如果我们只是停留在“代码长什么样”，那其实什么都没得到。

真正有价值的，从来不是那些具体的实现细节，而是隐藏在代码背后的东西：

那些没有被写在 README 里的判断，那些没有被文档强调的取舍，那些跨越具体技术栈、依然成立的设计思路。

代码会过时，框架会迭代，模型会被替换。

但有些东西，一旦被验证有效，就会像地基一样，反复出现在不同系统之中。

这也是为什么，在所有热闹的源码分析之外，很多人更在意的是另一个问题：

如果把这些代码全部删掉，只留下“思想”，还剩下什么？

Kubernetes Patterns和 Prompt Patterns的作者 Bilgin lbryam最近从源码里整理了 12 个可以复用的Harness设计模式，他没有试图复刻整个系统，也没有沉迷于细枝末节的实现。而是从这份源码中，一点一点地抽离出那些可以跨项目、跨模型、甚至跨时代复用的东西。他把这些模式归纳为四个维度：

记忆与上下文、工作流与编排、工具与权限、自动化。

这四个词，看起来平平无奇。但如果你真的写过复杂的 AI 系统，你会知道：

几乎所有的混乱、崩溃、失控，最后都逃不过这四个问题。

也正因为如此，这篇文章并不是一次“源码解读”。

而更像是一场从混乱中提炼秩序的过程。

本文分享一下整理。

正文

首先我们通过海贼王来简单理解下Harness。

从海贼王角度看下什么是Harness?

从海贼王角度看下为什么需要Harness?

模式列表如下：

一、记忆与上下文（5 个）

持久化指令文件模式（Persistent Instruction File Pattern）

作用域上下文组装模式（Scoped Context Assembly Pattern）

分层记忆模式（Tiered Memory Pattern）

记忆整合模式（Dream Consolidation Pattern）

渐进式上下文压缩模式（Progressive Context Compaction Pattern）

二、工作流与编排（3 个）

探索-规划-行动循环模式（Explore-Plan-Act Loop Pattern）

上下文隔离子智能体模式（Context-Isolated Subagents Pattern）

分支-合并并行模式（Fork-Join Parallelism Pattern）

三、工具与权限（3 个）

渐进式工具扩展模式（Progressive Tool Expansion Pattern）

命令风险分类模式（Command Risk Classification Pattern）

单用途工具设计模式（Single-Purpose Tool Design Pattern）

四、自动化（1 个）

确定性生命周期钩子模式（Deterministic Lifecycle Hooks Pattern）

接下来具体分享一下：

第一类：记忆与上下文

这五个模式，本质上描述的是一条逐渐“进化”的路径。

最初，Agent 只是拿到一份固定规则开始工作；接着，人们开始限制这些规则的生效范围；再往后，记忆被拆分成不同层级；然后引入后台整理机制；最后，在上下文即将耗尽时，对对话内容进行分级压缩。

从“无记忆”到“有结构的记忆系统”，这是一个从粗放到精细的过程。

1. 持久化指令文件模式（Persistent Instruction File Pattern）

如果没有一个长期存在的指令来源，每次会话对 Agent 来说都像第一次接触项目。

同样的规范、流程、约束，需要反复解释；甚至在多轮对话之后，依然可能重复早期的错误。

这个模式的核心很简单：把这些约定写进一个项目级文件，并在每次会话启动时自动加载。
例如构建方式、测试流程、架构约束、命名规则等，都集中在这里统一定义。

关键点在于——这份文件属于代码仓库，而不是依赖人为重复输入。

适用场景：需要在多个会话里反复处理同一个代码库。

权衡点：有维护成本。这个文件需要跟着项目一起更新，一旦过时，反而会误导 Agent，还不如没有。

2. 作用域上下文组装模式（Scoped Context Assembly Pattern）

在小型项目中，一份统一指令文件通常已经足够。但当项目规模扩大后，这种方式会迅速失效。

要么内容不断膨胀，变得难以维护；要么过于抽象，对具体目录失去指导意义。

这个模式的解决思路是：把规则拆散，并绑定到不同层级的作用域中。
例如组织级、用户级、项目根目录、父目录以及子目录。

Agent 会根据当前工作位置，动态组合并加载这些规则。
既保证整体一致性，又允许局部差异存在。

此外，通过模块化导入，可以避免规则重复定义。

适用场景：Monorepo、多语言项目，或者不同目录有不同规范的代码库。

权衡点：可读性会变差。规则分散在多个文件里后，很难一眼看清 Agent 实际加载了哪些内容，不同作用域之间也可能出现冲突。

3. 分层记忆模式（Tiered Memory Pattern）

当所有信息都用同一种方式存储时，结果往往是“什么都记不清”。

如果把全部历史都塞进上下文，不仅消耗大量 token，还容易触碰窗口限制，反而让关键信息被淹没。

因此，这个模式将记忆拆成不同层级：

精简索引：始终保留在上下文中（通常控制在较小规模）
相关内容：根据当前任务动态加载
完整历史：保存在外部存储，需要时再检索

本质上，是在“可访问性”和“成本”之间做分层权衡。

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

权衡点：实现会更复杂。需要想清楚信息该放哪一层，什么时候上升或下沉，以及怎么保证索引和实际数据是同步的。

4. 记忆整合模式（Dream Consolidation Pattern）

即便采用分层结构，随着时间推移，记忆仍然会逐渐失序。

重复信息堆积、旧数据与新数据冲突、索引持续膨胀——这些问题几乎不可避免。

这个模式的思路是引入后台整理机制，在系统空闲时对记忆进行处理：
去重、清理过时内容、重组结构，让整体保持可用状态。

可以把它理解为一类“认知层面的垃圾回收”。

类似源码中的 autoDream，本质上就是在执行这样的操作。

适用场景：Agent 会长期运行、持续积累记忆，而且不方便靠人工去维护。

权衡点：整理本身也要消耗 token，而且不一定完全准确。如果清理太激进，可能会把有用的信息一起删掉。

5. 渐进式上下文压缩模式（Progressive Context Compaction Pattern）

当对话持续增长时，上下文窗口迟早会成为瓶颈。

要么早期信息被挤出，要么任务被迫中断——两种情况都会影响结果质量。

这个模式的解决方式是对信息进行分层压缩：

最新内容尽量完整保留
中期内容进行摘要化处理
更早的信息进一步压缩，甚至折叠为极简表示

换句话说，信息越久远，保留的细节越少。

适用场景：对话轮次比较多（比如 20～30 轮以上）的任务。

权衡点：压缩一定是有损的。信息在一轮轮总结中会丢失，如果后面又需要这些细节，Agent 可能会「编」而不是承认不知道。

工作流与编排

这一组模式，可以用一个词来概括：解耦。

当任务变复杂时，如果“查资料、做决策、改代码、执行工具”全部混在一个上下文里，系统很快就会失控。
信息开始相互干扰，判断质量下降，错误也会越来越隐蔽。

这些模式的核心，就是把不同阶段拆开，让每一步只处理它该处理的事情。

6. 探索-规划-行动循环模式（Explore-Plan-Act Loop Pattern）

如果一开始就让 Agent 直接动手修改代码，问题几乎是必然的。

理解不完整、修改位置错误、遗漏依赖关系，甚至直接绕开已有实现逻辑——这些都很常见。

这个模式把流程拆成三个阶段，并且逐步放开权限：

探索（Explore）

只读代码、收集信息、理解结构
规划（Plan）

整理方案，与用户确认思路
执行（Act）

在明确路径后再进行修改

它解决的不是“能力问题”，而是“顺序问题”。

本质上，是把“先理解，再决策，最后执行”这件事强制固化下来。

适用场景：不熟悉的代码库，或者涉及多个文件的复杂修改。

权衡点：会慢一点。多了探索和规划这两步，小任务会显得有点「流程过重」。

7. 上下文隔离子智能体模式（Context-Isolated Subagents Pattern）

随着对话变长，所有信息都会堆积在同一个上下文中：
调研资料、讨论记录、代码修改、执行日志……全部混在一起。

当真正开始执行关键操作时，这些无关信息反而成为噪声。

这个模式的做法是：把不同阶段交给不同的子 Agent 处理，并为它们分配独立上下文和权限。

调研 Agent：只负责读取和分析
规划 Agent：只负责设计方案
执行 Agent：拥有完整操作权限

每个子 Agent 只看到自己需要的信息，从源头上减少干扰。

适用场景：长会话、多阶段流程，或者不同阶段对上下文要求差异很大的任务。

权衡点：需要额外协调。主 Agent 要决定每一步传什么信息，传少了会丢细节，传多了又回到上下文污染的问题。

8. 分支-合并并行模式（Fork-Join Parallelism Pattern）

有些任务本质上是可以并行的，但如果系统只能串行执行，效率就会被限制住。

例如跨多个文件的修改，本身互不影响，却只能一个接一个完成。

这个模式的思路是：拆分任务，并行处理，再统一合并。

每个子任务由独立 Agent 在隔离环境中完成（例如独立代码副本），互不干扰。
完成后，再将结果汇总回主分支。

它解决的不是“能不能做”，而是“能不能同时做”。

适用场景：可以拆成多个互不依赖子任务的场景。

权衡点：合并会更复杂。如果不同分支改到了同一部分代码，冲突可能比顺序处理更难解决。

工具与权限

如果说前两类解决的是：

Agent 知道什么（记忆）
Agent 如何做事（流程）

那么这一组关注的，是另一个更现实的问题：

Agent 到底被允许做什么

从实践来看，工具设计和权限控制的细致程度，会直接决定系统的稳定性上限。

9. 渐进式工具扩展模式（Progressive Tool Expansion Pattern）

直觉上，把所有工具一次性开放似乎更“强大”，但现实往往相反。

工具越多，选择成本越高，误用的概率也越大。

这个模式的做法是：从最小能力集开始，按需扩展。

初始只提供基础工具（如读写文件、搜索），
当任务需要时，再逐步开放更复杂的能力。

这样可以让 Agent 始终在“刚好够用”的范围内行动。

适用场景：工具很多，但大多数任务其实只用到一小部分。

权衡点：需要额外判断什么时候该开新工具。如果开得太晚，Agent 可能已经走了弯路，浪费了一些轮次。

10. 命令风险分类模式（Command Risk Classification Pattern）

如果允许 Agent 自由执行系统命令，风险会迅速失控；
但如果每一步都要求人工确认，又会让人疲劳甚至麻木。

这个模式引入了一层中间机制：对命令进行风险分级。

低风险操作：自动执行
高风险操作：提示确认或直接阻断

通常通过解析命令内容（操作类型、参数、影响范围等）来判断风险等级。

本质上，是在“效率”和“安全”之间做动态平衡。

适用场景：Agent 能执行 shell 命令，或者会操作外部系统。

权衡点：规则不可能覆盖所有情况，需要不断调整；有时候会误判，要么放过风险操作，要么拦住本来安全的命令。

11. 单用途工具设计模式（Single-Purpose Tool Design Pattern）

如果所有操作都依赖通用命令（如 shell），问题会逐渐显现：

表达不直观、难以审计、权限难以控制，对模型来说也更容易出错。

这个模式的思路是：把常见操作拆成明确、单一职责的工具。

例如：

读取文件
修改文件
搜索内容
匹配路径

每个工具都有清晰输入和边界。

这样不仅提高可理解性，也让权限控制变得更精细。

适用场景：需要频繁做文件操作或搜索的 Agent。

权衡点：灵活性会受限。专用工具不可能覆盖所有情况，所以还是需要保留通用 shell 作为兜底。

自动化

这一类看似只有一个模式，但实际上贯穿了前面所有部分。

因为无论是记忆、流程还是工具，都会遇到同一个问题：

有些步骤必须执行，但不能依赖模型“记得去做”。

12. 确定性生命周期钩子模式（Deterministic Lifecycle Hooks Pattern）

在实际系统中，总有一些操作是“不能出错，也不能遗漏”的：

修改后自动格式化代码
执行前进行校验
切换目录时刷新配置

如果这些逻辑仅写在提示词中，基本无法保证执行。

模型可能忘记、跳过，或者在复杂上下文中理解偏差。

这个模式的做法是：把这些关键动作绑定到系统生命周期节点上自动触发。

例如：

工具调用前后
会话初始化时
工作环境变化时

这些操作完全由系统控制，而不是依赖模型行为。

本质上，是把“必须正确的事情”，从模型层移交到系统层。

适用场景：存在必须严格执行、不能遗漏的步骤

权衡点：出了问题不太好排查，因为这些逻辑是在对话之外跑的

正文

总结

Harness这些模式不是空谈的理论，而是从生产级代码中提炼出来的架构智慧。

内存怎么分层、上下文怎么压缩、权限怎么控制、哪些流程必须自动执行——这些本质上都是架构层面的决策。模型会变，工具也会换，但这些东西不会很快过时。

这次 Claude Code 的泄露，让我们第一次比较完整地看到，这些模式在一个真实、大规模使用的 agent 里是怎么落地的。这样的窗口可能不会一直存在，但这些经验会留下来。

如果你正在做 agent 应用，值得认真研究这些模式。它们不是「锦上添花」的优化，而是决定系统能不能长期稳定运行的基础。

参考资料：https://generativeprogrammer.com/p/12-agentic-harness-patterns-from

**喜欢本文的，可以关注、收藏、点赞、转发、分享到朋友圈哦。
**

- END -

喜欢的可以加入我的免费知识星球与我一起学习相关开发技术：觉醒的新世界程序员，随时与我沟通，交流技术与想法。

喜欢的也可以关注我的公众号：无处不在的技术，与我一起学习成长、共同进步，在技术的道路上越走越远。

喜欢就点个 **在看****呗 👇
**

cover_image

原创爱海贼的无处不在无处不在的技术