CLAUDE CODE · 操作手册

Claude 的"记忆"系统

CLAUDE.md vs memory · 全局 vs 项目 · 写给 Teemo 自己看的指南

Claude Code 看似"记得"很多事——能叫出你的名字、知道项目结构、遵守你的工作规范。但这些"记忆"分布在两套独立机制里，新手极易混淆。

这份手册一次讲清四件事：两种记忆机制的区别、全局与项目的范围划分、四象限决策法、实战的提示词协议。

01两种"记忆"机制

叫"memory"会让人误以为它们是一回事，但它们完全不同。

CLAUDE.md

你写给 Claude 的指令文件

作者：你（手动编辑）
角色：规则 / 规范 / 契约
加载：每次会话自动注入
典型：「飞书文档默认用 XML」

MEMORY

Claude 自动维护的事实笔记

作者：Claude（自动写入）
角色：事实 / 观察 / 偏好
加载：索引注入 + 按需读
典型：「Margin 用 Vercel 部署」

CLAUDE.md 告诉 Claude "你应该怎么做"
memory 告诉 Claude "我们知道什么事实"

02范围：全局 vs 项目

无论哪种机制，都有"在哪些会话里加载"这个范围概念。

CLAUDE.md 的范围（向上叠加）

位置	范围	何时加载
`~/.claude/CLAUDE.md`	全局	每次启动都加载
`<project>/CLAUDE.md`	项目	cwd 在该项目时加载
`<project>/<sub>/CLAUDE.md`	子目录	进入更深目录时叠加
`<project>/CLAUDE.local.md`	项目 + gitignored	同项目，不进 git

关键规则：CLAUDE.md 从 cwd 向上级目录逐层叠加，所有命中的层都会加载。
所以启动 cwd 越深，加载的层越多。宁深勿浅。

memory 的范围（cwd 严格隔离）

~/.claude/projects/<encoded-cwd>/memory/

  例：cwd = /Users/teemo/Desktop/teemo-workspace/Projects/html-lab/
  对应：~/.claude/projects/-Users-teemo-Desktop-teemo-workspace-Projects-html-lab/memory/

  （把所有 / 替换成 -）

⚠

反直觉的关键事实：memory 没有真正的"全局"版本。

它永远按 cwd 隔离。如果想让某个事实在所有项目都被 Claude 知道，唯一办法是写进全局 CLAUDE.md（即使本质是事实而不是规则）。

03四象限决策图

把"性质"和"范围"两个维度交叉 → 4 个落点。

全局可见

项目可见

规则 / 偏好

~/.claude/CLAUDE.md

跨所有项目都遵守的规则

例：默认自主执行、付费 skill 锁手动触发

<project>/CLAUDE.md

只在该项目下生效的规则

例：飞书文档默认用 XML 格式

事实 / 观察

~/.claude/CLAUDE.md 用户区

借道 CLAUDE.md（无真全局 memory）

例：翁呈轩、个人站 URL

~/.claude/projects/.../memory/

Claude 自动维护，按 cwd 隔离

例：Margin 用 Vercel 部署

左下象限是关键反例：想全局可见的"事实"也得借道 CLAUDE.md，因为 memory 没有全局版本。

04实战 Playbook

三个核心问题，逐个给答案。

Q1 · 新会话该在哪个目录启动？

cwd 决定哪些 CLAUDE.md 被加载。让 cwd = 任务的实际所在地，宁深勿浅。

要做的事	启动 cwd	叠加层数
写飞书财务相关	`飞书/人生无限公司/财务/`	5 层
写飞书随想（KB 内）	`飞书/人生无限公司/`	4 层
飞书跨模块讨论	`飞书/`	3 层
处理某 GitHub 项目	`Projects/<名>/`	3 层
Wiki / 跨项目	`~/Desktop/teemo-workspace/`	2 层
无关项目	`~` 或 `/tmp`	1 层（仅全局）

Q2 · 怎么更新 CLAUDE.md？

