引言：一个直觉引发的问题

我用 Claude Code 给自己的项目建了一套"记忆"，希望它能长期记住项目知识，不用每次对话都从零开始。

直觉告诉我：多记点总没错吧？于是我让它通读项目，把所有"有用"的知识都存下来。

结果它一口气写了 6 个记忆文件，总共 8KB。内容覆盖项目结构、状态枚举、启动方式、测试框架、代码规范……应有尽有，感觉非常踏实。

但回头一看——这些信息真的都需要"记住"吗？已有的工具能不能覆盖？

于是我开始了一轮又一轮的裁剪。

背景：先认识三个工具

在讲裁剪过程之前，先介绍这次故事涉及的三个工具。如果你已经熟悉可以跳过。

Claude Code

Claude Code 是 Anthropic 官方的命令行 AI 编程助手。它在你终端里工作，能读写代码、执行命令、搜索代码库。和网页版 Claude 的最大区别是：它能直接操作你的本地项目。

安装方式：

npm install -g @anthropic-ai/claude-code

使用方式：

cd your-project
claude

然后就像聊天一样跟它对话，让它帮你写代码、改 bug、做 code review。

CLAUDE.md

CLAUDE.md 是 Claude Code 的项目说明书，放在项目根目录下，每轮对话自动加载到 AI 的上下文中。

你可以把它理解为"给 AI 看的 README"。它不需要安装任何东西——只要你项目根目录有这个文件，Claude Code 就会自动读取。

典型的 CLAUDE.md 长这样：

# CLAUDE.md

## Project Overview
这是一个电商后端项目，基于 Spring Boot...

## Tech Stack
- Java 17 + Spring Boot 3
- MySQL + Redis
- RabbitMQ

## Code Conventions
- Controller 类命名用 XxxResource
- REST API 前缀 /api/v1
- 所有 DTO 放在 dto 包下

创建方式有两种：

• 在 Claude Code 中输入 /init，AI 会自动扫描项目并生成一份 CLAUDE.md
• 也可以自己手动创建，写你关心的内容

关键特点：

• 每轮对话都会加载，不管用不用得到
• 由开发者控制内容——可以自己写，也可以让 AI 生成后再调整
• 不会随代码变化自动更新，需要手动维护
• 适合写"怎么跟这个项目协作"的行为准则

你可以在里面写项目架构、代码规范、运行命令、注意事项等。Claude Code 每次开始对话时都会先读一遍这个文件，相当于你给它提前"交代"好了。

Codegraph

Codegraph 是一个代码智能索引工具，能自动扫描项目中的所有符号、文件、调用关系，构建出一个知识图谱。Claude Code 可以通过 MCP（Model Context Protocol）接入它，实现毫秒级的代码查询。

安装方式：

# 安装 codegraph CLI
pip install codegraph-mcp
# 或者通过 npm
npm install -g codegraph-mcp

初始化（在项目根目录）：

cd your-project
codegraph init

然后在 Claude Code 的 MCP 配置中添加：

{
  "mcpServers": {
    "codegraph": {
      "command": "codegraph",
      "args": ["serve"]
    }
  }
}

使用方式——Claude Code 会自动使用 Codegraph 提供的工具：

工具	作用	示例
codegraph_explore	自然语言探索代码，返回源码	"OrderStatus 有哪些枚举值"
codegraph_search	按名称搜索符号	"找所有叫 createOrder 的函数"
codegraph_callers	查谁调用了某个函数	"谁调了 createOrder"
codegraph_callees	查某个函数调了哪些函数	"OrderService 调了什么"
codegraph_impact	分析改一个符号会影响哪些代码	"改 OrderStatus 会影响哪些文件"
codegraph_files	查看项目文件树	"src/service/ 下有哪些文件"

关键特点：

• 文件变化后约 1 秒自动更新索引，基本实时
• 按需查询——只有你问的时候才调用，不占每轮上下文
• 能追踪调用链、分析影响范围，这是文本搜索做不到的

Claude Code Memory

Memory 是 Claude Code 的持久化笔记机制。AI 可以把经验、教训、项目知识写入文件，下次会话自动加载。

它不需要安装——Claude Code 自带这个功能。记忆文件存放在：

~/.claude/projects/<project-path>/memory/

结构很简单：

memory/
├── MEMORY.md                     # 索引文件（每轮自动加载）
└── pitfalls-and-decisions.md     # 具体记忆文件

每个记忆文件是一个 Markdown 文件，带 frontmatter 元数据：

---
name: pitfalls-and-decisions
description: 踩坑经验和设计决策
metadata:
  type: feedback
---

这里写具体内容...

关键特点：

• 索引（MEMORY.md）每轮自动加载，具体内容按需召回
• 由 AI 写入，你可以让它修改或删除
• 适合存"代码里看不到、文档里没写"的隐性知识

第一轮：什么都想记（6 个文件，8KB）

了解了三个工具之后，回到我的故事。

我对 Claude Code 说："读一下我的项目，把需要长期使用的存入记忆。"

