09｜16 小时 Claude Code：子代理、插件与记忆，如何拆分复杂任务

23 · 子代理（Subagents）：把活儿外包出去，别什么都自己扛

都说 subagent 强，是 Claude Code 的「高级玩法」。很多人刚知道这功能那会儿，也兴奋得不行，恨不得把一个任务拆成五六个子代理同时跑，觉得这样「更专业、更高效」。

但说句实话：多数人一上来就拆，是错的。

这事得用一阵子才能想明白。后面会专门讲为什么——这里先把结论撂这儿：子代理不是「任务越多越该拆」，它是个有明确适用场景的工具，用对了省心，用错了又慢又贵。 想清楚「该不该拆」，比学会「怎么拆」重要得多。

这一篇我不光教你建子代理、触发子代理，更重要的是帮你建立那条判断线：什么时候该外包，什么时候自己干更快。

看完这一篇，你会拿到：

• 子代理到底是什么——独立上下文、独立工具、独立人设，一句话讲透它和主对话的区别
• 它真正解决的三个问题（隔离上下文、专精任务、可并行），以及那个反共识的坑：什么时候不该拆
• 用 /agents 交互式建，或手写 .claude/agents/name.md 配置文件，各字段是干嘛的
• 两种触发方式：靠 description 自动委派 vs 你直接点名
• 一个能照着跑、给了预期输出的实战：亲手建一个最小子代理并让它干活

01 先搞懂：子代理到底是什么

先给结论：子代理就是 Claude 临时雇来的一个专项小弟——它在自己的房间里干活，干完只把结论交给你，过程中翻的一堆资料不占你的桌面。

类比：把一个活儿外包给专项小弟。 你手上一堆事，其中「把这一千行日志翻一遍，挑出报错的那几条」这种又脏又占地方的活，你不想自己在主工作台上摊开干——那会把你桌面堆满。于是你把它外包给一个专门干这个的小弟：他在自己的房间里，自己的桌子上，翻完那一千行日志；翻完了，他不会把一千行原始日志搬回来给你，只递给你一张纸条：「报错就这三条，分别在第 207、589、903 行」。你的桌面始终干干净净。

这个小弟有三样东西是「他自己的」，跟你（主对话）完全隔开。官方文档把这句话讲得很死，值得记住：

每个 subagent 在自己的 context window 中运行，具有自定义系统提示、特定的工具访问权限和独立的权限。

拆开看就是三件「独立」：

最关键、也最容易被忽略的是第一行：子代理是从一张白纸开始的。官方说得很直接——它「看不到您的对话历史、您已经调用的技能或 Claude 已经读取的文件」。Claude 会写一段「任务交代」丢给它，它就从这句话开始干。

这一点决定了子代理「擅长什么、不擅长什么」，下一节就靠它来判断。

💡 一句话总结：子代理 = 独立上下文 + 独立人设 + 独立工具的外包小弟，在自己房间干活、只交结论回来；记住它从白纸起步，看不到你们之前的对话。

02 它解决什么——和那个反共识的坑

知道了「是什么」，得搞清「为什么要有它」。子代理真正解决三个问题，我一个个说，第三点我会顺手把开头那个反共识的坑挖开。

问题一：隔离上下文，不污染主线

这是子代理最核心、最值钱的用途。

上下文——Claude 的「工作台」是有限的，你跟它聊得越久、读的文件越多，台面越挤，挤满了它就开始忘事、变笨。有些活会疯狂占台面，但产出的中间垃圾你压根不会再看第二眼。

比如「把整个测试套件跑一遍，告诉我哪些挂了」。跑测试会刷出几百上千行输出，但你真正要的就一句：「这三个测试挂了，错误是 XXX」。要是在主对话里直接跑，那几百行全糊你台面上了。

这时候外包给子代理：它在自己房间里把这几百行扛了，只把「挂了哪几个」这一句交回来。 你的主对话台面，干净如初。官方把这个用途列为子代理「最有效的用途之一」：

运行测试、获取文档或处理日志文件可能会消耗大量上下文。通过将这些委托给 subagent，详细输出保留在 subagent 的上下文中，而只有相关摘要返回到您的主对话。

真实场景：调一个第三方 SDK 时，得反复 curl 它的 API 看返回，每次刷一屏 JSON。聊到第十几轮，主对话被 JSON 塞得开始记不住最初的需求了。换个做法——让一个子代理专门去「试调这个接口、只告诉我字段长啥样」，主对话瞬间清爽，你自己的思路也不断了。

问题二：专精某类任务

第二个用途：给某类反复出现的活，定一个「专门干这个的人」。

你要是发现自己老在重复同一种指令——每次写完代码都让 Claude「以资深审查员的视角挑挑刺，重点看安全和命名」——那不如把这套指令固化成一个子代理，叫它 code-reviewer，以后一句话就能唤起。官方原话：「当您不断生成相同类型的工作者并使用相同的指令时，定义一个自定义 subagent。」

它「专」在两处：一是专属人设（系统提示里写死「你是只挑刺的审查员」），二是专属工具（审查员就该只读不写，那就把 Write、Edit 砍掉，它想改也改不了）。

问题三：可并行

第三个用途：几件互不相干的活，可以同时甩给好几个子代理一起跑。

比如「把认证、数据库、API 这三个模块分别调研一下」——这三块互不依赖，那就开三个子代理同时探索，最后 Claude 把三份结论汇总给你。串行得等三趟，并行一趟搞定。

反共识的坑：不是越多越该拆

好，铺垫完三个用途，回到开头那句——为什么「一上来就拆」是错的？

因为新手普遍有个误解：「拆得越细 = 越专业 = 越快」。完全反了。 子代理有三个隐性成本，简单活儿一拆，成本全冒出来：

官方专门给了一张「该用主对话还是子代理」的判断清单，我提炼成一句话：频繁来回、共享上下文、快速小改、在意速度的活，留在主对话；产出一堆你不想看的中间垃圾、要锁死工具权限、能自包含只回一句结论的活，才外包。

官方还点了个反直觉的细节——子代理在意「延迟」的场合反而是劣势：

延迟很重要。Subagents 从头开始，可能需要时间来收集上下文。

真实场景：要是犯轴，连「改个变量名」都要开个子代理，「显得专业」。结果呢？它得先把文件重新读一遍（因为它没你刚才的上下文），慢吞吞改完再回灌结果，比在主对话直接说「把这个变量名改了」慢了一大截，还多烧了 token。所以有条铁规矩值得记住：一句话能说清、改动就在眼前的活，绝不外包。

💡 一句话总结：子代理解决「隔离上下文、专精任务、可并行」三件事；但简单活儿直接干更快更省——拆得多 ≠ 专业，过度拆只会又慢又贵又把台面堆回去。

这张图把「外包」这件事画清楚了：主对话是你的工作台，把一个会刷出大量中间输出的脏活（跑测试 / 翻日志）甩给子代理；子代理在自己独立的上下文房间里扛下全部细节，最后只有一行「结论摘要」回到主线，你的台面始终干净。

03 怎么建：/agents 交互式建

讲完「该不该用」，来动手建一个。最省事的方式是用 /agents 命令，全程交互式，不用手写一个字的配置。

在 Claude Code 会话里敲：

/agents

