---
source_url: "https://mp.weixin.qq.com/s/vdHloWWaKC7O72sK0SSOig"
title: "一文读懂 12 个 Agent 工程设计底层逻辑"
source: "数据派THU / 数据STUDIO / 云朵君"
ingested: 2026-06-15
sha256: "b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f7a8b9c0d1e2f3a4"
type: raw
tags: [agent-design-patterns, harness, claude-code, memory, context, workflow, permission, hooks, bilgin-ibryam, yunduojun]
---

一文读懂 12 个 Agent 工程设计底层逻辑

本文约5500字，建议阅读11分钟
本文介绍 Claude Code 12 个 Agent 模式，剖析架构痛点、用法及落地边界。

Claude Code 源码泄露后，技术圈都在研究它的实现细节。但 Bilgin lbryam 做了件更值钱的事——把实现提炼成 12 个可复用的设计模式，分成四类：记忆与上下文、工作流与编排、工具与权限、自动化。

核心隐喻：模式 1-11 是"脚手架"——帮 Agent 更好地工作。模式 12 是"承重墙"——系统级兜底，不依赖 Agent 记性。拆了脚手架房子还能站，拆了承重墙直接塌。

一、记忆与上下文：Agent 的大脑皮层

模式 1-5 都在回答一个问题：Agent 应该记住什么，记在哪，记多久？

Agent 记忆有三个互相打架的诉求：容量（能记多少）、速度（多快查到）、相关性（查到的东西有没有用）。你不可能三个全要——容量大 + 速度快 = 上下文窗口塞爆；速度快 + 相关性高 = 只能记最近几轮；容量大 + 相关性高 = 检索慢。

这五个模式，就是在解这个不可能三角。

深讲：模式 3 — 分层记忆

做法：精简索引常驻上下文（控制在 ~200 行以内），相关内容按需加载，完整历史留磁盘。

Claude Code 的实现：MEMORY.md 是指向所有记忆文件的索引（永远在上下文里），memory/ 目录下是分类记忆文件（按需加载），完整对话历史在磁盘上（需要时再搜）。

为什么不是"把所有记忆一股脑塞进 prompt"？因为你塞进去的东西越多，模型越容易"看不见"真正重要的那一条。记忆的价值不在量，在在正确的时刻被加载到正确的上下文里。

代码实现：memory_loader.py — 三层记忆加载
- load_index()：索引永远加载，硬限制 200 行，超限 raise ValueError
- load_hot(topic)：按 topic 关键词匹配相关记忆文件，最多 3 个
- search_cold(query)：冷存储全文搜索（生产环境用向量检索）

重点不在代码，在分层逻辑：索引文件有硬行数限制（200 行）。因为索引一膨胀 → 分层失效 → 退化回"全量塞 prompt"的原始状态。

其余四个速览：

| 模式 | 一句话 | 什么时候该用 | 什么时候过度设计 |
|------|--------|------------|----------------|
| 1. 持久化指令 | 给 Agent 一份项目级"员工手册" | 任何需要跨会话保持行为的项目 | 文件超 500 行还没拆分 → 升级到模式 2 |
| 2. 作用域上下文 | 不同目录自动加载不同规则 | Monorepo、多语言项目 | 单项目 3 个文件以内 → 一个 CLAUDE.md 够用 |
| 4. 记忆整合 | 后台定期清理重复/冲突/过期记忆 | Agent 持续运行数周以上 | 项目刚跑两周 → 手动清理就行 |
| 5. 渐进压缩 | 对话长了自动对旧消息分层压缩 | 单会话超 20-30 轮 | 短会话（10 轮以内）→ 压缩反而丢信息 |

Python 映射：用 LangGraph 搭 Agent 的话，模式 3 对应 MemorySaver + checkpoint 的分层。LangChain 的 ConversationSummaryBufferMemory 是模式 5 的简化版。

踩坑记录：MEMORY.md 索引文件三个月从 80 行涨到 190 行，再涨就要触发分层失效了。真正踩过的坑不是"怎么存更多"，是"怎么删旧的"——一条三个月前的项目决策记录，对今天的 Agent 判断到底是参考还是噪音？

二、工作流与编排：把"想"和"做"的上下文拆开

模式 6-8 回答一个问题：Agent 处理复杂任务时，怎么不让上下文变成垃圾场？

典型灾难性长会话：前 10 轮调研（大量网页内容涌进来），中间 5 轮讨论方案，最后 3 轮才动手写代码。到写代码的时候，上下文窗口里 90% 是跟当前任务无关的历史噪音。

解法都是分离——把不同阶段的上下文隔离开。

深讲：模式 7 — 上下文隔离子智能体

