12 个 Agent 工程设计底层逻辑：脚手架 vs 承重墙¶

📊 Level ⭐⭐⭐⭐ | 10.0KB

原文归档：原文归档

Bilgin Ibryam 提炼 Claude Code 12 个设计模式的中文深度解读，增加"什么时候过度设计"判断框架和完整 Python 代码实现。云朵君/数据STUDIO。

一句话¶

12 模式四类（记忆/编排/权限/兜底），1-11 是脚手架（拆了还站），12 是承重墙（拆了塌），核心原则：把确定性逻辑从 LLM 推理中剥离。

核心隐喻¶

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

四类架构问题¶

类别	模式	核心问题
记忆与上下文	1-5	Agent 应该记住什么，记在哪，记多久
工作流与编排	6-8	怎么不让上下文变成垃圾场
工具与权限	9-11	Agent 能做什么操作，怎么保证不捅娄子
自动化兜底	12	不该让模型记住的事

记忆不可能三角¶

容量 × 速度 × 相关性，只能三选二： - 容量大 + 速度快 = 上下文窗口塞爆 - 速度快 + 相关性高 = 只能记最近几轮 - 容量大 + 相关性高 = 检索慢

模式 3 深讲：分层记忆¶

三层：索引常驻（~200 行硬限制）→ 热层按需加载 → 冷层搜索

Claude Code 实现：MEMORY.md（索引）→ memory/（分类文件）→ 磁盘（完整历史）

关键：索引一膨胀 → 分层失效 → 退化回全量塞 prompt

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

主 Agent 的核心能力不是"拆 sub-agent"，是信息编辑——从 100 页调研里挑出相关的 3 段传给执行 Agent。

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

三级风险判定（低/中/高），分级逻辑必须落在确定性代码里，不能靠 prompt。

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

四个挂载点：PreToolUse / PostToolUse / SessionStart / Stop

三个关键设计：(1) 不调 LLM (2) 与 prompt 解耦 (3) 失败即阻断

什么时候过度设计¶

模式	过度设计信号
1 持久化指令	文件超 500 行没拆分 → 升级到模式 2
2 作用域上下文	单项目 3 个文件以内 → 一个 CLAUDE.md 够
4 记忆整合	项目跑不到两周 → 手动清理就行
5 渐进压缩	短会话 10 轮以内 → 压缩反而丢信息
6 探索-规划-执行	改一行配置 → 直接改比走三轮快
8 分支-合并并行	子任务有依赖 → 并行制造合并冲突
9 渐进式工具扩展	工具少于 5 个 → 直接全开放
11 单用途工具	工具少于 3 个 → 合并更简单

踩坑记录¶

MEMORY.md 索引文件三个月从 80 行涨到 190 行，再涨触发分层失效
Agent 跑 find -exec sed 路径没加引号撞上空格目录名
真正的坑不是"怎么存更多"是"怎么删旧的"

深度分析¶

记忆不可能三角：不是三个开关，是一条约束面¶

容量、速度、相关性三个诉求并非独立的设计选项，而是同一枚硬币的三面——任何记忆方案都落在"三选二"这条约束面上，没有免费午餐。模式 1-5 的五个模式，本质是这条约束面上的五个不同取点：持久化指令（模式 1）牺牲速度换容量与相关性，作用域上下文（模式 2）用空间换相关性，渐进压缩（模式 5）用精度换容量。分层记忆（模式 3）之所以最受重视，不是因为它打破了三角，而是它把三角的取舍内嵌到了分层结构里——索引层赌相关性（常驻但硬限 200 行），热层赌速度（按需加载），冷层赌容量（全文搜索）。记忆的价值从来不在"存了多少"，而在"在正确的时刻把正确的东西加载进正确的上下文"。

分层记忆 vs 上下文隔离：两种对抗"上下文膨胀"的策略¶