会弹出一个管理界面。建一个新的，官方推荐的流程是这样几步（我按官方演练复述，你照着走就行）：

1. 选位置：切到 Library 标签 → Create new agent → 选 Personal。选 Personal 会把它存到 ~/.claude/agents/，所有项目都能用；选 Project 则只在当前项目用、还能跟着 git 提交给团队（这俩的区别下一节细说）。
2. 让 Claude 帮你生成：选 Generate with Claude，然后用大白话描述你要个啥样的助手。比如：「一个代码审查助手，扫描文件、从可读性、性能、最佳实践三个角度提改进建议，每条都说清问题、贴出当前代码、再给改进版。」Claude 会自动帮你写好名字、描述和那段人设系统提示。
3. 选工具：审查员只该读、不该写，那就只勾 Read-only tools，其他全取消。官方提醒了一句关键的：「如果您保持所有工具被选中，subagent 会继承主对话可用的所有工具。」——不主动砍，它就什么都能干。
4. 选模型：给它单独挑个模型。审查这种活，官方示例选的是 Sonnet（分析能力和速度平衡）。
5. 保存：看一眼配置摘要，按 s 或 Enter 存下，立马就能用。（实际界面还会让你选背景颜色和内存范围 memory scope；颜色随意，内存默认 None 即可，新手跳过。）

类比：填一张「外包岗位申请单」。 你不用懂怎么写合同，前台（/agents 界面）拿张表一项项问你：这岗位叫啥、干啥活、能动哪些工具、用哪个档次的人——你填完，它把这个「岗位」给你建好了。Generate with Claude 就像旁边有个 HR 帮你把表填得漂漂亮亮。

真实场景：一个很值的常驻子代理就是这么建出来的——一个 test-runner，专门「跑测试、只回报挂了哪些 + 错误信息」。建的时候特意只给它 Read 和 Bash，不给 Write，就是怕它跑着跑着手痒去改你的代码。建一次，之后天天用。

💡 一句话总结：/agents 是建子代理的推荐方式，全程交互式填表、还能让 Claude 帮你生成人设；记住主动砍工具，不砍它就继承主对话的全部权限。

04 怎么建：手写一个配置文件

交互式建好之后，它落到磁盘上其实就是一个 Markdown 文件。看懂这个文件，你也能直接手写、或者改别人的。

子代理文件长这样——上面一段 YAML 头（frontmatter）管配置，下面的正文就是它的人设（系统提示）：

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

类比：给外包小弟的一张工牌 + 一份岗位说明书。 YAML 头是工牌上的硬信息——叫什么名、是干什么的、能动哪些工具、什么档次（name/description/tools/model）；横线下面那段正文，是塞给他的岗位说明书，「你是谁、来了先干嘛、按什么标准干」。他上岗只看这两样，看不到你公司其他乱七八糟的事。

官方明确，只有 name 和 description 是必填的，其余都可省。把常用字段拎出来说清楚：

放文件的位置有讲究，位置决定了「谁能用到它」。官方列了好几档，小白只需记住最常用的两档：

官方对项目级这档的建议很实在：

项目 subagents（.claude/agents/）非常适合特定于代码库的 subagents。将它们检入版本控制，以便您的团队可以协作使用和改进它们。

最后一个新手必踩的坑，官方用了个 Note 专门提醒——手写或直接改磁盘上的文件后，得重启会话才会加载；但通过 /agents 界面建的，不用重启、立即生效。第一次手写完一个子代理，很容易碰到叫它半天没反应、还以为写错了的情况，其实就是忘了重启。

💡 一句话总结：子代理就是个 Markdown 文件，YAML 头管配置（必填只有 name/description）、正文是人设；放 ~/.claude/agents/ 全局可用、放 .claude/agents/ 项目内共享；手改文件记得重启会话。

05 怎么触发：自动委派 vs 直接点名

子代理建好了，怎么让它干活？两条路：Claude 看「岗位描述」自动派单，或者你直接点名叫它。

路子一：description 驱动的自动委派

你正常提你的需求，Claude 会拿你这句话去比对每个子代理的 description，觉得对得上就自动把活派过去。 你甚至不用知道有这么个子代理存在。

这就是为什么上一节反复强调 description 要写清楚——它是 Claude 派单的唯一依据。官方给了个提升「主动性」的小技巧：在 description 里加上「use proactively」（主动使用）这类话，Claude 就更愿意主动委派。比如那个审查员的描述写成「写完或改完代码后立即主动审查」，你一改完代码它可能就自己唤起审查员了。

类比：岗位描述写得好不好，决定 HR 会不会把对的活派给他。 description 就是这个外包岗位的「招聘启事」。启事写得含糊（「处理一些任务」），HR（Claude）根本不知道啥活该找他；写得精准（「专门审查代码安全和命名，写完代码后主动上」），对口的活一来，HR 自然就想到他。

路子二：你直接点名

自动委派不靠谱、或者你就想指定某个子代理时，自己点名。官方给了几种由轻到重的方式，小白记住前两种够用：

自然语言点名——直接在话里叫它的名字，没有特殊语法：

用 code-reviewer 子代理看看我最近的改动

@ 点名——输入 @ 从弹出的列表里选（选中后会插入形如 @"code-reviewer (agent)" 的写法），也可以不走列表、直接手敲 @agent- 加名字。这种是「保证」用它，不把选择权留给 Claude：

@agent-code-reviewer 看看这次认证相关的改动

两者的区别官方讲得很清楚：自然语言是「Claude 通常会委托」，而 @ 是「确保特定 subagent 运行」。一个稳妥的习惯——新建、还没摸透脾气的子代理，一律用 @ 点名，免得 Claude 自作主张没派给它，你还以为子代理坏了。

结论怎么交回来

不管哪种方式触发，子代理干完，只把「结论」交回主对话，过程全留在它自己房间。 这正是第 01 节那个比喻的兑现：小弟翻完一千行日志，只递回一张「报错在这三行」的纸条。官方原话：它「独立工作并返回结果」，且「详细输出保留在 subagent 的上下文中，而只有相关摘要返回到您的主对话」。

⚠️ 但这里有个量的陷阱，官方专门警告过：开太多子代理、每个都回灌一大坨详细结果，照样会把你主对话的台面堆满。 所以并行也别贪多——回到第 02 节那条线：能自包含、只回一句结论的活才值得外包。

💡 一句话总结：触发分两路——靠 description 让 Claude 自动派单（描述要精准），或用自然语言 / @ 直接点名（@ 是保证用它）；子代理只把结论交回主线，但回灌太多照样堆台面。

06 动手：5 分钟建一个最小子代理并让它干活

光看不练假把式。下面带你手写一个最小子代理，再让它真的跑起来，亲眼看到「外包 → 只回结论」这条链路。全程不依赖任何复杂环境。

我们建一个最简单的：一个只读的「代码点评员」，专门读文件、给改进建议，但一个字都不准改（只给 Read，不给 Write/Edit）。

第一步：建一个玩具项目和子代理目录（Mac / Linux）

mkdir sub-demo
cd sub-demo
mkdir -p .claude/agents

预期：sub-demo 文件夹里有了 .claude/agents/ 这层目录。敲 ls .claude 能看到 agents 在。

第二步：手写子代理配置文件

用你顺手的编辑器，新建 sub-demo/.claude/agents/code-reviewer.md，贴入：

