Claude Code 的五层 Agent 开发工具包：大多数工程师忽略的架构大多数工程师认为他们只是将 Claude

从**CLAUDE.md**和 Skills 到 Hooks、Subagents 和 MCP，Claude Code 已经为记忆、专业知识、防护栏、委派和工具访问提供了分层架构。

大多数工程师认为他们只是将 Claude Code 用作编码助手。实际上，他们坐在一个更大得多的 Agent 运行时之上，却很少审视它。Anthropic 自己的文档表明，Claude Code 不仅仅是一个强模型的终端界面。

它已经包含了通过 CLAUDE.md 实现的持久化记忆、可复用的 Skills、确定性的 Hooks、可委派的 Subagents、可安装的 Plugins，以及基于 MCP 的外部系统连接。这意味着，真正的故事不仅是 Claude Code 能生成什么，而是它的行为如何被塑造、约束、专业化，并在工作流和团队之间共享。

这一点很重要，因为大多数 Agent 的失败实际上不是提示词失败。它们是架构性失败。一个系统之所以崩溃，是因为它没有持久的记忆层、没有模块化的知识层、没有确定性的防护栏层、没有清晰的委派层，或者没有将行为打包供团队复用的方式。

Anthropic 的文档现在分别描述了这些机制：CLAUDE.md 用于始终在线的上下文，Skills 用于按需的专业知识，Hooks 用于工作流自动化，Subagents 用于隔离的任务执行，Plugins 用于将能力打包成一个可安装单元。

一旦你从这个角度来理解产品，Claude Code 看起来就不那么像"终端里的 AI"，而更像是一个藏在眼前的 Agent 开发工具包。

在这篇文章中，我将 Claude Code 分解为一个五层栈：CLAUDE.md 作为记忆层，Skills 作为知识层，Hooks 作为防护栏层，Subagents 作为委派层，Plugins 作为分发层。目标不仅是解释每个部分的作用，更是展示为什么每个部分都能解决仅靠提示词无法解决的问题。

1. Claude Code 不仅仅是提示词界面

大多数工程师使用 Claude Code 就像使用一个异常强大的编码助手：打开终端，给它一个任务，让它检查文件、运行命令、帮助推进工作。这并没有错，但这只是冰山一角。

Anthropic 自己的文档将 Claude Code 描述为一个驻留在终端中的 Agentic 编码工具，能够理解代码库、执行常规任务，并通过 MCP 等机制连接到外部系统。仔细阅读文档后会发现，Claude Code 不仅仅是一个包装在 CLI 中的模型。它更接近于一个结构化的 Agent 运行时，具有多个控制面来管理记忆、模块化知识、委派、确定性执行和外部工具访问。

这种区别很重要，因为仅靠 LLM 不足以支撑生产级工程工作。基础模型可以生成代码、解释文件和回答问题，但它本身无法解决持久化项目记忆、可复用任务专业知识、基础设施级防护栏、有界委派或标准化团队分发等问题。

这些问题存在于提示词之外，而 Claude Code 的架构正日益反映这一现实。Anthropic 的文档现在分别记录了持久化指令文件（如 CLAUDE.md）、可扩展的 Skills、自定义 Subagents、Hooks 和预处理行为、设置作用域、Plugins 和 MCP 连接。综合来看，这些不是随机功能。它们构成了一个分层系统，旨在使 Agent 行为更可靠、更可复用、更易于运维。

这就是为什么我认为从架构角度而非功能角度来看待 Claude Code 是有意义的。有趣的问题不再是"Claude Code 能做什么？"更好的问题是"Claude Code 暴露了哪些层次来控制 Agent 行为如何被塑造、约束、委派和共享？"

一旦你这样看待它，这个栈就变得更容易理解了：CLAUDE.md 充当记忆和策略层，Skills 提供模块化专业知识，Hooks 添加确定性防护栏，Subagents 处理有界委派，Plugins 和范围化设置帮助在团队间分发行为。MCP 和 Agent-team 模式则围绕这个栈，作为将其连接到外部世界的系统。

