作者花12天系统学习Claude Code，从"自我感觉良好"到发现"90%的能力被浪费在桌上"——最大的收获不是某个功能，而是看清了一条从Prompt Engineering到Loop Engineering的递进逻辑链：记忆层解决"知道什么"、Skill定义"怎么执行"、Hook自动治理"不用人检查"、Subagent隔离上下文、Plugin复制协作基因。

我的个人知识库搭建分享系列文章虽然告一段落了，但之前也埋下了一个彩蛋，就是现在GitHub上交付的这版，背后其实潜藏着我对“系统化学习Claude Code产品能力”这件事的自我投射实践和思考。

出发点还是我一直把Claude Code作为我的AI工作站，从最开始小心翼翼的输入/init试探它的能力，到应用于项目规划、方案设计、数据分析等常规工作场景，再到沾沾自喜开始尝试搭建自己的个人作品——比如个人知识库，跑通并开始长期通过知识库产出知识时，看着那逐渐丰满的知识卡片主题网络，开始有点飘了，自认为对Claude Code应用已经“炉火纯青”了。

然而打脸来的很快，自己用的项目很容易让人产生“自我感觉良好”的幻觉，一旦到了拉出去溜溜的时候（找了好心的内测同学来体验我认为比较得意的一些产品），才发现原形毕露——其他外部用户在使用过程中暴露出来的产品稳定性/健壮性/可扩展性等等一系列问题瞬间教做人。

为了系统性解决这些问题，我意外找到了一个名为Claude howto的开源项目（建议大家也可以抽时间系统学习下，项目长期更新中：https://github.com/luongnv89/claude-howto ），它的README里有一句话就是对我这种情况的精准打击——You’re leaving 90% of Claude Code’s power on the table — and you don’t know what you don’t know，于是我花了 12 天把 Claude Code 的 10 个核心模块全部系统性的学了一遍。

学完后回头看，最大的收获不是任何具体功能，也不全是基于学习到的知识最终应用到了我的实际项目上，而是看清了它的能力设计背后有一条清晰的逻辑链——整个产品能力构建是一套层次递进的完整agent体系，暗含着从Prompt Engineering到Loop Engineering的演进史，是“上一阶段做极致后，探索新的设计解决新的问题”。 感觉跟我搭建知识库时：遇到不同阶段的问题在升级，解决方案也伴随着升级的逻辑一样（bushi）。

这条链路出自于挖掘Claude Code产品设计哲学本身，但我发现这是Agent 协作类产品的精髓。

一、记忆层：AI 的上下文要义不是“全记住”，而是分层按需加载

为什么需要记忆

Claude Code 最基本的交互是斜杠命令行对话——你输入命令，它执行命令。这个模式有一个根本局限：每次新会话，AI 对你的了解归零。 你的项目规范、命名习惯、架构约定——全部要重新交代。如果项目复杂，光是交代背景就要消耗大量上下文窗口。

记忆体系的核心设计

Claude Code 的 Memory 体系不是简单的“记住用户说过什么”。它设计了一套 8 层分级架构，从全局到局部，优先级递减：

不同层级在不同场景被加载。项目级 CLAUDE.md 在启动时自动加载；规则文件按路径匹配按需加载（通过 YAML frontmatter 的 paths 字段控制）；自动记忆只加载前 200 行或 25KB。

这个设计的关键决策是：不是让 AI 记住所有信息，而是让它在对的场景加载对的信息。 全量记忆 = 上下文浪费 + 噪声干扰。

学习前后对照

学完这套架构后，我重新审视了自己个人知识库项目的 CLAUDE.md——快接近500 行，从项目定位到格式规范，到脚本说明，到项目进展和计划全塞在一起——简直就是完美的反面教材。

但这也意味着学习后的优化空间很大，于是在我学习后总结出来三条原则：

1. 分层承载：核心共识写 CLAUDE.md，条件规则写 .claude/rules/，变动内容 @import，个人偏好写 CLAUDE.local.md，Auto Memory 定期审查后毕业或清理
2. 上浮测试：删掉某个 Skill 后规则还有意义吗？有就上浮到项目规则，没有就留在 Skill
3. 最小记忆：CLAUDE.md 只放”Claude 每次对话都必须知道的”，其余要么 @import、要么放目录规则、要么不进 Memory

结果：516行精简到 168 行（-67.44%），同时创建了 knowledge-schema.md 和 card-creation-rules.md 两个独立规则文件。主文件信息密度更高，规则文件按需加载不浪费上下文。

产品启发