它通读了项目结构、入口文件、数据库模型、常量定义、任务调度器、测试框架……然后一口气写了 6 个记忆文件：

文件	内容
project-overview.md	项目定位、技术栈、完整目录结构、Git 信息
dev-environment.md	启动命令、数据库配置、外部服务地址
architecture-patterns.md	请求流、中间件链、调度器架构、订单状态流转
testing-guide.md	测试框架、fixture 配置、测试模块分类
code-conventions.md	命名规范、注释语言、路径约定
key-enums-constants.md	OrderStatus、PaymentType 等核心枚举值

总计约 8KB，覆盖了项目的方方面面。

当时我感觉很踏实——信息很全，下次对话不用重新探索了。

但仔细一想：这些信息，真的需要"记住"吗？

第二轮：和 Codegraph 对比（砍掉 70%）

我让 Claude Code 自己评估：这些记忆内容，codegraph 能查到吗？

它逐条对比后给出了结果：

记忆内容	Codegraph 能查到吗
目录结构	✅ codegraph_files 一键出
OrderStatus 枚举值	✅ codegraph_explore("OrderStatus") 直接拿到源码
API 路由列表	✅ codegraph_explore("RouterConfig") 完整返回
请求流/中间件链	✅ codegraph_explore("AuthMiddleware")
调度器任务类型	✅ codegraph_node("TaskScheduler") 完整代码
PaymentType 等常量	✅ codegraph_explore("PaymentType")
测试框架/fixture	✅ codegraph_explore("conftest")
"为什么测试要 mock 定时任务"	❌ 查不到
"Redis 的 db0~db15 分别干什么"	❌ 只能看到代码赋值，不知道含义
"必须从项目根目录启动"	❌ codegraph 不关心运行时
"延迟导入是为避免循环依赖"	❌ 代码里看不出来

70% 的记忆内容是 codegraph 已经覆盖的，而且 codegraph 返回的永远是实时代码，比记忆的静态快照更准确。

打个比方：你想知道今天北京多少度，你是翻出上周拍的天气预报截图（记忆），还是打开天气 App 看一眼（codegraph）？当然是后者——实时、准确、不费力。

这里有一个关键认知：

记忆是静态快照，codegraph 是实时索引。能查到的不要记。

你把枚举值记到记忆里，三个月后代码加了个新状态，记忆就过时了。而 codegraph 每次查的都是最新代码，永远不会过时。

这一轮砍完，从 6 个文件缩减到 2 个，只保留了 codegraph 查不到的"Why"类知识和运行时经验。

第三轮：和 CLAUDE.md 对比（又砍一半）

还没完。我又问：剩下的内容，CLAUDE.md 里有没有？

CLAUDE.md 是我之前就写好的项目说明书，每轮对话自动加载。再看一遍：

记忆内容	CLAUDE.md 已经有了？
必须从项目根目录启动	✅ 已写
数据库表名前缀约定	✅ 已写
Controller 命名规范	✅ 已写
资源文件路径约定	✅ 已写
前后端分离架构	✅ 已写
订单状态流转链路	✅ 已写
当前开发分支	✅ 已写
测试必须 mock 定时任务	❌ 没提
utils 目录会遮蔽同名标准库	❌ 没提
Redis db 编号具体分配	❌ 只说"多个 db"，没说哪个干什么
延迟导入是设计决策	❌ 没提
用了自定义枚举不要替换成标准库	❌ 没提

又有一半内容和 CLAUDE.md 重复。这意味着每轮对话，同一份信息被加载了两次——CLAUDE.md 加载一次，Memory 又加载一次，白白浪费 token。

打个比方：这就像你桌上贴了两张便利贴，写的都是"下班锁门"。每次看过去两眼都看到一样的信息，浪费注意力。撕掉一张，只留一张就够了。

这一轮砍完，从 2 个文件缩减到 1 个文件，只留了 7 条纯增量知识。

最终成果

裁剪前后对比：

阶段	文件数	大小	内容
最初	6 个	~8KB	什么都记
第二轮后	2 个	~4KB	只记 codegraph 查不到的
最终	1 个	1.7KB	只记 codegraph 查不到、CLAUDE.md 没写的

最终留下的 7 条知识：

1. 测试必须 mock 定时任务（否则文件锁冲突）
2. 测试必须 mock 日志配置（否则权限报错）
3. 项目中的 utils 目录会遮蔽 Python 标准库同名模块（需要预加载）
4. 测试必须关闭异常传播（否则中间件捕获异常后会二次崩溃）
5. Redis 的 16 个 db 分别干什么（db0=缓存, db5=队列……）
6. 函数内的延迟导入是设计决策，不是疏忽
7. 项目用自定义枚举函数，不要替换成标准 Enum

这些知识的共同特点：代码里没写出来，文档里没提过，只有踩过坑才知道。

三层知识的分工

经过这三轮裁剪，我理清了一个框架：AI 编程助手的知识来自三层，每层解决不同的问题。