---
name: code-reviewer
description: 只读的代码点评员，读指定文件并从可读性、命名、潜在 bug 角度给改进建议。审查任何代码时主动使用。
tools: Read, Grep, Glob
---

你是一个资深代码审查员，只挑刺、不改代码。
被调用时：
1. 读用户指定的文件
2. 按可读性、命名、潜在 bug 三类列出问题
3. 每条问题给出具体的改进建议，但不要直接修改文件

按严重程度分组：必须改、建议改、可以考虑。

注意这里没给 model 字段——按官方默认，它会 inherit（用你主对话同款模型）。tools 只列了三个只读工具，它想写也写不了。

第三步：造一段「有改进空间」的代码给它点评

echo 'def f(a, b):
    return a / b' > calc.py

这个函数名 f、参数名 a/b 都很烂，还没处理除以 0——正好让点评员逮。

预期：sub-demo 里有了 calc.py，内容是上面那两行。

第四步：启动 Claude，点名让子代理干活

claude

进去后，用 @ 直接点名（保证用它，别让 Claude 自作主张）。手敲 @agent-code-reviewer，或者敲 @ 后从弹出列表里选 code-reviewer：

@agent-code-reviewer 点评一下 calc.py

预期：你会看到 Claude 委派给 code-reviewer 子代理（界面上会标出这个子代理正在跑，可能带个颜色块）。它在自己的上下文里读完 calc.py，然后只把一份「点评结论」交回主对话——大致会指出：函数名 f 和参数 a/b 不达意、缺少除数为 0 的处理、建议改成更清楚的命名并加边界判断。注意它只给建议、没动你的文件（因为你没给它 Write 工具）。

第五步：验证它真的没改文件

退出 Claude（敲 exit 或按 Ctrl+D），回终端看：

cat calc.py

（Windows PowerShell 用 type calc.py）

预期：calc.py 原封不动，还是那两行——这就是「限权」的威力：你只给了只读工具，它就算想帮你改也无能为力，只能动嘴。

跑通这五步，你就把「写配置 → 加载 → 点名触发 → 子代理在独立上下文干活 → 只回结论、不越权」这条完整链路亲手验证了一遍。以后任何子代理，本质都是在这套机制上换人设、调工具。

⚠️ 如果敲 @agent-code-reviewer 时列表里没有它，多半是子代理文件加载没生效——手写的文件需要重启会话（第 04 节那个坑）。退出重进，或者干脆用 /agents 界面建（免重启）。

💡 一句话总结：手写一个只给 Read 的点评员、用 @ 点名让它跑、再 cat 确认文件没被动——亲手跑通「独立干活 + 限权不越界」这条链路，比记十条字段都管用。

07 小结

这一篇我们把「子代理」从「该不该用」一路讲到「怎么建、怎么触发、怎么验证」——核心不是教你拆得多花哨，而是帮你建立那条「该外包还是自己干」的判断线。

把要点串起来回顾：

你现在应该能： 判断一个任务该不该外包给子代理（而不是一激动就拆），用 /agents 或手写文件建一个带专属人设、限定工具的子代理，并用自动委派或 @ 点名让它干活、把结论干净地交回主线。这套「该外包就外包、该自己干就自己干」的分寸感，才是子代理真正的门槛——功能十分钟学会，分寸得用出来。

记住开头那句反共识的话：子代理强，但强在「用对场景」，不在「拆得多」。

💡 一句话总结：子代理的门槛不是「会建」，是「知道什么时候该建」——脏活、可自包含、要锁权的，外包；简单、快速、来回频繁的，自己干。

下一篇 24「插件（Plugins）」——到这儿你手里的「配件」越来越多了：CLAUDE.md、斜杠命令、Skill、现在又加了 Subagent。一个个单独配，是不是有点碎？下一篇就教你把这些打包成一个插件，一键安装、一键分享，甚至直接从「插件市场」拿现成的来用。想想看：别人调教好的子代理和命令，能不能一键搬到你这儿？

24 · 插件（Plugins）：把一堆零碎配置一键打包

兄弟们，今天聊怎么把一堆零碎配置一键打包。说起来，你有没有遇到过这种场景：你辛苦给团队配好了一套「subagent + hook + MCP」，然后某天来了个新同事，你给他讲了半小时——「这个文件放 agents/，那段 hook 加到 settings.json 里，对了还有 .mcp.json 别忘了」——讲完发现他还是漏了一处，跑起来跟你的不一样。这不是谁的问题，散件管理本来就是这样：配置越分散，口头交代越容易漏。

你回头看看前面几篇攒下的家当：第 18 篇写了 CLAUDE.md，第 22 篇配了 MCP server，第 23 篇造了 subagent，中间还穿插着 skill、hook。每一样单独看都好用，但它们全是散的——subagent 放 agents/、hook 写在 settings.json、MCP 配在 .mcp.json，分散在好几个文件里。

问题来了：你在 A 项目辛辛苦苦配好的这一套，换到 B 项目想复用，得一个文件一个文件挨个抄过去。团队里新同事想要你这套配置，你得把目录结构口头讲一遍，还容易漏。散件管理，就是又累又容易出错。

说白了，插件就是 Claude Code 给这个问题的官方答案：把 commands、subagents、skills、hooks、MCP server 这些散件，打成一个能整体分发、能一键启停的包。这一篇就把「插件是啥、怎么从市场拿现成的、怎么管」一次讲透。

看完这一篇，你会拿到：

• 插件到底打包了哪些东西，以及它和「散装配置」该怎么选，一张表说清
• 「插件市场（marketplace）」两步走的逻辑：先加市场、再装插件，命令照抄就能用
• 从官方演示市场亲手装一个插件、跑通它带来的命令，全程给预期输出
• 插件目录长什么样（plugin.json + 各组件文件夹），自己想打包时照着摆
• 装第三方插件前必须过的「信任关」，别把陌生插件当无害软件

01 先搞懂：插件到底是个什么东西

先给结论：插件就是一个「自包含的文件夹」，把你前面学的那些扩展（skill、subagent、hook、命令、MCP server）打包在一起，能当成一个整体来装、来停、来分发。

为什么需要它？因为散装配置有三个绕不开的痛点：跨项目复用麻烦、团队共享靠人肉、版本更新没法追。你在一个项目里配好的 subagent 加 hook，想搬到另一个项目，只能手动复制粘贴；想分给同事，得把每个文件都说清放哪儿。插件就是把这一整套「装进一个盒子」，盒子整个搬走、整个递给别人就行。

类比：浏览器扩展商店。 你想给 Chrome 加广告拦截、加翻译、加截图——不用自己写代码、改配置，去扩展商店点一下「安装」，一整套功能就进来了，不想要了点「移除」就干净卸载。Claude Code 的插件就是这套思路：逛市场、一键装一整套功能，不用自己一件件手动配；它把过去散在好几个文件里的扩展，变成商店里一个能直接「装/卸」的条目。

官方文档把「插件」和「散装配置」的取舍讲得很清楚，我替你浓缩成一张表：

这张表的判断逻辑就一句话：自己一个项目随手用，散装就够了；要给别人用、要跨项目搬、要能更新，才上插件。官方也建议「先用 .claude/ 散装快速迭代，准备好共享了再转成插件」——别一上来就为一个一次性配置造插件，那是过度工程。