如果你在设计 Agent 产品，第一个要回答的问题不是“怎么让 AI 记住更多”，而是“用户的信息应该以什么粒度、在什么场景、被哪个层级加载”。Claude Code 的 8 层架构给出了一个参考答案：组织级 → 项目级 → 模块级 → 个人级 → 自动学习级，每一层解决不同作用域的持久化问题。最常见的错误是把所有指令塞进一个 CLAUDE.md——最简单，但也最浪费上下文、最容易让指令遵循率下降。事实放 CLAUDE.md，流程放 Skill，约束放 Rules，是这 8 层架构教给我的第一条原则。

二、执行协议层：Skill 不只是“写一段好的提示词”，而是定义一份工作协议

为什么记忆层不够

有了 Memory，AI 知道了你的规则。但“知道规则”和“知道怎么执行规则”是两件事。比如我的知识库有一个“深度讨论”流程：拿到一篇笔记 → 做多轮对话 → 判断是否需要生成知识卡片 → 落盘。Memory 可以告诉 AI“深度讨论要做三轮”，但它不规定每轮的准入条件是什么、什么情况应该中止、输出格式是什么。没有执行协议，AI 每一步都在临场发挥。

Skill 的核心设计

Skill 采用三层渐进式加载架构：

这个设计意味着你可以安装大量 Skill 而不会造成上下文惩罚——启动时 AI 只知道每个 Skill 的存在和触发条件（L1），直到真正需要时才加载完整指令（L2），详细参考文档按需读取（L3）。

Skill 的触发靠 description 字段的语义匹配：AI 将用户请求与每个 Skill 的描述做匹配，命中则激活。description 的质量直接决定 Skill 能否被正确触发。所谓质量我总结主要是两条决定：1. 高度提炼你skill的流程或职责；2. 给它一个准确的触发场景描述（兼顾包容性和排他性）。

Skill 可以包含两类内容：参考内容（增加 AI 的领域知识，如 API 规范、风格指南）和任务内容（特定动作的分步指令，如“部署到生产环境”）。好的 Skill 同时包含清晰的步骤、操作约束和验收标准——它本质上是一份工作协议，而不是一段提示词。

学习前后对照

学完 Skill 设计方法论后，我给自己已有的 5 个 Skill 做了一次深度体检。问题最严重的是 deep-discuss 的 Stage 2 环节——深度讨论的核心阶段。

体检发现：Stage 2 只有流程描述，没有场景约束。没有准入准出标准，没有规定一轮还是多轮，完全靠 AI 临场判断。用了这么久我一直觉得它“有时好有时飘”，根因就在这里——操作约束对执行稳定性的影响远大于流程步骤本身。

同一天我还做了一个判断：topic-deep-discuss（主题级讨论）和 deep-discuss（单篇讨论）要不要合并？分析后发现——输入维度不同、内核逻辑不同、合并会让 L2 指令体量翻倍加剧上下文浪费。决定独立保留，并用 disable-model-invocation: true 控制两者的调用方式——有副作用的工作流（如落盘、迁移）以及需要用户深度参与的，只允许用户手动触发，不允许 AI 自动调用。

产品启发

Agent 执行复杂任务时，最大的不稳定来源不是模型能力不够，而是执行协议的完整性。一个 Skill（或任何 Agent 工作流）需要的不只是“做什么”，还需要“做到什么程度算完”“什么场景下不该执行”“异常时怎么处理”。这里有一个常见误区：很多人把 Skill 等同于“一段好的提示词”。实际上 Skill 的本质是按约定结构打包的一组文件——Skill 远比提示词丰富，它包含步骤、约束、验收标准和参考资源。Claude Code 的做法是把约束条件显性化为 SKILL.md 的一部分——如果你的 Agent 产品里工作流经常“飘”，先检查下你是否在合适的位置加了合适的约束条件。

三、自动治理层：人不应该是最贵的质检员

为什么 Skill + Memory 还不够

Memory 和 Skill 解决了“AI 知道什么”和“AI 怎么做”的问题。但两者可能都面临一个共同局限：需要人来发起和检查。

你得手动告诉 AI“现在执行深度讨论”，你得手动检查“这张知识卡片的 YAML 格式对不对”，你得手动确认“这次写入的 ID 有没有和已有的冲突”。人的检查是最贵的治理方式——贵不只是时间成本，更贵的是人会遗忘、会偷懒、会在赶工时跳过检查。

Hook 的核心设计

Hook 是事件驱动的自动化机制。它在 AI 执行特定动作的前后，自动触发你预设的检查脚本。Claude Code 提供了 5 种 Hook 类型和 30 个事件：

5 种类型：

• Command：执行 Shell 脚本（最常用）
• HTTP：POST 到远程 Webhook
• Prompt：让 LLM 做单轮判断（常用于 Stop 事件，检查任务是否完成）
• MCP Tool：调用外部 MCP 工具
• Agent：启动一个独立 Subagent 做判断（可多步骤推理）

30 个事件