模式 3 与模式 7 表面上都在解决上下文膨胀，路径却截然相反。分层记忆（模式 3）把全部记忆留在同一个上下文窗口内，只按加载优先级分层管理，切换成本低，但代价是单个脆弱窗口——索引一旦膨胀，分层失效，就退化回"全量塞 prompt"的原始状态（这正是踩坑记录里 80→190 行的警报）。上下文隔离（模式 7）则物理上拆开上下文：调研、规划、执行各用独立的 sub-agent 窗口与权限，避免"写代码时 90% 是历史噪音"。隔离的代价是交接开销，且成败取决于主 Agent 的"信息编辑"能力——从 100 页里挑出相关的 3 段，而不是把全文转发过去。两者的共同敌人是同一个：噪音淹没信号。参见 Context Isolation。

命令风险分级与确定性钩子：安全逻辑必须脱离 prompt¶

模式 10 与模式 12 共享同一条设计信条：确定性逻辑必须落在确定性代码里，不能靠 prompt。风险分级之所以要三级（低/中/高）而不是二元放行/确认，是因为二元只有"有门控"和"没有门控"两种状态——而"确认疲劳"（第 50 次直接点确认）实际等于没有门控。分级要靠 HIGH_RISK_PATTERNS 这样的确定性规则，靠 prompt 分级 = 模型某天把 rm -rf / 判成低风险 = 生产事故。模式 12 的确定性生命周期钩子（PreToolUse/PostToolUse/SessionStart/Stop）把同样的原则推向自动化：不调 LLM、与 prompt 解耦、失败即阻断。二者呼应全文主线——从"更聪明的模型"到"更可靠的系统"：模型做判断，系统做执行，把确定性逻辑从 LLM 推理中剥离。

模式图谱的元设计："什么时候过度设计"本身就是一种模式¶

回顾 12 个模式，它们覆盖四类不可绕过的架构问题——记忆怎么管、任务怎么拆、权限怎么控、兜底怎么做。而作者自带的"什么时候过度设计"判断表，本身就是最值得提炼的元设计：模式 1-11 是脚手架，其价值是帮 Agent 更好地工作，当它不再为此付费时（改一行配置、工具少于 5 个、短会话 10 轮以内）就该拆掉；模式 12 是承重墙，拆了直接塌。这套"脚手架 vs 承重墙"的二分，给出了落地时的取舍标尺——不是所有模式都要上，而是先判断当前规模下哪个模式在替你扛风险、哪个只是增加复杂度。脚手架能拆就拆，承重墙一根都不能少。

实践启示¶

盯住索引膨胀这条生死线：分层记忆（模式 3）的索引有 ~200 行硬限制，一旦膨胀分层就失效、退化成全量塞 prompt。定期清理旧记忆比"存更多"更关键——真正的坑是"怎么删旧的"，不是"怎么存新的"。
长会话主动拆上下文：调研/规划/执行各用独立 sub-agent（模式 7），靠"信息编辑"只传 3 段相关摘要给执行 Agent，而不是转发 100 页原文。主 Agent 的核心能力是裁剪，不是转发。
权限分级必须落到确定性代码：低风险自动放行、中风险确认、高风险硬拦截（模式 10），用 HIGH_RISK_PATTERNS 这类规则而非 prompt——模型会"理解偏"，rm -rf / 必须无条件拦下。
把一次性校验挂到生命周期钩子上：格式化、风险分级这类确定性动作放到 PreToolUse/PostToolUse/Stop 等钩子（模式 12），不调 LLM、失败即阻断，把 LLM 的推理留给真正需要判断的事。
动手前先问"是不是过度设计"：改一行配置别走探索-规划-执行三轮，工具少于 5 个别分级、单项目 3 个文件以内一个 CLAUDE.md 够用。脚手架能拆就拆，承重墙一根都不能少。
用"三个月后是参考还是噪音"过滤记忆：写进长期记忆的每条决策，都要问它三个月后对 Agent 的判断是帮助还是干扰——记忆的价值在正确时刻被加载，不在总量。参见记忆主矛盾与 Working Set vs Long-Term Memory。