这里有个新手最容易迷糊的点，必须先说清：插件里的 skill 名字永远带「命名空间」。你在一个叫 my-plugin 的插件里写了个 hello skill，调用时不是 /hello，而是 /my-plugin:hello。

💡 一句话总结：插件就是把 skill、subagent、hook、命令、MCP server 打成一个能整体装卸的盒子；自用散装就行，要共享、要复用、要更新才打包成插件。

02 为什么打成一个包，比散着放强

上一节讲了「是什么」，这一节补一刀「凭什么值得」——因为光知道概念，你可能还是觉得「我手动复制几个文件也不费事」。

真正的差距在三个地方，结合具体场景讲，你就懂了。

第一，跨项目复用。 设想你常备一套「git 提交工作流」的配置——一个生成规范提交信息的 skill、一个提交前自动跑 lint 的 hook。早期这套是散装的，换一个新项目就得把 skills/ 和 settings.json 里那段挨个抄。一旦抄漏了 hook 那段，新项目里提交前没跑 lint，就可能混进去一个格式错误。打成插件之后，新项目里一句 /plugin install 就齐活了，再不会漏。

第二，团队共享。 散装配置分享给同事，基本靠「你把这个文件夹拷过去，放到 .claude/agents/ 下，然后那个 hook 记得加到 settings 里」——一通口头交代，对方十有八九配错。插件不一样：你把它发到一个市场（哪怕是公司内部的私有仓库），同事一条命令装好，配置完全一致，不存在「我这能跑你那不行」。

第三，版本更新。 这是散装最致命的短板。散装配置改了，用过的人根本不知道，只能你挨个通知。插件可以带版本号，你发新版，用户更新时就自动拿到最新的；官方还专门做了「自动更新」——官方市场默认开着，第三方市场默认关着（这设计很合理，自己人的更新可以自动收，外人的得你主动同意）。

类比：手机 App 和它在应用商店的关系。 你装了个 App，它出新版本，应用商店推给你「有更新」，你点一下就升级了，不用自己重新下安装包。插件之于市场，就是 App 之于应用商店——装是一键装，更新是顺着市场流下来的，不用你手动搬运。

对照一下散装和插件在这三件事上的差距：

说句实话，单人单项目，插件的好处你感受不深；一旦人多了、项目多了，散装就开始拖后腿。我自己也是带团队之后才彻底转向插件的——之前给新人配环境，得拉着人对着屏幕一个文件一个文件讲「这个放 agents/、那个 hook 加到 settings 里」，一上午能折腾掉小半天，还总有人漏一处；打成插件挂到内部仓库之后，新人就一条命令装完，配置跟我这边一模一样，再没出过「我这能跑你那不行」。

💡 一句话总结：插件的真正价值在「规模」——跨项目复用、团队共享、版本更新这三件事，散装全靠人肉，插件全是一条命令；人和项目越多，这差距越大。

03 插件市场：先加「商店」，再装「应用」

知道了插件是什么，下一个问题是：别人造好的插件，我从哪儿拿？ 答案是「插件市场（marketplace）」。

这里有个全篇最关键、新手最容易卡壳的认知：用市场是「两步」，不是「一步」。

• 第一步：加市场。 把一个市场「注册」给 Claude Code，让它能浏览这个市场里有哪些插件。注意，这一步一个插件都没装，只是让你看得到货架。
• 第二步：装插件。 在货架上挑你要的，单独安装。

类比：给手机装一个新的「应用商店」。 你手机上除了自带商店，还可以装第三方应用商店——但「装好这个商店」不等于「装好了里面的 App」。商店只是让你能进去逛、能看到它的全部收藏，具体要哪个 App，还得你自己点进去单独下载。插件市场就是这么个「应用商店」：加进来是让你能逛，装哪个插件是另一码事。

想清楚这个「两步」，下面的命令就全顺了。先看加市场——官方给了好几种来源，最常用的是从 GitHub 加：

/plugin marketplace add owner/repo

把 owner/repo 换成实际的 GitHub 仓库名就行（比如官方演示市场是 anthropics/claude-code）。除了 GitHub，市场还能从 Git URL（GitLab、Bitbucket、自托管都行）、本地路径、远程 URL 加，写法官方文档都列了，新手记住 GitHub 这种最常用的即可。

加完市场，装插件用这条：

/plugin install plugin-name@marketplace-name

@ 后面跟的是市场名，意思是「从这个市场装这个插件」。比如从官方市场装 GitHub 集成：

/plugin install github@claude-plugins-official

这里要单独点名官方自带的那个市场：claude-plugins-official。它不用你手动加——你一启动 Claude Code 它就在了，里面是 Anthropic 精选的一批插件（GitHub、GitLab、Slack、Figma、Sentry 这些外部集成，还有代码智能的 LSP 插件、安全审查插件等）。所以你想装官方插件，跳过「加市场」那步，直接 install 就行。

💡 一句话总结：用市场永远是「先加市场、再装插件」两步——/plugin marketplace add 加货架、/plugin install xxx@市场名 下单；唯独官方市场 claude-plugins-official 自带，开箱就能直接装。

04 三个市场，分别是干嘛的

上一节出现了好几个市场名，新手容易搞混。这一节把官方维护的三个市场摆清楚，你以后看到名字就知道是谁。

类比：同一个城市里三家不同定位的商场。 一家是品牌直营旗舰店（货都是官方精挑的），一家是开放入驻的大卖场（第三方来摆摊，但进场前过了安检），还有一家是临时的样板展厅（专门摆样品给你看效果）。Claude Code 这三个官方市场正好对上：

几个要点说清楚：

官方市场最稳但不开放申请。 Anthropic 自己决定收哪些插件，里面的东西经过精选，踩坑概率最低。你日常想要的大路货——GitHub 集成、各语言的 LSP、安全审查——基本都在这儿。

社区市场是开放的，但有门槛。 第三方插件提交后，要过 Anthropic 的自动验证和安全筛选才进得来，而且每个插件都被「固定到某次具体提交」——意思是你装的就是审查时那个版本，作者不能偷偷换内容。它要手动加，加完用 claude-community 这个名字装。

演示市场是用来学的。 它放的是「展示插件系统能做什么」的样板，下一节的动手实验就拿它练手。它也要手动加。

建议的取用顺序：官方市场优先，官方没有的再去社区市场找，找到了先看主页和它要的权限再装。演示市场一般只在教学或试水时用——它的定位就是样板，不是给你天天用的生产插件。

💡 一句话总结：官方市场自带最稳、社区市场要手动加但过了安检、演示市场是学习样板；日常先翻官方，缺货再去社区，演示拿来练手。

05 装一个插件，到底装进来了什么

/plugin install 一敲，到底有什么东西进了你的环境？这一节讲清楚，免得你装完一脸懵「然后呢，我怎么用它」。

一个插件可能带这几类组件进来，每一类的「触发方式」不一样，这是关键：

看出来没？有的是「你主动喊」（skill、命令），有的是「它自动干」（hook、MCP、LSP）。所以装完一个插件，你得知道它到底带了哪几类东西，才知道怎么用它。

