基于费曼学习法整理自 Claude Code 架构逆向工程研究。 本指南为 AI Agent 设计者提供可落地的架构决策框架—— 从 8 个通用失败模式到 5 大设计支柱， 涵盖工具选择、记忆分层、权限设计与扩展机制。
费曼第一步：用最简单的语言说清楚"问题是什么"。这 8 个不是 bug，是架构级别的盲点。
费曼第二步：理解"为什么需要 Agent 架构"。关键洞见——谁掌控循环，谁就掌控智能。
工作流的问题：研究阶段发现需要先澄清需求，但 DAG 里这条路不存在。只有自主循环才能应对真实世界的不确定性。这是架构失败 #6（硬编码行为）的根源。
费曼第三步：找到核心机制。整个 Agent 系统的心脏只是一个死简单的循环——复杂性全部委托给模型本身。
maxTurns 上限防止失控循环最被低估的架构决策。给模型一个 Shell，它就能执行人类工程师能执行的任何工作流。
为什么放弃向量嵌入？连续重新索引脆弱、部署面积大、企业安全审查难通过。让模型用 Bash + Grep + Glob 迭代搜索代码库——同样准确，部署简单得多。这就是"原语工具哲学"应用于检索的例子。
费曼第四步：找出每个架构决策背后的"为什么"——每个支柱都精确对应特定的失败模式。
最影响留存率的产品特性。用户期望 Agent 记住一切，6 层分层记忆是实现这一点的工程路径。
高级模式：「地图，而非百科全书」— 巨型 CLAUDE.md 最终会腐烂。最佳实践是把根文件当作极简目录（指向 docs/design、docs/api、docs/plans），强迫 Agent 有意识地导航文档结构，而非把无关规则全部塞入上下文。对比：Cursor Rules / Windsurf Rules 的演化路径。
这是 Agent 从工具变成平台的关键跨越。PM 可以写 CLAUDE.md，运维可以加 Hooks，平台团队可以发布 Plugins。
把这张表带进下次 Agent 选型会议或设计评审。每行是一个你必须问的问题。
费曼最终步：极简化。删掉所有废话，只留下你下次设计 Agent 时真正会用到的东西。
一句话总结整个架构：一个模型无关的 harness，给任何支持工具调用的 LLM 提供文件系统访问、Shell、分层记忆和声明式可扩展性——全部运行在一个受可组合权限约束的自主循环中。