这个框架也解释了为什么生产环境中 Agent 工作流的许多失败并非因为模型不够强。而是因为某个层缺失了。

一个团队可能完全依赖提示词，但没有持久的项目记忆。或者他们可能有很强的指令，但缺乏围绕风险工具使用的确定性控制。或者他们可能让一个通用 Agent 超负荷工作，而不是将工作分配到专门的 Subagents 上。Claude Code 之所以有趣，是因为它的文档越来越多地在不同层次上暴露了这些问题的答案。本文的剩余部分将逐一分解这个栈，从最基础的层开始：CLAUDE.md。

第 1 层 — CLAUDE.md：记忆层

Claude Code 架构的第一层是 CLAUDE.md，可以说这是最基础的层。Anthropic 的文档将 CLAUDE.md 描述为向 Claude 提供关于如何在项目中工作的持久化指令的地方，而自动记忆则存储 Claude 根据重复修正和偏好为自己编写的笔记。

这个区别很重要。CLAUDE.md 不是临时提示词的草稿本。它是团队编码持久化上下文的地方：编码标准、架构决策、首选库、审查清单以及应从每个会话开始就存在的工作流约束。

关键的技术点是，Claude Code 不会将 CLAUDE.md 视为仅从当前目录加载的单个项目文件。根据文档，Claude 会从工作目录向上遍历目录树，加载沿途发现的每一个 CLAUDE.md 和 CLAUDE.local.md。

这些文件被拼接进上下文而不是彼此覆盖，靠近启动目录的指令会较晚被读取。

这比大多数工程师假设的模型要灵活得多。这意味着 CLAUDE.md 不仅仅是"一个配置文件"，而是一个范围化的记忆系统，可以在更高级别表达广泛的规则，在更靠近活动代码的地方表达更具体的规则。

这种加载模型正是使 CLAUDE.md 成为真正记忆层（而非仅仅另一个指令文件）的原因。顶层文件可以捕获全局仓库约束，如命名约定、测试期望或架构边界，而更深层的文件可以缩小一个子系统的行为范围。

Anthropic 还支持通过 @path/to****/import 语法导入指令文件，这允许团队将大型指令集拆分为更小的可复用模块，而不是让一个 Markdown 文件变成垃圾场。导入的文件在启动时被展开到上下文中，并且导入可以递归链式引用最多五层。实际上，这使得 CLAUDE.md 更接近于一个可组合的项目记忆系统，而不是一个静态的提示词模板。

在 CLAUDE.md 和自动记忆之间还有一个重要的操作区别。Anthropic 的文档明确指出，两者在每个会话开始时都被加载，但它们扮演不同的角色。CLAUDE.md 包含人类有意编写的指令。自动记忆存储 Claude 自己在机器本地记忆目录中积累的笔记，通过 MEMORY.md 建立索引，在会话启动时仅加载该索引的前 200 行或 25 KB。

相比之下，CLAUDE.md 文件无论多长都会被完整加载，尽管 Anthropic 指出较短的文件往往能获得更好的遵循度。所以 CLAUDE.md 是受控的、声明式的记忆层，而自动记忆是自适应的、涌现性的那一层。

这就是为什么我认为正确理解 CLAUDE.md 的方式不是"你粘贴一次让 Claude 记住你的风格的那种上下文"。它更像是 Agent 的工作宪法。

Anthropic 的文档甚至提到了在 macOS、Linux、WSL 和 Windows 上集中管理 CLAUDE.md 文件的组织级部署路径，这进一步强化了这一层不仅承载个人偏好，还承载持久操作策略。

一旦你这样看待它，CLAUDE.md 的作用就变得更加清晰：它是记忆和策略层，防止团队在每个会话中重复说明相同的约束，并在任何任务特定工作开始之前为 Agent 提供一个稳定的行为基线。

第 2 层 — Skills：知识层

如果 CLAUDE.md 是持久记忆和策略层，那么 Skills 就是为 Claude Code 提供按需模块化专业知识的层。Anthropic 的文档将 Skills 描述为通过将指令放入 SKILL.md 文件来扩展 Claude 能力的一种方式。