覆盖 AI 执行的完整生命周期：会话开始/结束、用户提交输入、工具调用前/后、权限请求、子 Agent 启停、任务完成、配置变更等。

其中最关键的设计区分是阻断型 Hook vs 通知型 Hook：

• 阻断型（如 PreToolUse）：在工具执行前拦截，可以 allow/deny/ask，甚至可以修改工具输入参数后再放行。适合“源头拦截”场景。
• 通知型（如 PostToolUse）：在工具执行后触发，不能阻止操作，但可以注入额外上下文或反馈。适合“事后检查”场景。

Hook 通过 JSON stdin/stdout 通信，exit code 2 表示阻断错误。所有匹配的 Hook 并行执行，默认 60 秒超时。

学习前后对照

我落地了两个 Hook，解决的是知识库中最频繁出错的两个格式问题：

1. YAML 引号阻断（PreToolUse + Write）：知识库中所有引用其他笔记的字段必须使用单引号包裹 wiki-link，否则 YAML 解析出错，Dataview 查询全部失效。以前靠人工检查，现在 Hook 在每次写入前自动扫描，发现双引号直接阻断写入，exit code 2 返回错误信息。
2. KC ID 冲突检查（PreToolUse + Write）：知识卡片 ID 格式是 KC-YYYYMMDD-XXX，同日多张卡片时序号递增。以前偶尔 ID 重复、甚至会用一个未来日期来命名，因为 AI 生成新 ID 时不知道今天已用到几号。Hook 在创建文件前自动扫描当天已有 ID，冲突时当场提醒。

这两个 Hook 的共同特征是：确定性逻辑用脚本，推理判断逻辑才用 LLM。 Hook 负责“100% 精确的格式校验”，LLM 负责“需要理解的内容判断”。两者物理隔离，互不越界。

产品启发

在 Agent 产品中，人工检查是一个反模式——不可扩展，且一定会被跳过。正确做法是区分“确定性检查”（格式校验、规则匹配、边界条件）和“需要推理判断的检查”（内容质量、语义合理性），把前者固化到事件驱动的自动拦截中。这里有一个最常见的配置错误：把“每次编辑文件后自动跑 formatter校验”这类自动化需求写进 CLAUDE.md 或 Skill 里。模型选择做一件事跟自动执行一件事完全是两码事——前者靠提示词引导，后者靠事件稳定触发脚本。Claude Code 的阻断型/通知型 Hook 分离提供了一个设计参考：能在源头阻断的，不要留到事后修复；需要 LLM 判断的，用 Prompt 型 Hook 而不是人。

四、分工层：一个 Agent 干所有事是有上限的

为什么 Hook 层之后还需要 Subagent

Memory + Skill + Hook 构成了一套完整的单 Agent 治理体系。但随着任务复杂度上升，一个瓶颈开始显现：单 Agent 的上下文窗口是有限的。 一个具体的场景：我的“主题级深度讨论”流程需要扫描 7 个主题域索引页、读取数十张知识卡片、比对候选笔记、生成讨论框架。如果全部由主 Agent 执行，中间过程的信息会占满上下文窗口，后面的任务质量急剧下降。

Subagent 的核心设计

Subagent 的核心不只是“分工”，而是上下文隔离。每个 Subagent 从一个干净的上下文窗口开始工作——主 Agent 只把任务描述和相关细节传给它，不复制完整对话历史。Subagent 执行完后只把结论返回给主 Agent，不传回完整的推理过程。

Subagent 通过 Markdown 文件 + YAML frontmatter 定义，关键字段包括：name、description、tools（工具白名单）、model（模型选择）、maxTurns（最大执行轮次）、memory（记忆范围）。

Claude Code 内置了 6 个 Subagent（general-purpose、Plan、Explore、Bash、statusline-setup、Claude Code Guide），用户可以自定义更多。

什么时候该用 Subagent，什么时候不需要？我总结三条标准：多步骤执行 + 需要 LLM 判断 + 上下文消耗大。如果只是单步判断或规则匹配，用 Skill 就够了——Subagent 引入的协调成本不值得。

学习前后对照

学习 Subagent 那天，教程模板预置了 4 个候选：主题聚类器、卡片归类器、卡片网络链接器、Review 审核器。我用三条标准逐一检验——主题聚类是单步判断，卡片归类是规则匹配，另外两个同理。4 个候选全部不达标。

最终我提出了自己的候选：topic-candidate-selector（待讨论笔记筛选器）。它需要扫描全部 Processed 笔记、匹配主题域、评估成熟度信号、输出候选清单——真正的多步骤、需要判断、上下文消耗大。

这个经历也让我总结了一个四层关系框架，用来解释 Claude Code 各组件的定位：Memory 是知识库，Skill 是工具包，Subagent 是专业员工，Hook 是办公室自动化。 四层各司其职。

产品启发