好消息是，新版 Claude Code 在你装之前就把这些列给你看。在 /plugin 界面里点开一个插件的详情，会有个「将安装」区块，列出这个插件带的命令、agents、skills、hooks、MCP 和 LSP server；还会给一个「上下文成本」估算——告诉你这插件每轮大概往你的上下文窗口塞多少 token。

这个「上下文成本」得多说一句，它很重要。回想第 19 篇讲的上下文管理：插件带的每个组件，都会占掉你工作台的一块地方。装太多插件，等于还没开始干活，上下文就被各种 skill 说明、MCP 工具定义占掉一大截。装插件前一定要看这个估算，几百 token 的无所谓，上千的得掂量「我是不是真用得上」。装一堆用不上的插件白占上下文，是新手常犯的浪费。

还有个细节：装完插件，记得运行 /reload-plugins 让它生效，不用重启 Claude Code。会话中途装、停、启用插件，都靠这条命令刷新：

/reload-plugins

跑完它会告诉你当前加载了几个插件、几个 skill、几个 agent、几个 hook、几个插件 MCP server 和 LSP server。

💡 一句话总结：插件带进来的组件分「你主动喊」（skill/命令）和「它自动干」（hook/MCP/LSP）两类；装前在详情里看「将安装」清单和上下文成本，装后 /reload-plugins 生效。

这张图把本篇的两条主线画在一起：左边是「加市场 → 装插件」的两步流程，右边是一个插件盒子打包的五类组件（skill、subagent、hook、MCP server、LSP server），以及它们装进来后分别是「你主动喊」还是「它自动干」。

06 动手：加一个市场、装一个插件、用起来

光看不练假把式。下面带你从官方演示市场加市场、装一个真插件、跑通它带来的命令，全程不依赖任何复杂环境，跟着抄就行。我们装的是官方文档点名的 commit-commands——一个给 git 工作流加 skill 的插件。

第一步：启动 Claude Code，加演示市场

随便进一个目录启动 Claude Code：

claude

进去后在输入框敲（这是「两步」里的第一步——加市场）：

/plugin marketplace add anthropics/claude-code

预期：Claude Code 下载这个市场的目录，提示市场添加成功。此时你的「货架」上有货了，但还没装任何插件。

第二步：打开插件管理器逛一逛

敲：

/plugin

预期：弹出一个带四个标签页的界面——发现 / 已安装 / 市场 / 错误，用 Tab 键来回切（Shift+Tab 往回切）。切到「发现」标签，能看到你刚加的演示市场里那些样板插件。看到 commit-commands 在列表里 = 市场加对了。

第三步：装 commit-commands 插件

你可以在界面里点它选安装范围，也可以直接命令行装（这是「两步」里的第二步）：

/plugin install commit-commands@claude-code-plugins

注意 @ 后面是 claude-code-plugins——这是这个演示市场的内部名字（不是你加市场时写的 anthropics/claude-code，那是仓库地址）。装的时候它会让你选范围：

• 用户范围（默认）：所有项目里你自己都能用
• 项目范围：装进 .claude/settings.json，这个仓库的所有协作者都能用
• 本地范围：只在这个仓库、只有你自己能用

先选默认的「用户范围」即可。

预期：终端提示插件安装成功，可能还会列出它附带自动装了哪些依赖。

第四步：让插件生效，看它带来的命令

/reload-plugins

预期：Claude Code 重新加载，输出当前加载的插件、skill、agent、hook 以及插件 MCP server 和 LSP server 数量。因为 commit-commands 的 skill 带命名空间，它提供的是像 /commit-commands:commit 这样的命令。

第五步：用起来——亲眼看插件的 skill 跑活

先在当前目录随便改个文件制造一点改动（比如新建一个文本文件），然后敲：

/commit-commands:commit

预期：这个 skill 会帮你暂存改动、生成一条提交信息、创建提交。看到它走完这套 git 提交流程，说明插件不光装上了，它带的 skill 真的能用了——这就是「装一个插件、白捡一套现成工作流」的完整体感。

⚠️ 如果第五步敲 /commit-commands:commit 提示找不到命令，先确认你第四步跑了 /reload-plugins；还不行就 /plugin 进「错误」标签看加载报错。

跑通这五步，你就把「加市场 → 装插件 → 生效 → 用起来」这条完整链路亲手验证了一遍。以后装任何插件，本质都是这套流程。

💡 一句话总结：加市场（marketplace add）→ 装插件（install）→ 生效（/reload-plugins）→ 用命名空间命令——亲手把 commit-commands 跑通一遍，比记十条命令都管用。

07 想自己打包？先认识插件的目录长相

前面全是「用别人的插件」，但你迟早会想「我能不能把自己那套配置也打成插件」。这一节不教你从零造（那是单独一篇的量），只带你认住插件的目录长什么样，做到看得懂、心里有数。

一个插件的核心就两部分：一个「身份证」文件 + 各组件的文件夹。

身份证就是 .claude-plugin/plugin.json，它声明这个插件的名字、描述、版本：

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0"
}

其中 name 最关键——它就是 skill 的命名空间前缀。这个插件里的 skill 会变成 /my-first-plugin:xxx。version 是可选的，但设了版本号用户才会在你更新时收到更新，所以发布时记得每次发新版就提一下版本号。

各组件的文件夹就摆在插件根目录下，按类型分门别类。官方的目录约定我整理成一张表，照着摆就对：

整个插件摆起来大概长这样：

my-first-plugin/
├── .claude-plugin/
│   └── plugin.json        ← 身份证，只有它放这儿
├── skills/
│   └── hello/
│       └── SKILL.md
├── agents/
│   └── reviewer.md
└── hooks/
    └── hooks.json

这里有个官方反复强调、新手必踩的坑，我替你画重点：

常见错误：不要将 commands/、agents/、skills/ 或 hooks/ 放在 .claude-plugin/ 目录内。只有 plugin.json 应该在 .claude-plugin/ 内。所有其他目录必须在插件根级别。

说白了：.claude-plugin/ 这个文件夹里只准放 plugin.json 一个东西，其他组件文件夹全部摆在插件根目录下，跟 .claude-plugin/ 平级。这个坑我第一次打包就踩了——图省事顺手把 skills/ 也塞进了 .claude-plugin/，结果插件明明加载成功、/reload-plugins 也没报错，可那个 skill 死活不出现。我对着 plugin.json 检查了半天名字、版本、命名空间，全对，最后才反应过来是目录摆错位置了。挪出来跟 plugin.json 平级，立马就好。

你可能注意到，这套目录结构跟第 13 篇讲的 .claude/ 项目结构、第 23 篇的 agents/、第 22 篇的 .mcp.json 几乎一模一样。这不是巧合——插件本质就是「把你散在 .claude/ 各处的那些配置，按同样的格式收进一个独立文件夹」。所以官方才说散装配置能「转换成插件」，因为格式是相通的，搬过去就行。

想真正动手测自己打的包，官方给了个不用装市场的快捷办法——启动时用 --plugin-dir 直接加载本地插件目录：

claude --plugin-dir ./my-first-plugin

这个标志专门给开发测试用，改完插件跑 /reload-plugins 就能看到效果，不用走「发市场再安装」那一整套。

💡 一句话总结：插件 = .claude-plugin/plugin.json（身份证，name 定命名空间）+ 根目录下的各组件文件夹；记死那条铁律——.claude-plugin/ 里只放 plugin.json，别的文件夹全摆根目录。