Claude 可以通过斜杠命令直接调用技能，或者在检测到任务相关时自动加载。关键的架构点是，Skills 不像永久项目记忆那样被加载。与 CLAUDE.md 不同，技能的主体仅在实际需要时才被引入上下文，这使得它成为一种更干净的方式，用于附加可复用的过程、清单或领域特定指导，而不会默认使每个会话变得臃肿。

这个区别比它乍看起来要重要得多。许多工程师将 Agent 定制化视为一个长提示词：把所有东西都放进持久化上下文，然后希望模型能搞清楚什么重要。

Skills 提供了一种更结构化的替代方案。Anthropic 明确建议，当你发现自己反复粘贴相同的指令，或者当 CLAUDE.md 的一部分已经演变成一套流程而非一个事实时，就应该创建一个技能。换句话说，CLAUDE.md 应该承载持久的项目规则，而 Skills 应该承载可复用的操作知识。这种分离使始终加载的上下文保持精简，并将复杂的工作流转化为 Claude 可以在适当时调用的模块化组件。

Anthropic 的文档还明确指出，Skills 不仅仅是重命名的自定义命令。该平台现在将旧的 .claude/commands/*.md 文件和新的 .claude/skills/*/SKILL.md 定义视为在调用层面功能相似，但 Skills 提供了更多控制。

它们支持包含附属文件的目录结构、调用控制（使用户或 Claude 都可以触发它们）、动态上下文注入，甚至可以在 Subagent 中执行。这就是为什么我认为将 Skills 称为"知识层"是恰当的框架。它们不仅仅是快捷方式。它们是专业知识、流程和可复用任务上下文在 Agent 运行时内变得可组合的单位。

这也直接关联到你的架构图。在实践中，一个 Skill 就像一个有限的任务特定知识包：描述告诉 Claude 这个技能是做什么的，运行时匹配决定它是否适用，相关指令仅在有用时被加载。Anthropic 的文档明确指出，内置技能如 /debug、/loop 和 /simplify 是基于提示词的而非固定逻辑，这是关于整体设计的一个重要线索。

Skills 是使 Claude 行为变得模块化而不必将所有内容硬编码到核心产品的机制。这是一个比期望单个巨大的基础提示词覆盖每个工作流要可扩展得多的模式。

其实际价值很直接。假设一个团队有一个调试不稳定测试、审查 SQL 迁移或准备发布说明的标准流程。这些都是持久记忆太宽泛而一次性提示词又太重复的情况。

一个 Skill 让团队将流程打包一次，将参考资料放在旁边，让 Claude 仅在任务需要时才加载该知识。Anthropic 甚至指出，Skills 中的长参考资料在被使用之前几乎没有任何代价，这意味着 Skills 不仅在架构上更干净，在操作上也更高效。

这就是为什么我认为 Skills 是 Claude Code 栈中第二个必不可少的层。CLAUDE.md 给 Agent 一个稳定的宪法。Skills 给它针对性的、可复用的专业知识，而不会膨胀主上下文窗口。

这种组合正是将 Claude Code 从一个通用助手转变为一个能够同时承载持久项目记忆和模块化领域知识的系统的关键。下一层是使这种行为在实践中更安全的要素：Hooks。

第 3 层 — Hooks：防护栏层

如果 Skills 是模块化知识层，那么 Hooks 就是将 Agent 行为转变为更具操作性执行力的层。Anthropic 的官方文档将 Hooks 描述为一种通过在事件发生前后运行命令来自动化 Claude Code 工作流的方式。

Hooks 指南明确涵盖了诸如在编辑后自动格式化代码、阻止对受保护文件的编辑、在压缩后重新注入上下文、审计配置更改、在文件变化时重新加载环境状态以及自动批准特定权限提示等模式。这与提示词的角色非常不同。提示词可以建议行为。Hook 可以确定性地拦截或改变行为。

