跳至内容

AI 讲明白 · 系列细讲 2 / 3

经验该沉淀到哪

同一条教训,在 Claude Code 里至少能放进六个地方:CLAUDE.md、规则文件、skill、hook、子代理、自动记忆。放对了,下次自动生效;放错了,要么被忽略,要么每轮对话都白白占着上下文。这篇按官方文档把“该放哪、怎么写、怎么修剪”讲清楚。

官方Claude Code 官方文档(v2.1.293 时的版本) 实测本机跑过 推断我的判断

先记住一条:说一遍不等于记住

在对话里纠正 Claude,只对这一次会话有效。/clear 之后、开新会话之后,它就不记得了。官方文档给的时机很明确:同一个错误犯第二次,或者你在聊天里敲了一句上次会话也敲过的纠正,就该把它写下来。官方

写到哪,取决于两件事:它什么时候需要被看到,以及它是不是必须每次都发生。前者决定上下文成本,后者决定该用“提醒”还是“强制”。

最容易犯的错

把“绝不能做 X”写进 CLAUDE.md,以为就安全了。官方原话:CLAUDE.md 是作为一条用户消息送进对话的,there's no guarantee of strict compliance。写在文字里的规则只是请求,hook 才是强制。官方

按“什么时候被看到”分三层

上下文窗口是最稀缺的资源,越满表现越差。所以先看每个位置的加载方式,再决定往哪放。

常驻 · 每轮都在

写进去就一直占着

CLAUDE.md无 paths 的规则MEMORY.md 前 200 行输出风格skill 的描述

适合每个会话都要知道的事实和规则。每多一行,每一轮都要多付一次。

按需 · 用到才加载

碰到相关文件或任务才进来

带 paths 的规则skill 正文子目录的 CLAUDE.md记忆的主题文件

适合只对一部分代码成立的约定,以及偶尔才用的流程和参考资料。

不进主上下文

在对话外面执行

hook子代理

hook 不占上下文,除非它返回输出;子代理有自己独立的上下文,只把摘要带回来。

位置什么时候加载加载什么上下文成本
CLAUDE.md会话开始全文每一轮
输出风格会话开始、切换风格时当前风格的全部指令每一轮
skill会话开始 + 用到时开始时只有描述,用到时加载全文低(描述每轮都在)
MCP会话开始工具名,完整 schema 用到才取工具没用就很低
子代理被派出时新的独立上下文与主会话隔离
hook事件触发时什么都不加载,在外面执行零,除非 hook 返回内容

出处官方《Extend Claude Code》的 Context cost by feature 表,按原表翻译。官方

按顺序问七个问题

从上往下问,第一个回答“是”的,就是它该去的地方。顺序有讲究:先排除“必须强制”的,再按加载成本从高到低排。

  1. 它必须每次都发生,而且不需要 Claude 判断吗?格式化、禁止改某类文件、提交前跑检查、结束时通知你。
    hook写在 .claude/settings.json,事件触发就执行。
  2. 它跟“怎么回答”有关,而且你可能想随时关掉吗?回答长度、格式、讲解多少,或者让 Claude 扮演写作助手这类非工程角色。
    输出风格一次只生效一个,可以切换。
  3. 它会读大量文件、产生一堆你不会再看的中间输出吗?代码库调查、大范围搜索、逐个文件的审查。
    子代理.claude/agents/,只把结论带回主会话。
  4. 它是多步流程,或者只是偶尔才用到的参考资料吗?发版清单、排障手册、API 风格指南、数据库表说明。
    skill.claude/skills/<名字>/SKILL.md,用到才加载全文。
  5. 它只对某些文件或目录成立吗?前端组件写法、src/api/ 的接口约定、测试目录的规范。
    带 paths 的规则.claude/rules/*.md,碰到匹配的文件才加载。
  6. 它是这个项目每个会话都要知道的事实或规则吗?构建和测试命令、目录结构、团队约定、“总是做 X”。
    CLAUDE.md项目根目录,提交进仓库,团队共享。
  7. 它是你个人的偏好或背景,不是项目规则吗?你的角色、你习惯的做法、你纠正过它的事、外部资料在哪。
    自动记忆 · 个人 CLAUDE.md说“记住……”让它存进自动记忆,或者写进 ~/.claude/CLAUDE.md。

另外两个出口:要跨好几个仓库复用同一套 skill、hook、子代理,就打包成插件;需要连外部系统(数据库、工单、浏览器),用 MCP 接进来,再配一个 skill 写清楚怎么用。官方

说明这个问题顺序是我按官方各页的说法排的,官方没有给出这样一张决策表。推断

官方给的“出现什么信号就加什么”

不用一开始就全配齐。官方建议等信号出现了再加,大多数团队大致按下面的顺序。官方

信号加什么
同一个约定或命令,Claude 错了两次写进 CLAUDE.md
你一直在让它“短一点”“多解释点”“按同一种格式答”设一个输出风格
你总在敲同一段提示词来开始某类任务存成一个你能手动调用的 skill
同一份操作手册或多步流程,第三次往聊天里贴做成 skill
你一直在从 Claude 看不到的浏览器页面里复制数据把那个系统接成 MCP 服务
Claude 读很多文件只为找一个符号在哪定义、在哪用装对应语言的代码智能插件
一个支线任务的输出淹没了对话,而你以后不会再看交给子代理
你希望某件事每次都发生,不用开口写一个 hook
第二个仓库需要同一套配置打包成插件

官方还补了一句:同样的信号也说明已有的东西该改了。反复出现的错误、反复出现的审查意见,应该去改 CLAUDE.md,而不是在聊天里再纠正一次;一个你总在手动微调的流程,说明那个 skill 需要再修一版。

每个位置的写法要点

下面的数字和行为都取自官方文档,版本号是该行为开始生效的版本。

CLAUDE.md./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 可能听任何一边,要自己保持一致。
共享
支持符号链接。链到工作目录之外的文件,算“外部导入”,每个项目要你批准一次才加载。
.claude/rules/api.md
---
paths:
  - "src/api/**/*.ts"
