Claude Code 每次会话都从空白上下文开始。CLAUDE.md 文件和 Auto Memory 是跨会话携带知识的两种机制，两者相辅相成。
CLAUDE.md vs Auto Memory 对比
| CLAUDE.md 文件 | Auto Memory | |
|---|---|---|
| 谁来写 | 你 | Claude 自动记录 |
| 包含内容 | 指令和规则 | 学到的模式和习惯 |
| 作用范围 | 项目/用户/组织 | 每个工作树（worktree） |
| 加载方式 | 每次会话全量加载 | 每次会话加载前 200 行 |
| 适用场景 | 编码规范、工作流、架构决策 | 构建命令、调试洞察、Claude 自动发现的偏好 |
原则：用 CLAUDE.md 文件主动引导 Claude 的行为；用 Auto Memory 让 Claude 从你的纠正中自动学习，无需手动整理。
CLAUDE.md 文件的四种作用域
| 作用域 | 位置 | 用途 | 共享范围 |
|---|---|---|---|
| 托管策略 | macOS: /Library/Application Support/ClaudeCode/CLAUDE.md<br>Linux/WSL: /etc/claude-code/CLAUDE.md<br>Windows: C:\Program Files\ClaudeCode\CLAUDE.md | IT/DevOps 管理的全组织指令 | 组织内所有用户 |
| 项目指令 | ./CLAUDE.md 或 ./.claude/CLAUDE.md | 团队共享的项目指令 | 通过版本控制共享给团队成员 |
| 用户指令 | ~/.claude/CLAUDE.md | 跨所有项目的个人偏好 | 仅限本人（所有项目） |
| 本地指令 | ./CLAUDE.local.md | 不进 git 的个人项目偏好 | 仅限本人（当前项目） |
优先级：更具体的位置覆盖更宽泛的位置（local > project > user > managed）
快速初始化项目 CLAUDE.md
# 在项目根目录运行
claude
/init/init 会分析你的代码库（构建系统、测试框架、代码规范），自动生成一个基础 CLAUDE.md。如果文件已存在，则建议改进而不是覆盖。
写出有效的 CLAUDE.md
推荐格式：
# Code style
- Use ES modules (import/export) syntax, not CommonJS (require)
- Destructure imports when possible (eg. import { foo } from 'bar')
# Workflow
- Be sure to typecheck when you're done making a series of code changes
- Prefer running single tests, not the whole test suite, for performance
# Architecture
- API handlers live in src/api/handlers/
- Database models in src/models/
- Run `npm run build` to compile, `npm test` for tests写作原则：
| ✅ 应包含 | ❌ 应排除 |
|---|---|
| Claude 无法猜到的 Bash 命令 | Claude 能从代码中自行发现的内容 |
| 与默认不同的代码风格规则 | 标准语言惯例（Claude 已知） |
| 测试指令和首选测试运行器 | 详细 API 文档（链接即可） |
| 代码库约定（分支命名、PR 规范） | 频繁变化的信息 |
| 项目特有的架构决策 | 冗长的解释或教程 |
| 开发环境特殊要求（必需环境变量） | 逐文件描述代码库 |
| 常见坑和非直觉行为 | 「写简洁的代码」这类显而易见的话 |
大小控制：目标每个 CLAUDE.md 文件不超过 200 行。文件越大，Context 占用越多，遵从度反而下降。
使用 @ 导入其他文件
CLAUDE.md 支持 @path/to/import 语法引入其他文件，在启动时展开并加载到上下文：
See @README for project overview and @package.json for available npm commands.
# Additional Instructions
- git workflow @docs/git-instructions.md- 支持相对路径和绝对路径（相对于包含导入的文件）
- 导入文件可递归导入其他文件（最大 5 层）
- 第一次遇到外部导入时，Claude Code 会弹出审批对话框
跨 worktree 共享个人配置（CLAUDE.local.md 仅存在于一个 worktree 中）：
# Individual Preferences
- @~/.claude/my-project-instructions.md.claude/rules/ 路径级规则
对于大型项目，用 .claude/rules/ 目录组织模块化规则：
your-project/
├── .claude/
│ ├── CLAUDE.md # 主项目指令
│ └── rules/
│ ├── code-style.md # 代码风格规范
│ ├── testing.md # 测试规范
│ └── security.md # 安全要求
路径匹配规则（frontmatter）
规则可以用 YAML frontmatter 的 paths 字段限定作用文件范围：
---
paths:
- "src/api/**/*.ts"
---
# API 开发规则
- 所有 API 端点必须包含输入验证
- 使用标准错误响应格式
- 包含 OpenAPI 文档注释只有当 Claude 打开匹配路径的文件时，这条规则才会加载到上下文，节省 Context 空间。
路径匹配模式速查：
| 模式 | 匹配 |
|---|---|
**/*.ts | 任意目录下的所有 TypeScript 文件 |
src/**/* | src/ 下的所有文件 |
*.md | 项目根目录的 Markdown 文件 |
src/components/*.tsx | 特定目录的 React 组件 |
多模式 + 大括号展开：
---
paths:
- "src/**/*.{ts,tsx}"
- "lib/**/*.ts"
- "tests/**/*.test.ts"
---跨项目共享规则（symlink）
# 用软链接在多个项目间共享规则集
ln -s ~/.claude/shared-rules/security.md .claude/rules/security.md用户级规则（跨所有项目）
# 在 ~/.claude/rules/ 目录中放置规则文件
mkdir -p ~/.claude/rules
echo '# Personal style\n- Always use Chinese variable comments' > ~/.claude/rules/personal.mdAuto Memory（自动记忆）
Auto Memory 是 Claude Code 自动记录用户习惯和偏好的系统，无需手动整理。
存储位置：每个工作树（worktree）独立存储，每次会话加载前 200 行。
工作原理：当你纠正 Claude 的行为时（「不要这样写」「用这种风格」），Claude 会自动将这个偏好写入 Auto Memory，下次会话直接沿用。
启用/禁用：
/memory # 查看和编辑 Auto Memory
# 在设置中可以开启或关闭 Auto Memory
查看 Auto Memory 内容：
/memory → 选择「查看 Auto Memory」
适合 Auto Memory 的内容：
- 构建命令和测试命令
- 调试过程中发现的规律
- 你反复纠正 Claude 的行为模式
常见问题排查
Claude 不遵循 CLAUDE.md 指令：
- 检查文件是否保存在正确路径
- 确认文件大小未超过 200 行（过长导致遵从度下降）
- 检查规则是否有矛盾（Claude 可能随机选择其一）
不知道 Auto Memory 保存了什么：
- 运行
/memory查看所有条目 - 可以直接编辑或删除不需要的条目
CLAUDE.md 太大了：
- 将长文件拆分为
.claude/rules/中的多个主题文件 - 用路径规则限定只在特定文件类型时加载
- 用
@import语法将常用文档链接进来而非复制
/compact 后指令好像丢失了：
- CLAUDE.md 在每次会话开始时加载，但
/compact压缩后不会重新加载 - 解决方案：重启会话（
/clear）让 CLAUDE.md 重新完整加载
原文：How Claude remembers your project - Claude Code Docs | 来源：Anthropic 官方文档