08 装第三方插件，先过「信任关」

这是全篇最该慎重的一节，也是新手最容易掉以轻心的地方：插件不是无害的小工具，它能用你的权限在你机器上执行任意代码。

回想第 21 篇讲的安全边界——那一篇的判断力，到了插件这儿一样适用，甚至更要紧。官方把话说得很重：

插件和市场是高度受信任的组件，可以使用您的用户权限在您的机器上执行任意代码。仅从您信任的来源安装插件和添加市场。

这是什么意思？一个插件里可能带 hook（自动跑脚本）、带 MCP server（自动启动的程序）、带 bin/ 里的可执行文件。你装它、启用它，这些东西就在你的权限下跑起来了——它能读你的文件、能联网、能执行命令，和你自己敲命令的权限一样大。装一个来路不明的插件，约等于把陌生人的脚本直接在你电脑上运行。

类比：从陌生网站下载一个 .exe 双击运行。 你不会随便从一个没听说过的网站下个可执行文件就双击吧？因为它一旦跑起来，能干的事跟你本人一样多。装第三方插件就是这个性质——来源可信不可信，是装之前必须先回答的问题，不能图省事直接装。

所以这里给你三条「装第三方插件前」的自检，值得当成硬规矩：

几个能让你稍微安心的官方设计：社区市场的插件过了自动验证和安全筛选，且固定到具体提交（作者没法偷换内容）；官方市场是 Anthropic 精选，最省心。但这些都不能替代你自己的判断——核心还是那句「只从你信任的来源装」。

一套稳妥的实践：官方市场的插件直接装；社区市场的，先去它主页扫一眼是谁、干什么的、要哪些权限，再决定；陌生来源的私人插件，除非你能看懂它的代码，否则一律不碰。说句实话，插件这东西方便归方便，但「方便」和「安全」从来是要你自己拿捏的——别把一键安装的顺滑，当成了它无害的证据。

💡 一句话总结：插件能用你的权限跑任意代码，装第三方的等于在你机器上运行陌生人的脚本；装前三查——来源可信吗、带了啥、范围给到哪，官方市场最稳，陌生来源宁可不装。

09 小结

这一篇我们把 Claude Code 的「插件」从概念捋到动手——它本质就是把你前面学的那些散件，打成一个能整体装卸、能分发、能更新的盒子。

把核心要点串起来回顾：

你现在应该能： 看懂插件和散装配置该怎么选、用「加市场 → 装插件 → /reload-plugins」三步从市场拿到现成功能、看懂插件详情里的「将安装」清单和上下文成本、认住插件的目录长相，并且清楚装第三方插件前必须先过信任关。这套能力让你不用什么都自己从零配——市场上现成的全家桶，拿来即用。

从第 18 篇到这一篇，你已经把 Claude Code 的「扩展工具箱」配齐了：CLAUDE.md、MCP、subagent、skill、hook，最后用插件把它们打包统管。工具，到这儿算是装齐了。

下一篇 25「记忆系统（memory）」——工具装齐了，但你有没有发现一个别扭的地方：每开一个新会话，Claude 又是一张白纸，你上次告诉它的偏好、这个项目的关键事实，它转头就忘。下一篇就聊怎么让 Claude 跨会话「记住」你——记住你爱用的技术栈、记住项目的硬规矩，不用每次从头交代。想想看：如果它能像个共事久了的老搭档一样，开口就知道你的习惯，是不是省事多了？

25 · 记忆系统（memory）：让它跨会话记住你

先说个新手特别容易踩的坑。

刚摸到「能让 Claude 记东西」这功能时，很容易跟捡到宝似的，啥都往里塞：今天调通了一个端口号塞进去、改了个临时变量名塞进去、连「这次先用 8081 别用 8080」这种一次性的破事也塞。背后的逻辑往往是「记得越多越聪明」。

结果呢？两周后再开项目，它张口就跟你提那个早就废弃的 8081 端口，还有几条连你自己都忘了为啥写的「偏好」。它记了一脑子没用的，真正该记的反倒被淹了。

这时候才会搞明白：记忆这东西，不是塞得越多越好，是「该记的记准、不该记的别碰」。 记错了比不记还坑——它会拿着过时的信息一本正经地误导你。

前面 [18 CLAUDE.md 使用指南] 我们专门讲过 CLAUDE.md 怎么写，[19 上下文管理] 也反复提到「自动记忆会占上下文」。但这两块到底怎么咬合成一套完整的「记忆系统」、那本 Claude 自己写的笔记又是怎么运转的，一直没讲透。今天补上。

看完这一篇，你会拿到：

• Claude Code 的记忆到底分哪两套：你写的 CLAUDE.md vs 它自己写的「自动记忆」，谁管啥一张表看明白
• 「自动记忆」存在哪个文件、怎么被加载进上下文、怎么用 /memory 审计和删改
• 怎么让它记一条、记完落到哪、下次怎么自动生效，一步步带你跑通
• 一张「该记 vs 不该记」清单，帮你避开「啥都塞」那个坑
• # 这个老快捷键现在还能不能用，官方现在的正确做法是什么

01 先分清：记忆其实是两套，不是一套

先给结论：Claude Code 的「记忆」是两套并行的系统，一套你写、一套它写，各管各的。 很多人一提「记忆」只想到 CLAUDE.md，其实那只是一半。

类比：贴在显示器边上的便利贴。 你桌上常有两种纸。一种是你正经打印出来、用图钉钉在隔板上的「工作守则」——项目规矩、提交流程，写得规规整整，谁来都照着办，这是 CLAUDE.md。另一种是你随手撕一张便利贴，写句「上次那个 bug 是缓存没清」往显示器边一贴，下次扫一眼就想起来——这种它自己随手记的小条，就是「自动记忆（auto-memory）」。两种纸都在你眼前，但一种是「我定的规矩」，一种是「我顺手记的心得」。

官方把这两套的分工讲得很清楚，整理成一张对照表——这是本篇最该先记住的一张：

看出关键区别没？CLAUDE.md 是「你想让它怎么干」，自动记忆是「它自己摸索出来的怎么干」。 你纠正它「这个项目跑测试得先起本地 Redis」，它下次就记得了——这条不用你手动写进任何文件，它自己存。

还有一条官方反复强调、你必须先吃透的认知：

Claude 将它们视为上下文，而不是强制配置。要阻止某个操作，无论 Claude 决定什么，请改用 PreToolUse hook。

什么意思？记忆（不管哪一套）都只是「影响它想干啥」的软提示，不是「锁死它能干啥」的硬约束。 这跟 [20 权限配置] 那篇的结论一脉相承——真要拦死某个操作，得靠权限规则或 hook，光在记忆里写一句「不要 push」是拦不住的。记忆负责「让它更懂你」，不负责「替你把关」。

💡 一句话总结：记忆分两套——CLAUDE.md 你手写规矩、自动记忆它自己记心得；两套都只是软提示，想真正拦死操作得靠权限或 hook，不是写进记忆就万事大吉。

这张图把两条记忆通路并排画出来：左边是你手写、全量加载进上下文的 CLAUDE.md（项目守则）；右边是 Claude 工作时自己往 MEMORY.md 里记、下次会话自动读回前 200 行的自动记忆（私人笔记）。两条线最后都汇进「新会话的上下文窗口」，让它一开工就「记得你」。