---
- 新接口要在 openapi.yaml 里同步加上定义
- 错误统一用 ApiError 返回,不直接 throw 字符串
skill.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 只在调用它的那一轮免确认,并不限制它能用哪些工具。官方

.claude/skills/release/SKILL.md
---
name: release
description: 发布新版本:更新版本号、生成变更记录、打 tag 并推送
disable-model-invocation: true
---
发布 $ARGUMENTS:
1. 跑 npm test,全绿才继续
2. 更新 package.json 的版本号
3. 从上一个 tag 到现在的提交生成 CHANGELOG 条目
4. 提交、打 tag、推送
hook.claude/settings.json
本质
在固定的生命周期事件上执行你的脚本、HTTP 请求、MCP 工具,或者一段交给模型判断的提示词。事件一到必定触发,结果不靠 Claude 自觉。
成本
不占上下文,除非 hook 返回内容,比如把 lint 结果回给 Claude。
强制力
PreToolUse hook 返回 deny,即使在 bypassPermissions 模式下也照样拦。权限模式改不掉它。
常见用法
编辑后自动格式化(PostToolUse),拒绝危险命令或受保护的文件(PreToolUse),测试不过不让结束(Stop),会话结束发通知(SessionEnd / Notification)。
.claude/hooks/protect-migrations.sh
#!/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
.claude/settings.json
{
  "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 字段,它可以有自己的跨会话记忆。
.claude/agents/reviewer.md
---
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。

六条常见教训,各自去哪

同一种“被纠正”,落点可以完全不同。推断

这个项目用 pnpm,别用 npm
CLAUDE.md一行就够

每个会话都要知道,又是 Claude 猜不到的。如果它还是偶尔敲 npm install,再加一个 PreToolUse hook 拒绝这条命令。

改 src/api 下的接口,要同步改 openapi.yaml
带 paths 的规则

只在动接口代码时成立。放进 CLAUDE.md 会让每个会话都背着它,用 paths: src/api/** 只在需要时加载。

发版要走这七步
skilldisable-model-invocation

多步流程、有副作用、一个月用几次。做成 /release,只在你开口时运行。

绝不能改已经提交的迁移文件
hookCLAUDE.md 写原因

必须每次成立,所以由 hook 拦截;CLAUDE.md 里用一句话说明为什么、应该怎么做(新建迁移),让它一开始就走对路。

我习惯先看方案再动手,别直接改
自动记忆个人 CLAUDE.md

这是你个人的工作方式,不是项目规则。说“记住这一点”,它会存进 feedback 类记忆;想让它在所有项目都生效,写进 ~/.claude/CLAUDE.md。

排查线上问题,先看这三个仪表盘
skill(参考型)

只在排障时需要,内容又长。做成 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 当时的官方文档。版本号、数字限制以后可能变化,以官方文档为准。