CLAUDE.md 记忆系统
每次启动 Claude Code 都是一个全新的上下文窗口。那么 Claude 怎么记住你的项目约定、技术栈、编码规范？答案是记忆系统——由你手动维护的 CLAUDE.md 文件和 Claude ���动维护的 Auto Memory 共同构成。
你将学到
- CLAUDE.md 的作用和最佳写法
- 文件层级：组织级 → 用户级 → 项目级 → 子目录级
- Auto Memory 的工作原理
- 路径作用域规则（path-scoped rules）
- 上下文窗口管理策略
适合谁
- 希望让 Claude Code 更精准地遵循团队规范的开发者
- 管理多个项目、需要跨会话保持上下文的工程师
1. CLAUDE.md vs Auto Memory
Claude Code 有两套记忆机制：
| 特性 | CLAUDE.md | Auto Memory |
|---|---|---|
| 编写者 | 你手动编写 | Claude 自动记录 |
| 内容 | 指令和规则（如"使用 pnpm"） | 学到的模式和偏好 |
| 范围 | 组织/用户/项目/子目录 | 按工作树范围 |
| 加载方式 | 每次会话完整加载 | 前 200 行加载 |
| 适合 | 明确的编码规范和项目规则 | Claude 在交互中学到的偏好 |
两者在每次对话开始时都会加载。Claude 将它们视为上下文参考。指令越具体越简洁，Claude 越能一致地遵循。
2. CLAUDE.md 文件层级
文件位置决定作用范围，从最广到最窄：
| 层级 | 位置 | 说明 |
|---|---|---|
| 组织级 | /Library/Application Support/ClaudeCode/CLAUDE.md (macOS) |
IT 管理的全组织策略 |
| 用户级 | ~/.claude/CLAUDE.md |
你的个人偏好，跨所有项目 |
| 项目级 | ./CLAUDE.md 或 ./.claude/CLAUDE.md |
项目规范，通过 Git 共享 |
| 子目录 | 子目录中的 CLAUDE.md |
按需加载，适合模块级规则 |
父目录的 CLAUDE.md 在启动时自动加载（适合 monorepo 场景）。子目录的 CLAUDE.md 仅在 Claude 处理该目录文件时按需加载。
推荐做法
~/.claude/CLAUDE.md：放个人偏好（如"我喜欢简洁的 commit message"）./CLAUDE.md：放项目规范（技术栈、命名规则、构建命令），提交到 Git 让团队共享- 子目录：放模块特定规则（如"API 路由必须用 zod 验证"）
3. 编写高效的 CLAUDE.md
好的 CLAUDE.md 示例
# Project: My API Server
## Tech Stack
- Node.js 20 + TypeScript 5
- Express.js with Zod validation
- PostgreSQL + Prisma ORM
- Jest for testing
## Commands
- `npm run dev` - start dev server
- `npm test` - run all tests
- `npm run lint` - run ESLint
## Conventions
- Use 2-space indentation
- All API routes must validate input with Zod
- Database queries go through Prisma, never raw SQL
- Error responses follow RFC 7807 format
- Commit messages use conventional commits (feat:, fix:, etc.)
## Architecture
- `src/routes/` - Express route handlers (thin layer)
- `src/services/` - Business logic
- `src/repositories/` - Data access layer
- `src/middleware/` - Express middleware
写作原则
- 保持简洁：对每一行问自己——"删掉这行会导致 Claude 犯错吗？"如果不会，就删掉
- 具体可执行：写 "Use 2-space indentation" 而不是 "format code nicely"
- 像代码一样维护��出问题时审查，定期修剪，观察行为变化
- 提交到 Git：让团队共同维护项目级 CLAUDE.md
- 用强调词提升遵守度：关键规则用 "IMPORTANT" 或 "YOU MUST" 标注
不要放什么
- 不要放太长的说明——过长的 CLAUDE.md 会导致 Claude 忽略你的实际指令
- 偶尔才用的工作流放到 Skills 中，不要塞进 CLAUDE.md
- 能从代码推断出的信息不需要写（如类型定义的含义）
4. 路径作用域规则
在 .claude/rules/ 目录下创建规则文件，通过 YAML frontmatter 限定到特定文件路径：
示例：API 路由验证规则
创建 .claude/rules/api-validation.md：
---
paths:
- "src/api/**/*.ts"
---
All API routes must validate request parameters with Zod schemas.
Always return proper error responses for validation failures.
示例：测试框架规则
创建 .claude/rules/testing.md：
---
paths:
- "src/**/*.{ts,tsx}"
- "tests/**/*.test.ts"
---
Use Vitest, not Jest. Run tests with `npx vitest run`.
这些规则只在 Claude 处理匹配路径的文件时加载，不会浪费上下文空间。
5. Auto Memory
Auto Memory 是 Claude 自动维护的笔记系统，记录它在交互中学到的模式和偏好。
工作原理
- 文件存储在
~/.claude/projects/<project>/memory/ MEMORY.md是索引文件，前 200 行在每次会话开始时加载- 详细笔记存储在单独的主题文件（如
debugging.md、patterns.md），按需访问 - 超过 200 行的索引内容不会自动加载
教 Claude 记住
always use pnpm, not npm
remember that the API tests require a local Redis instance
从现在起使用 conventional commits 格式
Claude 会将这些保存到 Auto Memory 中。
管理 Auto Memory
使用 /memory 命令：
- 浏览和打开所有记忆文件
- 切换 Auto Memory 开关
- 打开记忆文件夹直接编辑
记忆文件是纯 Markdown，你可以随时编辑或删除。
禁用 Auto Memory
如果不需要：
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1
6. 上下文窗口管理
上下文窗口是 Claude Code 最重要的资源。它包含：对话历史、文件内容、命令输出、CLAUDE.md、加载的 Skills。
管理策略
| 操作 | 命令 | 何时使用 |
|---|---|---|
| 检查使用量 | /context |
随时查看 |
| 压缩历史 | /compact |
上下文使用 ~60% 时 |
| 清理上下文 | /clear |
切换到不相关的任务时 |
关键建议
- 主动压缩：在 ~60% 时用
/compact，不要等到自动压缩（~80%） - 任务隔离：不同任务之间用
/clear分隔，避免"大杂烩"会话 - 精简 CLAUDE.md：它每次都加载，只放广泛适用的内容
小结
- CLAUDE.md 是你给 Claude 的持久化指令，Auto Memory 是 Claude 自己的笔记
- 项目级 CLAUDE.md 提交到 Git，让团队共享编码规范
- 保持简洁——过长的指令反而降低遵守度
- 用路径作用域规则精确控制不同模块的规范
- 主动管理上下文窗口：
/compact、/clear、/context
延伸阅读
内容来源：Anthropic 官方文档