这就是为什么我认为 Hooks 最好被理解为防护栏层，而不仅仅是自动化便利工具。Anthropic 的文档显示，hooks 可以附加到诸如 PreToolUse 等事件上，成本指南给出了一个具体示例，其中 PreToolUse hook 拦截 Bash 命令并重写测试调用，使 Claude 只看到失败输出而非完整流。

在这个例子中，hook 读取传入的 JSON 负载，检查命令，并返回更新工具输入的结构化 JSON。这不是"AI 做出更好的决策"。这是基础设施在控制模型在给定工作流阶段允许看到或做的事情。

这个区别很重要，因为提示词级别的防护栏对于生产环境来说往往太软了。如果一个团队想要确保生成的代码总是被重新格式化、敏感文件不能被更改、或者破坏性工具调用需要更严格的审查，仅依赖指令是不够的。Hooks 将这些控制移出了模型的自由裁量范围。

Hooks 文档明确围绕自动化模式来构建它们，如阻止编辑、在特定生命周期事件上通知、以及在压缩后保持会话上下文一致。换句话说，Hooks 使得在事件级别强制执行工作流行为成为可能，而不仅仅是要求模型表现良好。

Hooks 也很好地融入了更广泛的 Claude Code 架构，因为它们与上下文管理并行运作，而非在其内部。Anthropic 的故障排除文档甚至将"hooks 未触发"列为一个独立的配置问题，这是关于产品如何对待它们的有用线索：Hooks 是运行时环境的一部分，而不仅仅是聊天内的内容。

文档还推荐使用 /doctor 来诊断 hooks、MCP 服务器和上下文使用的问题，这进一步强化了 Hooks 属于系统执行层的定位。它们不仅仅是 Claude 读取的指令；它们是必须正确连接到会话运行时的配置驱动行为。

这里还有一个实际的成本和性能角度。Anthropic 的成本指南明确建议将处理任务卸载到 hooks 和 skills，因为 hooks 可以在 Claude 看到输入之前对其进行预处理。他们自己的例子是将一个巨大的测试日志过滤到只保留失败部分，将原本数万 token 的内容减少为一个小得多的负载。

这是一个重要的架构教训：Hooks 不仅关乎安全。它们也关乎效率。一个放置得当的 hook 可以减少 token 浪费，保持上下文更干净，并防止模型花费时间在可预测的过滤工作上——这些工作由确定性的 shell 逻辑来做更便宜、更可靠。

这就是为什么我认为 Hooks 是大多数团队最先低估的层。持久记忆帮助 Agent 记住。Skills 帮助它专业化。但 Hooks 让团队将重复的操作期望转化为确定性策略。

它们位于模型驱动的推理和系统强制执行的行为之间的边界，而这正是许多生产故障实际发生的地方。一旦这一层缺失，质量就过于依赖提示词了。下一层 Subagents 解决了一个不同的问题：不是控制，而是委派。

第 4 层 — Subagents：委派层

如果 Hooks 解决的是控制问题，那么 Subagents 解决的是委派问题。Anthropic 的文档将 Subagents 描述为专门的 AI 助手，它们在自己的上下文窗口中处理特定类型的任务，只返回结果。

这个设计很重要，因为退化 Agent 会话的最快方式之一就是让每个附带任务用日志、搜索结果或永远不会被复用的探索性推理来污染主对话。

Subagents 是 Claude Code 对这个问题的回答：而不是强迫一个通用 Agent 在一个线程中做所有事情，主 Agent 可以将附带任务委派给一个独立运行的专业工作者，并报告一个摘要回来。

Subagents 通过将探索和实现排除在主对话之外来帮助保存上下文，通过有限的工具访问来强制执行约束，跨项目复用配置，通过聚焦的提示词来专业化行为，甚至通过将合适的任务路由到更便宜的模型（如 Haiku）来降低成本。

这就是为什么我认为"委派层"是恰当的框架。一个 Subagent 不仅仅是一个命名的提示词。它是一个有界执行单元，拥有自己的描述、系统提示词、模型、工具权限、记忆设置和运行时范围。

这也解释了为什么 Subagents 不仅仅是对高级用户的便利。Anthropic 包含了几个内置的 Subagents，如 Explore、Plan 和 General-purpose，每个都有不同的工具访问权限和预期用途。

