Claude Code的五层结构：内存、技能、钩子、子智能体与插件。
Claude Code被视为一种智能体运行时：包含CLAUDE.md内存、按需调用的技能、确定性钩子，以及为团队整合所有功能的独立子智能体和插件。
来源: **Claude Code’s 5-Layer Agent Development Kit: The Architecture Most Engineers Are Missing**
许多工程师将 Claude Code 视为功能强大的编程助手：打开终端，交给他任务，让他读取文件并执行命令，然后看着工作逐步推进。这种描述虽准确但不完整。Anthropic 的文档则将其定义为一种运行在终端中的智能编程工具，它能理解代码库、执行常规任务，并通过 MCP 等机制连接外部系统。仔细阅读后会发现，这款产品与其说是一个包裹在命令行外壳中的模型，不如说是一个具备多种独立控制界面的结构化智能体运行环境。
这些组件包括以内存形式存在的CLAUDE.md文件、可重复使用的技能、确定性的钩子函数、用于分配任务的子代理、可安装的插件，以及连接外部系统的MCP链接。因此，有意义的问题发生了变化：与其询问Claude Code能生成什么，不如探讨如何塑造、约束它的行为，实现专业化，并在团队间共享。
五层架构
基础模型能够编写代码、解释文件并回答问题。但仅靠它本身还无法解决诸多问题：会话之间如何记住项目内容、如何复用任务相关的专业知识、如何在基础设施层面设置约束规则、如何限制可委托的任务范围，以及如何让团队保持一致的行为标准。这些难题都超出了提示词的处理范畴，而 Claude Code 的设计也越来越体现出这一点。文档中将持久化的指令文件、可扩展的技能、自定义子代理、钩子功能、设置作用域、插件以及 MCP 连接性视为独立的机制。它们并非杂乱无章的功能集合，而是构成不同层次的结构，从而使智能体的行为更加可靠、可复用且易于管理：
- CLAUDE.md属于记忆与策略层。
- Skills则是知识层，能够按需提供专业能力。
MCP和agent-team模式作为将整个架构与外部世界相连的系统，包裹在该堆栈之上。
相关分析揭示了失败代理项目中的一个共同模式：模型很少是薄弱环节，问题往往出在缺少某一层。有的团队完全依赖提示词而缺乏持久的项目记忆；有的团队虽有详尽的指令，但对高风险工具的使用缺乏确定性控制；还有的团队在本应分工处理的任务上让单个通用型代理承担过多工作。大多数代理系统的失败源于架构问题，而非提示词问题。下文将从底层开始逐一介绍每一层的内容。
为何架构视角优于功能列表
如果将 Claude Code 看作功能列表，就会产生它能做什么的疑问；而若从架构角度看待，则能提出更好的问题：它暴露了哪些层次，以便控制智能体行为的形成、约束、委托与共享？一旦问题视角改变，理解整个系统结构就会变得容易，实际出现问题时的诊断也会更为便捷。
文档中可得出两点结论。首先，这些机制都不存在于模型内部，而是分布在模型周围的文件、事件处理程序、配置范围以及打包格式中。其次，每一种机制都对应不同的故障场景：内存机制用于解决遗忘问题，技能机制用于处理通用行为问题，钩子机制用于应对不可靠性，子智能体机制用于解决上下文过于混乱的问题，而插件机制则用于避免手动重复设置带来的繁琐。
第一层：以CLAUDE.md作为记忆库
基础就是CLAUDE.md。文档中将其描述为存储项目工作相关持久指令的地方，而独立的自动记忆功能则用于保存Claude在多次修改和调整后为自己写的笔记。
这种分离很重要。CLAUDE.md并非临时提示的草稿纸。团队会将长期有效的上下文信息存放在这里：编码标准、以往的设计决策、常用的库、审查清单及工作流程限制，所有在会话开始前就需要了解的内容都会放在这里。
其加载方式是颇具技术趣味的部分。它并非仅从当前目录读取单个文件。Claude会从工作目录开始沿着目录树逐层查找，加载所有找到的CLAUDE.md和CLAUDE.local.md文件。这些文件会被合并为上下文内容，而非相互覆盖，而且距离启动目录较近的指令会优先被读取。
这使其成为一个有范围限制的内存系统，而非单独的配置文件。顶层文件可以存储整个代码库范围内的规则，如命名规范、测试预期或架构边界，而层级更深的文件则可针对某个子系统细化相关规则。以单仓库结构为例：根目录文件规定了测试的命名方式以及服务边界的位置，而支付目录下的文件则增加了仅适用于该目录的更严格的规则。在该目录下启动会话的用户将会同时看到这两类规则，其中更为具体的指导内容会最后被读取。
导入功能提升了组件的可复用性。@path/to/import 这一语法让团队能够将庞大的指令集拆分成更小的可重复使用模块，从而避免单个 Markdown 文件变得杂乱无章。Launch 会将导入的文件融入上下文中，而且一个导入项本身也可以继续导入其他文件，最多可嵌套五层。实际上，CLAUDE.md 更像是具有组合性的项目记忆系统，而非静态的提示词模板。
自动记忆与手动记忆的作用不同。两者都在每次对话开始时被加载，但CLAUDE.md存储的是人类刻意输入的内容，而自动记忆则保存在机器本地的目录中，由MEMORY.md进行索引。每次会话开始时仅加载该索引的前200行或25 KB数据。相比之下，CLAUDE.md文件无论长度如何都会被完整加载，不过Anthropic指出较短的文件能获得更好的后续处理效果。前者是受控的、基于明确规则的；后者则是自适应的、自然生成的。
比“仅粘贴一次上下文以便 Claude 记住风格”这种思维模式更好的做法是为智能体制定明确的操作准则。Anthropic 甚至为各大桌面操作系统规定了集中管理 CLAUDE.md 文件的组织级存储位置，这表明该机制旨在确立持久的操作规范，而不仅仅是个人偏好。这样一来，团队无需在每次会话中重复说明相同的约束条件，智能体也能在开始任何特定任务之前拥有稳定的基准。
加载规则带来的实际后果是，CLAUDE.md需要精心管理。由于每个被发现的文件都会被完整加载，因此每次会话都会产生冗余负担；而Anthropic建议优先使用较短的文件，这一指导也说明了定期清理文件的必要性。那些已超出文件容量限制的流程会成为首先被移除的对象，进而进入下一层级。
第二层级：按需获取的技能
如果CLAUDE.md代表持久性记忆与规则，那么Skills则提供按需调用的模块化专业能力。根据文档说明，将指令写入SKILL.md文件是让Claude获得新能力的途径。可以通过斜杠命令明确调用某项技能，或者当Claude判断任务适合时自行将其加载进来。
在架构设计中，关键在于时机控制。技能的“本体”并非永久性的项目记忆，只有在需要时才会被纳入上下文之中，因此可以添加可复用的流程、检查清单及领域指导，而不会使每次会话的负载过重。
许多工程师将定制化视为一个冗长的提示语：把所有内容都放入持久性上下文中，期望模型能自行判断哪些内容是重要的。而“技能”则是更为结构化的选择。Anthropic建议在相同指令被反复使用，或CLAUDE.md中的某部分内容从事实信息演变为操作流程时创建技能。CLAUDE.md应包含持久有效的项目规则，而技能则应承载可复用的操作知识。这样既能保持始终加载的上下文简洁，又能将复杂的工作流程转化为Claude可在适当时候调用的模块。
技能并非仅仅是自定义命令的别名。旧版的 .claude/commands/.md 文件与新版 .claude/skills//SKILL.md 定义在调用时的行为类似，但技能提供了更强的控制能力。它们允许存在包含相关支持文件的目录，可决定由用户、Claude 或两者共同触发，支持动态上下文注入，甚至能在子代理中运行。正因如此，“知识层”这一表述十分贴切：技能正是让专业知识、流程及任务上下文在运行时能够被组合使用的单元。
可以将某种技能视为一份针对特定工作的封闭知识包。其描述会说明该技能的用途，运行时通过匹配来判断它是否适用于当前请求，而其中的指令则仅在有用时才会被加载。文档中指出，/debug、/loop 和 /simplify 这类组合技能是基于提示语的，而非固定逻辑，这一特点很好地反映了其设计思路。由于无需将所有内容硬编码到核心产品中，因此功能实现更加模块化，相比依赖一个庞大的基础提示语来覆盖所有工作流程，这种模式的可扩展性要强得多。
想象一个拥有标准流程的团队，用于调试不稳定测试、审查SQL迁移或撰写发布说明。对于这类任务而言，持久内存的概念太过宽泛，而一次性提示则显得过于重复。团队会将相关流程封装一次，将参考资料放在旁边，只有当任务需要时才让Claude加载这些内容。技能中的长篇参考内容在未被使用前几乎不会产生任何成本，因此这种模式不仅更简洁，运行成本也更低。
因此，技能机制能够激励人们养成识别重复内容的习惯。每当同样的解释被输入第三次，或者CLAUDE.md中的某段文字开始呈现出编号流程的形式时，很可能就有适合提取为技能的内容。这项工作只需几分钟时间，但每次任务再次出现时都能带来回报。
总体而言，CLAUDE.md为智能体提供了稳定的基本规则，而Skills则为其提供了针对性且可重复使用的专业能力，同时不会增加主上下文窗口的负担。下一层则进一步提升了该行为的安全性。
第三层：作为约束机制的钩子
钩子将智能体的行为转化为可强制执行的操作。官方文档将其定义为事件驱动的自动化机制：在Claude Code中，某个命令会在特定操作之前或之后由相应事件触发而执行。这些钩子明确了其典型用途，包括在编辑后自动格式化代码、拒绝对受保护文件的修改、在对话被压缩后恢复上下文、审计配置变更、在文件发生变化时刷新环境状态，以及预先批准某些权限请求。
这与提示词的作用截然不同。提示词可以建议某种行为，而钩子则能够以确定性的方式拦截或修改该行为。正因如此，钩子更应被视为一种安全防护层，而不仅仅是自动化工具的便利功能。
一个具体的例子来自成本指南：PreToolUse钩子会捕获Bash命令，识别出测试运行并对其进行重写，这样Claude接收到的输出就只包含失败结果，而不会是完整的命令流。从机制上来看，该钩子会接收描述待处理调用的JSON数据，分析其中的命令，然后返回用于修改工具输入的JSON响应。整个过程中并非人工智能在做出更优决策，而是基础设施在控制模型在工作流中的某个阶段能够看到什么或执行什么操作。
与提示词级规则相比，这一点值得重点强调。软性约束往往对于实际应用来说过于薄弱。比如生成的代码必须始终重新格式化，敏感文件绝不能被修改，或者具有破坏性的工具调用需要更严格的审查。仅依赖书面指令是不可靠的，而钩子则将控制权移出模型的自主决策范围，在事件发生时强制执行工作流规则。
钩子位于上下文管理之外，而非其内部。故障排除文档将“钩子未触发”列为独立的配置问题，并建议使用/driver来诊断钩子、MCP服务器及上下文使用方面的问题。这些细节都表明，钩子属于执行环境的一部分：它是基于配置的行为，必须正确地集成到会话运行时中，而非Claude读取的文本。
还有成本方面的考虑。Anthropic的成本指南建议将处理任务交由hooks和skills来完成，因为hooks可以在模型看到数据之前对大量输入进行预处理。其示例是将庞大的测试日志仅筛选出失败案例，从而将可能包含数万个标记的数据量缩减为更小的负载。因此，hooks不仅能提升安全性，还能提高效率：它们能减少标记浪费，保持上下文更整洁，同时让模型不必承担那些可由确定性壳层逻辑更廉价、更可靠地完成的筛选工作。
想象一下变化前的状况与变化后的差异会有所帮助。在引入钩子之前，团队会在说明中写上“始终运行格式化工具”，然后寄希望于此。而引入钩子之后，无论模型是否记得，每次编辑时格式化工具都会自动运行，同时受保护的文件根本无法被修改。智能体仍然可以自由地思考要构建什么；而钩子则决定了在该思考过程中哪些操作是被允许的。
大多数团队最初都会低估这一层的作用。记忆能力帮助智能体留存信息，技能则帮助其实现专业化，但钩子将重复出现的操作要求转化为具体的规则。它们恰好位于模型驱动的推理与系统强制执行的行为之间，而许多实际的生产故障正是发生在这个环节。如果没有钩子，质量就会过度依赖提示词。
第四层：用于任务分配的子智能体
钩子用于实现控制，而子代理则负责任务委派。文档中将它们描述为专门的 AI 助手，能在各自的上下文窗口中处理特定类型的任务，并仅返回结果。
其原理很简单。破坏会话速度最快的方法之一，就是让辅助任务用日志、搜索结果或那些永远不会被重复使用的探索性推理内容来污染主对话。与其让一个通用型智能体在单个线程中处理所有事务，不如将辅助任务交给能够独立运行的专用工作节点，由其返回总结。这样做的好处包括：
- 探索与实现过程不会干扰主对话，从而保留上下文。
- 有限的工具访问权限有助于设定约束。
- 配置可在不同项目中重复使用。
- 针对性的提示语能让智能体的行为更加专业化。
将子代理称为“命名提示”其实低估了它的作用。实际上，它是一个独立的任务单元，包含描述、系统提示、选定的模型、允许使用的工具集、内存设置以及运行时间限制。
内置示例展示了各自的用途：Explore适用于只读搜索和代码库分析，Plan用于规划工作流程，而通用型代理则能处理需要结合推理与行动的复杂多步骤任务。文档还指出，内置子代理会继承父对话的权限，并附加额外的工具限制，因此任务委派在设计上就受到了约束。
还有一个限制：子代理不能递归。Anthropic指出，子代理无法生成其他子代理，这正是Claude在获取所需上下文的同时避免无限嵌套的方式。如果没有明确的边界，任务分配可能会演变成难以控制、成本高昂且难以监控和理解的代理树结构。该模型的设计保持简单：主代理将任务下放，子代理独立完成后再将结果上传。
从实际应用角度来看，子代理可在多个层级进行配置。它们可以通过 /agents 命令交互式创建，按用户存储在 ~/.claude/agents/ 中，按项目存储在 .claude/agents/ 中，通过命令行传递以供单次会话使用，或嵌入插件中。每个子代理都是带有 YAML 前置信息的 Markdown 文件，但其定义的功能十分丰富：模型选择、工具访问、内存管理行为、钩子函数以及技能等都可以针对该被委派的执行单元进行配置。它们属于打包好的执行配置文件，而非角色标签。
正因如此，子代理才属于最重要的层级之一。CLAUDE.md让主代理遵循项目规则，技能库提供模块化的专业能力，钩子则在运行时强制执行策略，而子代理则能防止一切陷入职责过多的混乱对话之中。这种隔离机制带来了隐性优势：子代理可以读取数十个文件、进行搜索甚至陷入死胡同，但这些探索过程都不会影响到主线程，主线程仅会收到最终结果。子代理为辅助任务划定了明确的边界，让团队能够专注特定工作流程，从而保持主上下文的整洁与持久性。在实现了任务分配之后，剩下的问题就是组织层面的：如何为团队整理所有这些内容。
确定每条规则的位置
由于有五层可供选择，放置规则的位置便成为一项设计决策。一个实用的测试方法是思考该规则应如何运作：如果必须始终明确知晓，就将其放入CLAUDE.md中；如果是仅偶尔需要的流程，则将其设为技能；如果无论模型做出何种决定都必须强制执行，那就用钩子来实现；如果相关工作较为复杂、独立性强或适合使用成本更低的模型，就交由子代理处理；如果整个方案需要被传递，就将其打包为插件。放在错误层级的规则往往会以类似的方式出问题：以普通文本形式存在的策略会被忽略，存储在内存中的冗长流程会挤占其他所有资源，而设计精巧但仅存在于某台笔记本电脑上的方案则永远无法传递给团队。
第五层：用于部署的插件
假设一个团队已经拥有其记忆文件、技能、钩子以及子代理。此时问题已不再是局部行为，而是分布式问题。如何让这样的配置在各个仓库、机器和团队成员之间传递，而无需每次都手动重新构建？
Anthropic提供了多种机制来跨不同范围打包和重用行为：用户级和项目级的子代理、共享技能、插件设置、全组织范围的CLAUDE.md部署，以及能够提供代码智能或其他功能的插件。Claude Code并非仅适用于个人配置，它越来越旨在帮助团队标准化并统一管理代理的行为方式。
最明确的官方信号便是插件与设置模型。相关设置文档介绍了专用的插件配置板块、允许列表以及诸如codeIntelligence.*之类的权限，同时还涵盖了项目级设置与继承自用户的设置。文档还指出，append-system-prompt和allowed-tools之类的命令行参数不会传递到插件中，这进一步证实了插件是具有独立行为规范的封闭式分发单元，而非父会话的被动扩展。因此，插件的作用更多在于封装代理行为，从而实现大规模的安装、重复使用及管理。
同样的模式也出现在其他地方。子代理支持用户级、项目级、会话专用以及插件定义的安装方式。各项功能采用模块化设计，使得可重复使用的技能无需始终加载在内存层中即可运行。该架构不仅关注代理是否具备某种功能，更注重如何将这类能力进行封装与共享，这正是平台型系统而非单一用户助手的显著特征。
治理也是其中的一部分。一个统一的包中可能包含经过审核的子代理、严格限制的工具权限、标准钩子，或是特定于某个组织的流程，因此团队传递的是政策而非仅仅是便利性。针对集中管理的CLAUDE.md文件所设定的企业级路径表明，标准化从一开始就已被规划在内。那种能够提升单个工程师工作效率的分层设计，可以发展成一种适用于整个团队的运营模式，在这种模式下，记忆、专业知识、控制机制和任务分配得以共享，而无需重复构建。
缺少某一层时会出现什么问题
从整体上看，这一系列组件为诊断不可靠的代理设置提供了实用的检查清单。出现的问题通常就表明有某一层缺失了。
- 该智能体总是重复提问或忽视房屋风格。它没有记忆功能。那些通用的规则应该放在CLAUDE.md中，按目录进行分类，并在文件过大时拆分成多个导入文件。
- 每次对话都从一大段粘贴的流程开始。知识被限制在提示词之中。应将可重复使用的部分放入技能模块中，这样只有在任务需要时才会加载这些内容。
- 高风险操作依赖于模型能够记住要谨慎行事。各种约束措施仅属于建议性质。而钩子功能则会在不管模型如何决策的情况下，自动完成格式化、文件保护以及命令重写等工作。
- 主要对话内容充斥着日志信息以及无果的讨论。缺乏任务分配机制。那些工具有限的子智能体会承担繁琐的辅助工作，然后仅返回总结结果。
这些解决方案的共同点在于，它们并非只是通过在提示词中写得更完善就能解决的问题，而是属于结构性改进，正因如此才能在实际工作负载下保持稳定。将 Claude Code 视为一种恰好集成在终端中的智能体开发工具，能让这些改进更易于被理解、更便于与团队讨论，也能更从容地逐层逐步地实施。