02 CLAUDE.md 在记忆体系里的位置

CLAUDE.md 的写法 [18] 已经讲细了，这里只补一句它在「记忆系统」里扮演的角色——它是那张钉死的、人人都得看的「工作守则」。

类比：还是显示器旁那两种纸，CLAUDE.md 是钉死的那张。 它不是随手撕的便利贴，是你认真打印、图钉钉牢的正式守则。所以它有几个特点和自动记忆完全不同：你写的、进版本控制全队共享、每次会话全量加载、内容是「规则」不是「心得」。

官方给 CLAUDE.md 划了清晰的分层，按加载顺序（从最广到最具体）是这样：

这里有个跟自动记忆的关键差别，新手最该记牢：

CLAUDE.md 无论多长都全量加载，自动记忆有上限。 官方原话——「CLAUDE.md 文件无论长度如何都完整加载」。所以 [18] 才反复劝你把它压在 200 行以内：不是加载不进去，是写越长越占上下文、它遵守得反而越差。自动记忆则相反，它有硬上限（下一节细说），超了的部分根本不加载。

实操里分工可以很清楚：「这是你定的死规矩」就写 CLAUDE.md，「这是让它自己摸索积累的」就交给自动记忆。 比如「依赖只用 pnpm」这种铁律手写进 CLAUDE.md；而「这个项目的测试得起 Redis」这种它能自己发现的，不必手写，纠正它一次让它自己记。

💡 一句话总结：CLAUDE.md 是记忆体系里那张「钉死的正式守则」——你写、全队共享、全量加载、装的是规则；和「它自己随手记心得」的自动记忆，定位完全不同。

03 自动记忆：它自己写的那本笔记

重点来了，也是 [18] 留给本篇的正题——自动记忆（auto-memory），Claude 工作时给自己记的那本笔记。

ℹ️ 自动记忆需要 Claude Code v2.1.59 或更高版本，默认是开着的。敲 claude --version 看一眼你的版本；太老就升一下（升级方法见 [02 安装]）。

类比：干活久了的老搭档。 一个跟你配合了一段时间的搭档，有些事你压根不用反复交代——他自己会在脑子里记下来：「这项目构建得跑 make build 不是 npm build」「上次那个偶发 bug 是时区没设对」。下次遇到类似的，他自己就想起来了。你不用交代，他边干边积累——自动记忆就是 Claude 的这种「主动学习」能力。

它具体记些什么？官方给的清单：构建命令、调试见解、架构笔记、代码样式偏好、工作流习惯。 注意一个关键设计——它不是每次会话都往里记，而是「根据这条信息未来对话还用不用得上，来决定值不值得记」。一次性的破事它一般不会记（这点正好治了「啥都塞」的病）。

那它怎么实际写进去的？两种触发方式：

第一种，你直接让它记。 在对话里说一句「以后这个项目都用 pnpm，别用 npm」或者「记住 API 测试要本地起 Redis」，它就把这条存进自动记忆。官方原文：

当你要求 Claude 记住某些内容时，如「总是使用 pnpm，而不是 npm」或「记住 API 测试需要本地 Redis 实例」，Claude 将其保存到自动记忆。

第二种，它从你的纠正里自己学。 你不用明说「记住」，只要你纠正了它一次——比如它用 npm test 你说「这项目是 pnpm test」——它判断这条以后还用得上，就自己记下来了。这是自动记忆最香的地方：你正常干活、正常纠正，它在背后默默积累，零额外动作。

你怎么知道它正在记？看界面提示。 官方说，当你看到 Claude Code 界面里冒出「Writing memory」或「Recalled memory」，就是它在往那本笔记里写、或者从里面读了。

💡 一句话总结：自动记忆是 Claude 自己写的便利贴——你让它记、或它从你的纠正里自学，只记「以后还用得上」的；看到界面提示「Writing/Recalled memory」就是它在记或在翻笔记。

04 它存在哪、又怎么被加载进上下文

这节解决两个最实际的问题：这本笔记到底存哪个文件？它又是怎么塞进上下文让 Claude「想起来」的？ 后半截正好呼应 [19] 讲的上下文管理。

存放位置，官方定死了——每个项目一个独立的记忆目录：

~/.claude/projects/<project>/memory/
├── MEMORY.md          # 简洁索引，每次会话都加载
├── debugging.md       # 调试相关的详细笔记
├── api-conventions.md # API 设计决策
└── ...                # Claude 自己创建的其他主题文件

几个要点拆开说：

MEMORY.md 是入口和索引。 它像便利贴里的「目录页」，Claude 用它跟踪「我都记了些啥」。详细内容它会拆到 debugging.md、api-conventions.md 这种主题文件里，免得 MEMORY.md 越滚越长。

<project> 这个名字按 git 仓库算。 所以——同一个仓库的所有 worktree 和子目录，共用这一份自动记忆。这点跟 CLAUDE.md 不一样（CLAUDE.md 是按目录树拼接的）。

它是机器本地的，不跨设备同步。 你这台电脑记的，换台电脑不会有。也别指望它进 git——它就在你 ~/.claude 下待着。

接下来是最该理解的机制——它怎么被加载进上下文，官方写得很死：

MEMORY.md 的前 200 行或前 25KB（以先到者为准）在每次对话开始时加载。超过该阈值的内容在会话开始时不加载。

翻译成人话，三层意思：

1. 每次新会话，自动读回 MEMORY.md 的前 200 行（或 25KB，哪个先到算哪个）。这就是它「跨会话还记得」的原理——上次记的，这次开局自动进上下文。
2. 超过 200 行 / 25KB 的部分，开局不加载。 所以 Claude 会主动把 MEMORY.md 保持精简，详细的甩进主题文件。
3. 主题文件（debugging.md 这些）开局也不加载，它需要时用文件工具按需读——跟 [18] 讲的「子目录 CLAUDE.md 按需加载」一个道理。

把 CLAUDE.md 和自动记忆的加载规则放一起对比，差别一目了然：

理解这个上限，你就懂为啥它不会被记忆「撑爆」上下文——自动记忆天生带了个 200 行的闸，而 CLAUDE.md 那个闸得你自己把。

💡 一句话总结：自动记忆存在 ~/.claude/projects/<project>/memory/MEMORY.md，按 git 仓库分、机器本地、worktree 共享；每次开局只读回前 200 行 / 25KB，超出的拆进主题文件按需读——所以它有天生的上限，不会撑爆上下文。

05 /memory：审计、编辑、开关，一个命令全包

自动记忆最让人不放心的一点是——它自己记的，万一记错了、记了过时的怎么办？（开头那个 8081 端口的坑就是这么来的。）官方给的答案是一个命令：/memory。

类比：随时能掀开看的那叠便利贴。 它自己记的笔记不是黑箱，你想看随时掀开、想撕随时撕。/memory 就是「掀开看」这个动作。

在会话里敲 /memory，它干三件事：

1. 列出当前会话加载的所有记忆文件——包括 CLAUDE.md、CLAUDE.local.md、规则文件，以及自动记忆。怀疑它「记错了什么」，先用这个查到底加载了啥。
2. 提供打开自动记忆文件夹的入口——点一下就能进 memory/ 目录，那些文件全是纯 markdown，你随时能读、能改、能删。记岔了的那条，直接删掉就行。
3. 切换自动记忆的开关——不想让它自动记了，这里能关。