用显式提示词，不要让 Claude 猜。

✓ 推荐

「把 X 加到全局 CLAUDE.md」
「把 X 加到项目 CLAUDE.md」
「把关于 Y 的那条改成…」

✗ 避免

「记一下 X」（无范围）
让 Claude 自己判断该写全局还是项目
为单步操作做 skill（过度工程）

⚠

为什么不让 Claude 猜？代价不对称。

写到项目（窄）猜错 → 在其他项目失效，损失小。
写到全局（宽）猜错 → 污染所有项目 + 浪费 token + 影响判断，损失大。

Q3 · memory 还是 CLAUDE.md？

按性质 + 范围两个维度判断。

是规则 / 偏好 / 契约吗？ ├─ 是 → CLAUDE.md │ ├─ 跨项目？ → 全局 │ └─ 不跨？ → 项目 └─ 否（是事实） ├─ 跨项目？ → 全局 CLAUDE.md 的"用户"区（借道） └─ 不跨？ → 项目 memory

例子对照

你说的话	性质	范围	落点
"默认回答中文"	规则	全局	~/.claude/CLAUDE.md
"飞书文档用 XML"	规则	项目	飞书/CLAUDE.md
"我女朋友叫小明"	事实	全局	~/.claude/CLAUDE.md 用户区
"Margin 部署在 Vercel"	事实	项目	Margin memory
"我喜欢用 Tailwind"	偏好	全局	~/.claude/CLAUDE.md

"记一下 X" 协议

✓

已写入 ~/.claude/CLAUDE.md v1.1

用户说"记一下 X"但没指定落点时，Claude 必须：
① 先问性质（规则/事实）+ 范围（全局/项目）
② 改全局 CLAUDE.md 前必须告知用户
③ 项目 memory 可自主写，写完报备

05意外发现：memory 实际很稀疏

在 Teemo 这台机器上的真实状态：

有 memory 的 cwd

memory 条目总数

0
飞书工作目录

home (~) 累积

为什么这么少？几个原因叠加：

1. Auto-memory 是相对新功能
2. 维护良好的 CLAUDE.md 体系会"抢走" memory 的活
3. 讨论型对话不容易触发自动保存
4. 大部分 cwd 是一次性任务

✓

对 Teemo 这种"主动维护 CLAUDE.md"的用户，memory 重要性其实不高。

规则化沉淀已经在 CLAUDE.md 层完成。memory 累积少不是 bug，是 CLAUDE.md 体系成熟的副作用。
不用焦虑，继续以 CLAUDE.md 为主即可。

06备忘卡

遇事不决，回这里看一眼。

▸ 启动会话

cwd 尽量深 → 自动叠加所有上层 CLAUDE.md
常用入口建 shell alias（已有 feishu，可以加 obs、margin）

▸ 更新规则

「加到全局 CLAUDE.md：X」→ ~/.claude/CLAUDE.md
「加到项目 CLAUDE.md：X」→ <project>/CLAUDE.md
「记一下 X」（模糊）→ Claude 先问

▸ 更新事实

跨项目事实 → 全局 CLAUDE.md（借道）
项目事实 → 让 Claude 自动写 memory，报备即可

▸ 不要做的事

✗ 让 Claude 猜该写全局还是项目
✗ 把事实写进 CLAUDE.md（除非要跨项目）
✗ 把规则写进 memory（不保证加载）
✗ 在项目文件夹里找 memory（找不到，它在 ~/.claude/）

07验证全局 CLAUDE.md 是否生效

随时可以做的一次性体检。

$ cd /tmp
$ claude

然后问：

我叫什么？你现在加载了哪些 CLAUDE.md？

预期回答：

✓ 知道你叫 翁呈轩（Teemo Weng）
✓ 列出加载了 ~/.claude/CLAUDE.md
✓ 没加载任何项目 CLAUDE.md（/tmp 不在任何项目下）

如果不符合预期，说明全局 CLAUDE.md 出了问题（被改坏、被删、路径错），需要排查。