层级一：CLAUDE.md——行为准则

解决什么问题：怎么跟这个项目协作

CLAUDE.md 告诉 AI 项目的游戏规则——代码规范是什么、怎么启动、基本架构如何。它不负责传授具体知识，而是设定行为边界。就像新员工入职时你给的那份"开发规范"文档：不需要教他每一行代码怎么写，但要告诉他"注释用中文"、"API 前缀是 /api/v1"。

谁来维护：开发者控制内容（/init 自动生成或手写，之后手动维护）

什么时候加载：每轮对话自动加载

适合写什么：

• 项目概述和架构
• 代码规范和约定
• 运行和部署方式
• 不要做什么（禁止事项）

💡 题外话：CLAUDE.md 不会自动更新，代码变了怎么办？

这是很多人会问的问题。CLAUDE.md 是静态文件，代码改了它不会跟着变。但如果你设计得当，这不是问题。

秘诀只有一个：CLAUDE.md 只写"稳定的东西"。

适合写（几乎不变）	不适合写（经常变）
技术栈是 Flask + Redis	当前有哪些 API 路由
代码规范：中文注释、4 空格缩进	OrderStatus 的枚举值
API 前缀 /api/v1	数据库有哪些表
启动方式 python app.py	函数的参数签名

左边这些可能几个月才变一次，改了手动更新就行。右边这些天天变，但本来就不该写在 CLAUDE.md 里——交给 codegraph 实时查就好了。

所以这又回到了文章的核心观点：让每个知识待在对的地方。稳定的写文档，变化的靠查询，经验的记笔记。三层各司其职，就不存在"过时"的问题。

层级二：Codegraph——实时查询

解决什么问题：代码现在到底长什么样

不管代码怎么变，查询结果永远是实时的。函数签名、枚举值、调用链、影响范围——这些"事实性"的信息不需要记，查就行。就像工程师不需要背 API 文档，知道怎么查就够了。

谁来维护：自动索引，无需手动维护

什么时候用：按需查询，不占每轮上下文

适合查什么：

• 函数/类的定义和位置
• 调用链和依赖关系
• 改某个符号会影响哪些代码
• 符号的完整源码

层级三：Memory——经验传承

解决什么问题：踩过的坑、代码里看不出来的隐性知识

有些知识代码不会告诉你——比如"这个目录名会遮蔽标准库"、"延迟导入是故意的"。这些只有实际踩过坑、做过决策的人（或 AI）才知道。就像老员工的"经验笔记"——文档里找不到，但对新人最有价值。

谁来维护：AI 写入，开发者可以要求修改或删除

什么时候加载：索引每轮加载，内容按需召回

适合记什么：

• 踩坑经验（"必须 mock xxx 否则会…"）
• 设计决策的 Why（"为什么不这样做"）
• 运行时约束（"必须从某个目录启动"）
• 项目特有的隐性知识

三层对比一图看清

遇到问题时的知识获取顺序：

CLAUDE.md

零成本，每轮自动加载

项目规范、运行方式、代码约定

↓ 不够？

Codegraph

按需查询，1 次工具调用

函数定义、调用链、枚举值、影响范围

↓ 还不够？

Memory

经验召回，踩坑记录

代码里看不到、文档里没写的隐性知识

实操建议

如果你也在用 Claude Code 或类似的 AI 编程助手，以下是整理知识的具体建议。

该记什么

问自己一个问题：这个知识，codegraph（或代码搜索）能查到吗？CLAUDE.md 已经有了吗？

• 都能 → 不记
• 只有一个能 → 看看是否足够，够了就不记
• 都不能 → 这才值得记

具体来说，这三类知识最适合放进 Memory：

1. 踩坑经验 — "测试必须 mock 定时任务，否则多 worker 文件锁冲突"、"utils 目录名会遮蔽标准库"
2. 设计决策的 Why — "延迟导入是为解决循环依赖，不是疏忽"、"用自定义枚举而非标准库，保持一致性"
3. 运行时约束 — "必须从项目根目录启动"、"调试时不要残留锁文件"

不该记什么

1. 代码本身记录的东西 — 结构、枚举值、函数签名 → 让搜索引擎实时查
2. CLAUDE.md 已经写了的东西 — 不要重复占 token
3. 会频繁变化的东西 — 记忆是快照，业务状态天天变，记了反而误导

判断标准

一条知识值不值得记，用这个检查清单：

☐ 代码搜索/codegraph 查不到？

☐ CLAUDE.md 里没有？

☐ 下次对话还用得到？

☐ 不会频繁变化？

4 个都勾 → 值得记

有 1 个不勾 → 想想是不是有更好的载体

结尾

最终我的项目只留了 1 个记忆文件，7 条知识，1.7KB。

不是偷懒——而是每一层知识都有了最合适的载体：

• CLAUDE.md 管"怎么做"（行为准则）
• Codegraph 管"是什么"（实时查询）
• Memory 管"别再踩坑"（经验传承）

少记不是忘得少，而是让每个知识待在对的地方。