Agent 拆分的判断标准不是“功能不同”，而是“上下文是否需要隔离”。很多 Agent 产品的问题不是拆分不够，而是拆分过度——把简单的判断任务也做成了独立 Agent，增加了协调成本却没有减少上下文压力。同时，当你的 Agent 能做越来越多的事时，瓶颈会从“能力不足”切换到“治理不足”——边际收益最高的不再是让 Agent 更强，而是管住它。

五、复制层：从“我很强”到“谁都能强”

为什么前面四层还差最后一步

Memory + Skill + Hook + Subagent 构成了一套完整的个人级 Agent 治理体系。但所有配置都存在本地的 .claude/ 目录里。换一台电脑、换一个同事来用——一切从零开始。手动安装需要：逐个复制命令文件、单独配置每个 Subagent、手动设置 MCP、逐条注册 Hook。一个复杂系统的完整配置可能需要 2 小时以上。

Plugin 的核心设计

Plugin 是 Claude Code 的最高层扩展机制，把命令、Skill、Subagent、Hook、MCP 配置、LSP 服务器、可执行文件打包成一个可一键安装的整体。一条命令 /plugin install pr-review，2 分钟内完成安装和配置。

Plugin 的目录结构以 .claude-plugin/plugin.json 为清单文件（声明 name、version、author、description），下分 commands/、agents/、skills/、hooks/、bin/ 等子目录。

Plugin 和“一个文件夹的文件”之间的关键区别不只是打包——而是生命周期管理：语义化版本、自动更新、依赖声明与自动安装、市场发现与分类、Token 成本透明化（安装前可看到每轮消耗多少上下文 Token）。Plugin 的 Subagent 被沙箱化——不能声明 hooks、mcpServers 或 permissionMode，防止权限升级。

好的 Plugin 设计遵循一个原则：Bundle cohesion, not kitchen sinks（内聚打包，不是大杂烩）。如果组件之间不构成一个工作流，就不应该打包成 Plugin。

学习前后对照

在我学习接近尾声到了plugin这里的时候，我问了自己一个问题：如果另一个产品经理也想系统化的学习一门新领域知识，我能把我这次的学习方法论复制给他吗？

于是莫不如现学现卖，我也尝试把整个学习过程积累下来的能力，沉淀为包含 3 个 Skill、3 个 Subagent、4 个 Command、2 个 Hook，共 24 个文件的plugin。但最有价值的设计不是任何一个组件本身，而是一个共享文件——teaching-style-guide.md。它定义了所有组件的交互风格：亦师亦友，不冰冷也不说教。这个文件被所有 Skill 和 Subagent 共同引用。是我亲自试验下来觉得最应该补充和值得分享的。

Plugin 章节是我 12 天学习中得分最低的模块。技术细节和配置逻辑在没有实际踩坑的情况下感知不强。但正因为难，反而逼出了最有价值的认知：好的 Plugin 不是功能的合集，而是共享基因的载体。 你要复制的不是一堆文件，而是一套协作范式。

产品启发

当 Agent 产品从“个人使用”走向“团队分发”，核心挑战不是功能打包，而是基因复制。你的团队共享的是什么？一套命名规范？一套异常处理原则？一套交互风格？如果这些东西只在某个人的脑子里，方案就不可复制。把它们显性化为共享规则文件，是 Agent 产品从手工作坊到工业化的分界线。

收束：一条设计原则，和一个更大的故事

回头看 Claude Code 的能力体系，这五层不是功能清单上的并列项，而是一条递进的问题解决链：

每一层都不是“再加一个功能”，而是“上一层无法突破，卡在这里了，需要一个新的设计来解决”。

这条设计链不只适用于 Claude Code。任何 Agent 协作类产品，只要想让 AI 从“能聊天”进化到“能协作”，都绕不开这五个问题。区别只在于你的产品在哪一层做了更深的设计，在哪一层还有空白。

另外，这 12 天的学习其实也不是一般的自学——我用的是一套基于 Claude Code 自身搭建的 AI 导师学习系统。它同时扮演六个角色：路径规划师（安排学习顺序和计划）、资料管家（准备每日材料）、讲解员（把英文技术概念翻译为中文产品语言，补齐“学习过程陪伴”）、垂直资料库（MCP 接入外部知识源）、测评官（Pre-test/Post-test 量化验证）、项目导师（每天追问“这对你知识库有什么用”，三模式适配不同学习类型）。12 天的学习数据——每天的测评分数、42 项改进动作的执行追踪、5 张方法论卡片——都是这套系统驱动产出的。

这个“用 AI 学 AI”的过程本身，也成了一个值得分享的故事。关于怎么通过自己的实际体验设计一套 AI 导师学习平台、怎么从学习痛点中反推出产品方案，我在下一篇文章里展开。