AI 讲明白 · 系列细讲 2 / 3
经验该沉淀到哪
同一条教训,在 Claude Code 里至少能放进六个地方:CLAUDE.md、规则文件、skill、hook、子代理、自动记忆。放对了,下次自动生效;放错了,要么被忽略,要么每轮对话都白白占着上下文。这篇按官方文档把“该放哪、怎么写、怎么修剪”讲清楚。
先记住一条:说一遍不等于记住
在对话里纠正 Claude,只对这一次会话有效。/clear 之后、开新会话之后,它就不记得了。官方文档给的时机很明确:同一个错误犯第二次,或者你在聊天里敲了一句上次会话也敲过的纠正,就该把它写下来。官方
写到哪,取决于两件事:它什么时候需要被看到,以及它是不是必须每次都发生。前者决定上下文成本,后者决定该用“提醒”还是“强制”。
把“绝不能做 X”写进 CLAUDE.md,以为就安全了。官方原话:CLAUDE.md 是作为一条用户消息送进对话的,there's no guarantee of strict compliance
。写在文字里的规则只是请求,hook 才是强制。官方
按“什么时候被看到”分三层
上下文窗口是最稀缺的资源,越满表现越差。所以先看每个位置的加载方式,再决定往哪放。
写进去就一直占着
适合每个会话都要知道的事实和规则。每多一行,每一轮都要多付一次。
碰到相关文件或任务才进来
适合只对一部分代码成立的约定,以及偶尔才用的流程和参考资料。
在对话外面执行
hook 不占上下文,除非它返回输出;子代理有自己独立的上下文,只把摘要带回来。
| 位置 | 什么时候加载 | 加载什么 | 上下文成本 |
|---|---|---|---|
| CLAUDE.md | 会话开始 | 全文 | 每一轮 |
| 输出风格 | 会话开始、切换风格时 | 当前风格的全部指令 | 每一轮 |
| skill | 会话开始 + 用到时 | 开始时只有描述,用到时加载全文 | 低(描述每轮都在) |
| MCP | 会话开始 | 工具名,完整 schema 用到才取 | 工具没用就很低 |
| 子代理 | 被派出时 | 新的独立上下文 | 与主会话隔离 |
| hook | 事件触发时 | 什么都不加载,在外面执行 | 零,除非 hook 返回内容 |
出处官方《Extend Claude Code》的 Context cost by feature 表,按原表翻译。官方
按顺序问七个问题
从上往下问,第一个回答“是”的,就是它该去的地方。顺序有讲究:先排除“必须强制”的,再按加载成本从高到低排。
-
它必须每次都发生,而且不需要 Claude 判断吗?格式化、禁止改某类文件、提交前跑检查、结束时通知你。hook写在
.claude/settings.json,事件触发就执行。 -
它跟“怎么回答”有关,而且你可能想随时关掉吗?回答长度、格式、讲解多少,或者让 Claude 扮演写作助手这类非工程角色。输出风格一次只生效一个,可以切换。
-
它会读大量文件、产生一堆你不会再看的中间输出吗?代码库调查、大范围搜索、逐个文件的审查。子代理
.claude/agents/,只把结论带回主会话。 -
它是多步流程,或者只是偶尔才用到的参考资料吗?发版清单、排障手册、API 风格指南、数据库表说明。skill
.claude/skills/<名字>/SKILL.md,用到才加载全文。 -
它只对某些文件或目录成立吗?前端组件写法、
src/api/的接口约定、测试目录的规范。带 paths 的规则.claude/rules/*.md,碰到匹配的文件才加载。 -
它是这个项目每个会话都要知道的事实或规则吗?构建和测试命令、目录结构、团队约定、“总是做 X”。CLAUDE.md项目根目录,提交进仓库,团队共享。
-
它是你个人的偏好或背景,不是项目规则吗?你的角色、你习惯的做法、你纠正过它的事、外部资料在哪。自动记忆 · 个人 CLAUDE.md说“记住……”让它存进自动记忆,或者写进
~/.claude/CLAUDE.md。
另外两个出口:要跨好几个仓库复用同一套 skill、hook、子代理,就打包成插件;需要连外部系统(数据库、工单、浏览器),用 MCP 接进来,再配一个 skill 写清楚怎么用。官方
说明这个问题顺序是我按官方各页的说法排的,官方没有给出这样一张决策表。推断
官方给的“出现什么信号就加什么”
不用一开始就全配齐。官方建议等信号出现了再加,大多数团队大致按下面的顺序。官方
| 信号 | 加什么 |
|---|---|
| 同一个约定或命令,Claude 错了两次 | 写进 CLAUDE.md |
| 你一直在让它“短一点”“多解释点”“按同一种格式答” | 设一个输出风格 |
| 你总在敲同一段提示词来开始某类任务 | 存成一个你能手动调用的 skill |
| 同一份操作手册或多步流程,第三次往聊天里贴 | 做成 skill |
| 你一直在从 Claude 看不到的浏览器页面里复制数据 | 把那个系统接成 MCP 服务 |
| Claude 读很多文件只为找一个符号在哪定义、在哪用 | 装对应语言的代码智能插件 |
| 一个支线任务的输出淹没了对话,而你以后不会再看 | 交给子代理 |
| 你希望某件事每次都发生,不用开口 | 写一个 hook |
| 第二个仓库需要同一套配置 | 打包成插件 |
官方还补了一句:同样的信号也说明已有的东西该改了。反复出现的错误、反复出现的审查意见,应该去改 CLAUDE.md,而不是在聊天里再纠正一次;一个你总在手动微调的流程,说明那个 skill 需要再修一版。
每个位置的写法要点
下面的数字和行为都取自官方文档,版本号是该行为开始生效的版本。
./CLAUDE.md- 放哪
- 个人全局
~/.claude/CLAUDE.md;项目共享./CLAUDE.md或./.claude/CLAUDE.md;个人本项目./CLAUDE.local.md(加进.gitignore);组织统一下发的放在系统目录。各层内容叠加,不互相覆盖。 - 长度
- 每个文件控制在 200 行以内。越长越占上下文,遵守程度也越差。用
@路径导入能让文件更整齐,但不省上下文,因为被导入的文件也在启动时加载。 - 写法
- 写能核对的话:“用 2 个空格缩进”,不写“代码格式要规范”;“提交前跑
npm test”,不写“记得测试”。按标题和条目分组。 - 该写
- Claude 猜不到的命令、和默认不同的代码风格、测试方法、仓库规矩(分支、PR)、项目特有的架构决定、环境上的坑。
- 别写
- 读代码就能知道的、语言通用约定、详细 API 文档(给链接)、经常变的信息、长篇教程、逐个文件的说明、“写干净的代码”这类空话。
官方给的修剪标准是一个问题:删掉这一行,Claude 会不会犯错?
不会,就删;它不写也做得对,就删掉或改成 hook。某一条总被忽略,可以只给那一行加 IMPORTANT,到处都强调就等于没强调。官方
.claude/rules/- 结构
- 一个主题一个文件,比如
testing.md、api-design.md,子目录会递归读取。 - 加载
- 没有
paths的规则,启动时加载,优先级和.claude/CLAUDE.md相同;带paths的,只在 Claude 处理匹配的文件时才加载。 - 个人级
~/.claude/rules/对这台电脑上的所有项目生效,先于项目规则加载。两边冲突时 Claude 可能听任何一边,要自己保持一致。- 共享
- 支持符号链接。链到工作目录之外的文件,算“外部导入”,每个项目要你批准一次才加载。
---
paths:
- "src/api/**/*.ts"
---
- 新接口要在 openapi.yaml 里同步加上定义
- 错误统一用 ApiError 返回,不直接 throw 字符串
.claude/skills/- 两类
- 参考型:约定、风格指南、领域知识,Claude 边干活边参照。任务型:发版、提交、生成代码这类一步步的动作,通常由你用
/名字触发。 - 描述
- Claude 靠
description判断要不要加载它。描述里要有你平时会说的关键词;描述含糊或互相重叠,它就会加载错,或者漏掉。 - 正文
- 一旦加载,全文会一直留在对话里,每一行都是持续的成本。写“做什么”,少写“为什么”。上下文压缩后,每个 skill 只保留前 5000 token,所有 skill 合计 25000 token。
- 持续生效
- Claude Code 不会在后面的轮次重新读 skill 文件。希望整个任务期间都成立的话,要写成“每次修改后都跑测试”,而不是“跑测试”。
| frontmatter | 你能调用 | Claude 能自己调用 | 描述常驻上下文 |
|---|---|---|---|
| 默认 | 能 | 能 | 是 |
disable-model-invocation: true | 能 | 不能 | 否 |
user-invocable: false | 不能 | 能 | 是 |
有副作用的流程(部署、发消息、提交)一律加 disable-model-invocation: true,你不会希望 Claude 看代码差不多了就自己去部署。只是背景知识、不是一个动作的,加 user-invocable: false。context: fork 让 skill 在子代理里跑。allowed-tools 只在调用它的那一轮免确认,并不限制它能用哪些工具。官方
---
name: release
description: 发布新版本:更新版本号、生成变更记录、打 tag 并推送
disable-model-invocation: true
---
发布 $ARGUMENTS:
1. 跑 npm test,全绿才继续
2. 更新 package.json 的版本号
3. 从上一个 tag 到现在的提交生成 CHANGELOG 条目
4. 提交、打 tag、推送
.claude/settings.json- 本质
- 在固定的生命周期事件上执行你的脚本、HTTP 请求、MCP 工具,或者一段交给模型判断的提示词。事件一到必定触发,结果不靠 Claude 自觉。
- 成本
- 不占上下文,除非 hook 返回内容,比如把 lint 结果回给 Claude。
- 强制力
- PreToolUse hook 返回 deny,即使在 bypassPermissions 模式下也照样拦。权限模式改不掉它。
- 常见用法
- 编辑后自动格式化(PostToolUse),拒绝危险命令或受保护的文件(PreToolUse),测试不过不让结束(Stop),会话结束发通知(SessionEnd / Notification)。
#!/bin/bash
# 已提交的迁移文件不许改:命中就以退出码 2 拒绝,stderr 会作为原因回给 Claude
FILE=$(jq -r '.tool_input.file_path // empty')
case "$FILE" in
*/migrations/*)
if git ls-files --error-unmatch "$FILE" >/dev/null 2>&1; then
echo "migrations/ 下已提交的文件不能改,请新建一个迁移文件。" >&2
exit 2
fi ;;
esac
exit 0
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-migrations.sh" }
]
}
]
}
}
实测把模拟的工具输入用管道喂给这个脚本:改已提交的迁移文件,退出码 2,stderr 输出拒绝原因;改新建、未提交的迁移文件或别的文件,退出码 0。实测
.claude/agents/- 本质
- 一个有独立上下文的工作者。它读几十个文件、跑一堆搜索,主会话只收到它的摘要。
- 启动时带什么
- 它自己的系统提示、
skills字段里列出的 skill 全文、CLAUDE.md 和 git 状态(内置的 Explore、Plan 两种不带),以及派它出去时写的那段说明。主会话的自动记忆不会带过去。 - 能沉淀什么
- “这类活该怎么做”的角色定义:审查者只给只读工具,调查者指定便宜的模型。加
memory字段,它可以有自己的跨会话记忆。
---
name: reviewer
description: 改完代码后审查 diff,只报影响正确性和需求的问题
tools: Read, Grep, Glob, Bash
model: sonnet
---
你是审查者。只看 diff 和任务要求,报告会导致结果错误或不满足需求的问题,
附文件和行号。风格偏好不报。
~/.claude/projects/…/memory/- 谁写
- Claude 自己。你说“记住……”,它就存进来;你说“加到 CLAUDE.md”,它才写 CLAUDE.md。
- 存什么
- 四类:
user(你的角色、偏好)、feedback(你的纠正和认可过的做法)、project(代码和提交历史里看不出来的进展和决定)、reference(外部资料在哪)。读代码就能知道的、CLAUDE.md 已经写了的,它会跳过。 - 加载
- 索引
MEMORY.md每次会话加载前 200 行或前 25KB,以先到者为准;各条记忆的主题文件按需读取。 - 范围
- 只在这台电脑上,按 git 仓库划分,同一仓库的 worktree 共用一份,不跨机器同步。用
/memory查看、编辑、开关。
它适合放“关于你”的东西。团队要共享的项目规则,还是写进 CLAUDE.md,自动记忆别人看不到。官方
同时用好几个 AI 工具时:AGENTS.md
v2.1.277 起,Claude Code 能直接读 AGENTS.md。默认规则是:工作目录及其上级目录里没有 CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md 时,才读 AGENTS.md;有的话只读 CLAUDE.md。你的 ~/.claude/CLAUDE.md 和规则文件不算在内。官方
- 想一份文件给所有工具用:AGENTS.md 写正文,CLAUDE.md 第一行写
@AGENTS.md导入,下面再写 Claude 专属的内容。导入不会让它读两遍。 - 别用文字转发:CLAUDE.md 里写一句“请去读 AGENTS.md”,Claude 只有自己决定打开时才会看到。要么删掉这个 CLAUDE.md,要么换成
@AGENTS.md导入。 - 一个坑:在依赖 AGENTS.md 的项目里,自己加一个
CLAUDE.local.md,会让 Claude 不再读 AGENTS.md。要两个都读,在/config里把 Project instructions 设成claude-md-and-agents-md。
六条常见教训,各自去哪
同一种“被纠正”,落点可以完全不同。推断
每个会话都要知道,又是 Claude 猜不到的。如果它还是偶尔敲 npm install,再加一个 PreToolUse hook 拒绝这条命令。
只在动接口代码时成立。放进 CLAUDE.md 会让每个会话都背着它,用 paths: src/api/** 只在需要时加载。
多步流程、有副作用、一个月用几次。做成 /release,只在你开口时运行。
必须每次成立,所以由 hook 拦截;CLAUDE.md 里用一句话说明为什么、应该怎么做(新建迁移),让它一开始就走对路。
这是你个人的工作方式,不是项目规则。说“记住这一点”,它会存进 feedback 类记忆;想让它在所有项目都生效,写进 ~/.claude/CLAUDE.md。
只在排障时需要,内容又长。做成 user-invocable: false 的参考 skill,描述里写上“线上报错、告警、排查”这些词,让它在相关时自己加载。
沉淀之后:体检和修剪
沉淀得越多,越需要定期清理。两条规则互相矛盾时,官方的说法是 Claude may pick one arbitrarily
,也就是随便挑一条。
| 命令或机制 | 回答什么问题 | 备注 |
|---|---|---|
/context | 这次会话到底加载了哪些 CLAUDE.md 和规则? | 看 Memory files 一栏;子目录的 CLAUDE.md 用到才加载,不会列在这里 |
/doctor prompt-audit | 指令文件里有没有过时的、引用了不存在的文件或命令的、互相矛盾的? | v2.1.283 起。只出报告和修改建议,你同意才改 |
/skill-doctor | 每个 skill 占多少上下文、用过几次?哪些从没被调用过? | v2.1.252 起。先关掉占得多又没用过的 |
/memory | 自动记忆存了什么? | 记忆是纯 Markdown,可以直接改、直接删 |
| InstructionsLoaded hook | 哪个规则文件在什么时候、因为什么被加载了? | 调试带 paths 的规则时很有用 |
- 按信号修,不按日历修:Claude 明明有规则还照犯,多半是文件太长、规则被淹没了,先删再加;Claude 问你的问题 CLAUDE.md 里其实写了,说明那句话有歧义,改写它。官方
- 改完看行为有没有变:官方原话是像对待代码一样对待 CLAUDE.md,
test changes by observing whether Claude's behavior actually shifts
。改了一条规则,拿上次犯错的那个场景再跑一遍。 - 只剩在聊天里纠正过的,等于没沉淀:每次收工前问自己一句,今天有没有哪句纠正是第二次说了。有,就按上面七个问题找它的位置。推断
来源
- 官方 Extend Claude Code(功能选型、上下文成本、信号表)
https://code.claude.com/docs/en/features-overview - 官方 How Claude remembers your project(CLAUDE.md、规则、AGENTS.md、自动记忆)
https://code.claude.com/docs/en/memory - 官方 Extend Claude with skills
https://code.claude.com/docs/en/skills - 官方 Hooks reference、Automate workflows with hooks
https://code.claude.com/docs/en/hooks
https://code.claude.com/docs/en/hooks-guide - 官方 Create custom subagents
https://code.claude.com/docs/en/sub-agents - 官方 Best practices for Claude Code
https://code.claude.com/docs/en/best-practices
整理于 2026 年 10 月 8 日,对照的是 Claude Code v2.1.293 当时的官方文档。版本号、数字限制以后可能变化,以官方文档为准。