做法：不同任务用不同 sub-agent，各自独立上下文窗口和权限。
- 做调研的 sub-agent：只读权限，只看资料，产出一份报告
- 做规划的 sub-agent：只设计方案，不碰代码，不碰原始资料
- 做执行的 sub-agent：有完整工具权限，但只接收"蓝图 + 调研摘要"，不接收 100 页原始网页

关键不在"拆 sub-agent"，在主 Agent 怎么做"信息编辑"——不是把调研全文直接转发给执行 agent，是从 100 页里挑出跟当前任务相关的 3 段。

Claude Code 的 Agent tool 就是这个模式的直接实现——subagent_type 决定角色，isolation 决定是否独立 worktree。

| 模式 | 一句话 | 什么时候该用 | 什么时候过度设计 |
|------|--------|------------|----------------|
| 6. 探索-规划-执行 | 先只读探索，再规划，最后动手改 | 不熟悉的代码库、涉及多文件的复杂改动 | 改一行配置 → 直接改比走三轮快 |
| 8. 分支-合并并行 | 多个互不依赖的子任务并行跑 | 批量重构多个模块、独立测试 | 子任务之间有依赖 → 并行反而制造合并冲突 |

三、工具与权限：最小权限原则在 Agent 系统里的落地

模式 9-11 回答一个问题：Agent 能做什么操作？怎么保证它不捅娄子？

确认疲劳 = 没有门控。第 1 次认真看确认框，第 10 次麻木直接点确认，第 50 次连弹的什么命令都没看清。

深讲：模式 10 — 命令风险分类

三级风险判定，不是二元"放行 vs 确认"：
- 低风险（读文件、查看状态、搜索）：自动放行
- 中风险（写文件、执行脚本、安装包）：弹确认
- 高风险（sudo、rm -rf /、修改系统设置）：直接拦截

分级逻辑必须落在确定性代码里，不能靠 prompt。靠 prompt 分级 = 模型某天"理解偏了"把 rm -rf / 判成低风险 = 生产事故。

代码实现：command_risk.py — 命令风险三级分类
- HIGH_RISK_PATTERNS：rm -rf /、sudo、chmod 777、mkfs.、dd if=、fork bomb、chown -R /
- MEDIUM_RISK_PREFIXES：rm、git push、git reset --hard、pip install、npm install -g、docker rm、kubectl delete

| 模式 | 一句话 | 什么时候该用 | 什么时候过度设计 |
|------|--------|------------|----------------|
| 9. 渐进式工具扩展 | 默认只给读+搜索，写和执行按需开 | 项目初期快速搭建 Agent 原型 | 工具少于 5 个 → 直接全开放 |
| 11. 单用途工具 | Read 读、Write 写、Edit 改——各自独立 | Agent 需要频繁文件操作 | 工具少于 3 个 → 合并反而更简单 |

踩坑记录：Agent 自动执行 find . -name "*.md" -exec sed -i ... 做批量替换，路径没加引号撞上有空格的目录名。从那以后把"写操作"的 sandbox 路径限制加进了 PreToolUse 钩子。权限控制不是在防恶意，是在防无心之失。

四、自动化兜底：不该让模型记住的事

模式 12 是整个分类体系里唯一一个"不该由 LLM 参与"的模式。

深讲：模式 12 — 确定性生命周期钩子

做法：把这些动作挂在 Agent 生命周期的关键节点上，由系统自动触发，完全不经过 LLM。

常见挂载点：
- PreToolUse：工具调用前触发——比如执行 shell 命令前跑风险分级
- PostToolUse：工具调用后触发——比如写完文件自动 ruff 格式化
- SessionStart：会话开始时触发——加载项目级 CLAUDE.md
- Stop：会话结束时触发——检查是否有未提交产物、跑最终校验

类比：模式 1-11 是给 Agent 的"驾驶培训"，模式 12 是"安全带 + 刹车灯"。

代码实现：hook_system.py — 确定性生命周期钩子系统
- 三个关键设计：(1) 钩子是确定性的——不调 LLM (2) 与 prompt 解耦 (3) 失败即阻断——返回 False 或抛异常，后续操作不执行

结尾：从"更聪明的模型"到"更可靠的系统"

为什么恰好是这 12 个模式？因为这 12 个模式覆盖了 Agent 工程中四类不可绕过的架构问题：记忆怎么管、任务怎么拆、权限怎么控、兜底怎么做。解决这些问题的不是更好的 prompt，是更好的架构——把确定性逻辑从 LLM 推理中剥离。模型做判断，系统做执行。

即使三年后 Llama 7 或 GPT-6 的推理能力强 10 倍，上下文窗口依然有物理上限、危险的 shell 命令依然危险、记忆依然会腐烂、模型依然会忘掉 prompt 里写的"每次都做"的步骤。

Bilgin lbryam："模型可以换，工具也会变，但这些设计很可能会一直存在。"

参考资料：
[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