Explore 针对只读搜索和代码库分析进行了优化，Plan 在规划工作流期间使用，general-purpose Agent 处理涉及推理和行动的更复杂的多步骤任务。

重要的是，文档还指出内置 Subagents 继承父会话的权限并附加工具限制。这是一个微妙但重要的系统设计选择：委派不是无限制的。它是按设计有界的。

文档还确认了你社交帖子中的一个关键点：Subagents 不会无限递归。Anthropic 明确指出 Subagents 不能产生其他 Subagents，这一限制是 Claude 避免无限嵌套同时仍然收集必要上下文的方式的一部分。

这是一个关键的设计决策。没有这样的硬边界，委派很容易变成不受控制的 Agent 树，既昂贵又难以监控和推理。通过防止嵌套生成，Claude Code 保持了委派模型的简洁性：主 Agent 向下委派工作，Subagent 在隔离中执行，结果返回。

从实际的工程角度来看，Anthropic 设计中最有用的部分是 Subagents 可以在多个范围内配置。

它们可以通过 /agents 命令交互式创建，存储在用户级别的 ~/.claude/agents/、项目级别的 .claude/agents/、通过 CLI 传入当前会话，或通过插件分发。

每个 Subagent 只是一个带有 YAML 前置元数据 的 Markdown 文件，但它定义的行为非常丰富：模型选择、工具访问、记忆行为、hooks 和 skills 都可以作用域到该特定委派的工作者。换句话说，Subagents 不仅仅是角色标签。它们是用于专门工作的打包执行配置文件。

这就是为什么我认为 Subagents 是 Claude Code 中最重要的架构层之一。

CLAUDE.md 使主 Agent 扎根于项目规则。Skills 给它模块化的专业知识。Hooks 在运行时强制执行策略。但 Subagents 是防止整个系统崩溃为一个承载过多责任的过载对话的关键。它们为附带工作创建硬边界，让团队专业化工作流，并保持主上下文更干净、更持久。

一旦你有了这个委派层，下一个问题就变成了组织性的而非技术性的：你如何在团队中打包和分发所有这些行为？这就是下一层的内容。

第 5 层 — Plugins：分发层

一旦一个团队在 CLAUDE.md 中有了持久记忆，在 Skills 中有了模块化专业知识，通过 Hooks 有了确定性控制，以及通过 Subagents 有了有界委派，下一个问题就不再是本地行为了。而是分发。

你如何使这个架构在代码库、机器和团队成员之间可移植，而不必每次都手动重建？这就是插件层作为一个心智模型变得有用的地方。

Anthropic 的文档暴露了多种跨作用域打包和复用 Claude Code 行为的机制：用户级和项目级 Subagents、共享 Skills、插件设置、组织级 CLAUDE.md 部署，甚至还有提供代码智能或附加功能的插件。

在实践中，这意味着 Claude Code 不仅仅可以为一个人配置。它越来越多地被设计为允许团队标准化和分发 Agent 的行为方式。

这里最强的官方信号来自 Anthropic 的插件和设置模型。成本和设置文档描述了专用的插件配置部分、插件允许列表以及插件权限（如 codeIntelligence.*），支持项目本地设置和继承的用户设置。

Anthropic 还指出，CLI 参数如 --append-system-prompt 和 --allowedTools 不会传播到插件中，这强化了一个重要的架构点：插件被视为有界分发单元，拥有自己的行为表面，而不是父会话的被动扩展。

这正是为什么我认为"分发层"是恰当的框架。插件不仅仅是添加工具。它们是关于打包 Agent 行为，使其可以被安装、复用和大规模治理。

同样的分发模式也出现在 Subagents 和 Skills 中。Anthropic 的 Subagent 文档支持多种安装范围，包括用户级存储 ~/.claude/agents/、项目级存储 .claude/agents/、通过 CLI 传入的仅会话 Subagents，以及可以作为更大包的一部分分发的插件定义的 Subagents。