除了在会话里用 /memory，还有两个「钉死开关」的官方办法：

在 settings.json 里关掉自动记忆（项目级，进配置文件长期生效）：

{
  "autoMemoryEnabled": false
}

或者用环境变量临时关掉（设 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 即可）。

值得养成一个习惯：每隔一阵子，敲一次 /memory 掀开自己项目那本笔记扫一遍。 经常能清出几条早该删的——一个换掉的端口、一个废弃的接口约定、一条自己都看不懂的「偏好」。两分钟的事，省得它哪天拿着过时信息误导你。 这正是从 8081 那个坑里能学到的教训。

💡 一句话总结：/memory 一个命令把记忆系统全摊开——列出加载了哪些文件、点开自动记忆文件夹随时读改删、还能开关自动记忆；定期掀开扫一遍、清掉过时的那几条，是治「它记错」的最简单办法。

06 该记什么、不该记什么：别重蹈「啥都塞」的覆辙

机制讲完，落到最实在的判断——啥值得让它记，啥碰都别碰。 这节全是用真金白银的坑换来的经验。

好消息是，自动记忆默认就比较克制（只记「以后用得上」的）。但你主动让它记的时候，得自己把关——你说「记住 xxx」，它一般就真记了，把不把关全看你。

直接上对照表，左边是塞了会后悔的，右边是真该记的：

三条判断原则，记住这三个词就够：

一是「会不会变」。 一次性的、马上要改的、「先这么着」的，全别记——它们的保质期比你这次会话还短，记下来就是给未来挖坑。那个 8081 就是典型，调通的当下有用，过两天就是误导。

二是「能不能复用」。 只有这次用得上的（「我现在在调 X」），别记；下次、下下次还用得上的（构建命令、架构事实、踩过的坑），才值得记。

三是「敏不敏感」。 这条是红线——密码、token、API key 这类绝对不能进任何记忆文件。自动记忆是纯 markdown 明文存在你硬盘上的，把密钥记进去等于明文落盘。这跟全局安全约束一致：敏感信息不进代码、不进 commit、不进日志，自然也不进记忆。

让它记之前，脑子里就过这三关：会变吗？以后还用吗？敏感吗？ 三关都过了才让它记。这么把关之后，它那本笔记会干净得多，也不会再拿过时信息误导你。

💡 一句话总结：记之前过三关——会变的别记、只用一次的别记、敏感的绝对别记；只记那些「稳定、复用、项目特有」的事实和心得，别啥都往里塞。

07 # 这个老快捷键，现在还能用吗

ℹ️ # 是早期老做法，新版本已不用这套交互。 不少老教程和视频还在教「用 # 开头快速追加记忆」，忘掉它就好。现在的正确入口：说「记住 xxx」存进自动记忆、说「加进 CLAUDE.md」存进 git 守则、查改删用 /memory。

新手最容易踩的一个坑：光说「记住 xxx」，它默认存进自动记忆（机器本地），不等于进了 CLAUDE.md（进 git、全队共享）。要全队都能看到某条规矩，必须明说「加进 CLAUDE.md」。一句话之差，共享范围天差地别。

💡 一句话总结：# 过时别用；「记住 xxx」进自动记忆、「加进 CLAUDE.md」进 git——两者不是一回事，想共享得说全。

08 动手：记一条、看它落哪、下次自动生效

光看不练不算会。下面带你完整走一遍：让它记一条 → 确认落到了自动记忆文件 → 验证下次会话自动想起。 全程最小示例，不依赖任何复杂环境。

ℹ️ 前提：claude --version ≥ v2.1.59，且自动记忆没被关（默认开着）。

第一步：建个玩具项目，启动 Claude（Mac / Linux）

mkdir memory-demo
cd memory-demo
claude

预期：进入 Claude Code 会话界面，底部有输入框。

第二步：让它记一条

在输入框里敲（用一条典型的、值得记的「构建命令」）：

记住：这个项目的构建命令是 make build，不是 npm build

预期：Claude 回应说它记下了，并且界面上会闪过一个 「Writing memory」 之类的提示——看到这个提示，就是它正在往那本笔记里写。

第三步：用 /memory 确认它落到了哪个文件

紧接着敲：

/memory

预期：弹出记忆管理界面，列出当前加载的所有记忆文件。你能看到自动记忆的入口，点进去能看到 MEMORY.md，里面有刚才那条 make build 的记录。看到它在文件里 = 这条已经从「对话里说说」变成「落盘的笔记」了。

想从命令行直接确认也行，另开一个终端敲：

cat ~/.claude/projects/*memory-demo*/memory/MEMORY.md

预期：输出里能看到刚记的那条构建命令（具体路径里的 <project> 名按你的目录算，用 * 通配即可）。纯 markdown，一眼能读。

第四步：验证下次会话自动生效

这步是关键——记忆的意义就在「跨会话」。退出当前会话：

/exit

然后重新启动，再问它一个会用到那条记忆的问题：

claude

进去后敲：

这个项目怎么构建？

预期：它会直接告诉你用 make build（而不是瞎猜 npm build）——而且你可能看到 「Recalled memory」 的提示，表示它从笔记里读回了上次记的内容。它在全新会话里答对了 = 跨会话记忆完整跑通，恭喜！

第五步（可选）：清掉这条，验证删除也生效

敲 /memory，进自动记忆文件夹，把那条 make build 删掉存盘。下次再问「怎么构建」，它就不会再笃定地报 make build 了——记错的那条，删了就干净，这正是 /memory 给你的「掀开撕掉」的权力。

跑通这五步，你就把「记一条 → 落盘 → 跨会话自动想起 → 随时审计删改」整条链路亲手验证了一遍。以后所有记忆相关的玩法，本质都在这套机制上。

💡 一句话总结：让它「记住 xxx」→ 看「Writing memory」提示 → /memory 或 cat 确认落进了 MEMORY.md → 退出重进、它「Recalled memory」自动答对 → 需要时 /memory 删改。亲手跑通这条链路，比记十条概念都管用。

09 小结

这一篇把 Claude Code 的「记忆系统」从头捋清了——它不是一套，是两套并行；不是塞得越多越好，是该记的记准。

把核心要点串起来回顾：

你现在应该能： 分清 CLAUDE.md 和自动记忆各管什么、各存哪、各怎么加载；让 Claude 记一条并确认它落到了哪个文件；用 /memory 把记错、记旧的笔记清掉；以及判断一条信息到底该不该记。说白了——你能让 Claude「记住该记的、忘掉该忘的」，而不是任它攒一脑子没用的把你自己绕进去。

记忆这东西，本质是 Claude 在「被动地记住事实」——你纠正它、它积累。但它能为你做的，远不止记住。

下一篇 26「Agent Skills」——记忆是「被动记住事实」，Skills 则是「主动封装能力」：把一套你反复要它干的活儿，打包成一个它能按需调出的「专项本事」。如果说记忆让它「更懂你」，Skills 就是让它「会的更多」。留个小思考：同样是「让 Claude 提前准备好」，你觉得「记住一条规矩」和「学会一项技能」，该在什么时候各用哪个？