Skills 遵循类似的可模块化设计，允许可复用的操作知识存在于始终加载的记忆层之外，并仅在被调用时才激活。换句话说，Claude Code 的架构不再停留在"Agent 能做到吗？"它越来越多地在问"这个能力如何被打包和共享？"这是一个真正平台的标志，而非单一用户助手。

这一层还有一个治理角度。插件模型让团队分发的不仅是便利性，还有策略。一个共享包可以携带批准的 Subagents、精心范围化的工具权限、标准 Hooks 或组织特定的工作流。

Anthropic 的记忆文档甚至记录了在 macOS、Linux、WSL 和 Windows 上企业部署的集中管理 CLAUDE.md 路径，这表明标准化不是事后才考虑的事情。

同样的分层架构，帮助个人工程师更快地工作，也可以转化为团队范围的操作模型，其中记忆、专业知识、控制和委派被一次性安装并一致继承。这是一个比依赖每个人都记住相同的提示词配方要强大得多的模型。

这就是为什么我认为 Plugins 是栈中最终的 core 层。CLAUDE.md 定义稳定的规则。Skills 打包专业知识。Hooks 强制执行运行时策略。Subagents 创建有界工作者。Plugins 和共享打包机制使所有这些都可移植。

它们是让 Agent 行为从个人设置变为团队资产的关键。一旦有了这个分发层，整个栈就可以更容易地通过 MCP 服务器连接到外部世界，并组合成更广泛的 Agent-team 模式。

大多数 Agent 失败源于某个缺失的层

让 Claude Code 有趣的不仅是它是一个 Agentic 编码工具。Anthropic 的文档清楚地表明，它也是一个可扩展的运行时，具有不同的机制用于持久化指令、模块化专业知识、确定性工作流控制、委派执行和外部工具集成。

CLAUDE.md 定义持久的项目指导，Skills 在相关时加载可复用的任务知识，Hooks 在特定生命周期点自动执行，Subagents 在独立的上下文中隔离专注的子任务。综合来看，这些不是孤立的功能。它们是对真实 Agent 系统中不同失败模式的独立回答。

这就是为什么我认为生产环境中 Agent 工作流的大多数失败应被理解为架构性失败而非模型失败。当一个系统忘记团队约定时，缺失的层通常是持久记忆。当它不断重复相同的设置指令时，缺失的层是模块化知识。

当它在风险行为附近表现不一致时，缺失的层是确定性防护栏。当主上下文变得嘈杂和过载时，缺失的层是委派。当行为无法跨项目或团队标准化时，缺失的层是分发。模型可能仍然很好，但没有周围的层，工作流仍然脆弱。

Anthropic 自己的指导强化了这种分层解读。它们的最佳实践文档明确区分了建议性指令和确定性 hooks，指出 hooks 是当某些事情必须每次都发生且零例外时的正确工具。

它们的 Subagent 文档强调上下文保存和专业化。它们的 Skills 文档将 skills 定位为重复指令、清单和多步骤过程的正确位置，这些内容不应存在于始终加载的记忆中。

即使是概览页面也一致地将 Claude Code 描述为一个读取代码库、运行命令并与开发环境集成的工具，这更接近于一个操作系统而非一个聊天界面。

我的看法是，这是未来思考 Claude Code 的更有用的方式。最大的飞跃不是模型变得更擅长编码了。而是周围的系统越来越多地暴露了在实践中使编码 Agent 更可靠所需的层次。

一旦你不再将 Claude Code 视为"终端里的助手"，架构就变得更容易推理了。CLAUDE.md 给 Agent 一个宪法。Skills 给它模块化的专业知识。Hooks 在运行时强制执行质量。Subagents 保持委派有界。MCP 和更广泛的扩展面将这个栈连接到真实的工具和真实的工作流。

而这，在我看来，就是隐藏在 Claude Code 中的真正 Agent 开发工具包。不是一个神奇的功能，而是一个分层系统，其中每个部分都解决了一个仅靠提示词无法解决的问题。

-------------------------------------------------------------

Claude Code 的五层 Agent 开发工具包：大多数工程师忽略的架构

目录：