# Claude Code 记忆与规则

> Claude Code 如何读取 CLAUDE.md、auto memory、.claude/rules，以及 AGENTS.md 项目的兼容方式。

URL: https://docs.passion8.cc/docs/claude-code/memory
Language: zh-CN
Publisher: Passion8

Claude Code 每次会话都是新的上下文窗口。要让它长期记住项目约定,主要靠两套机制:你写的 `CLAUDE.md`,以及 Claude 自动积累的 auto memory。

## CLAUDE.md 与 auto memory

| 机制 | 谁写 | 存什么 | 适合场景 |
| --- | --- | --- | --- |
| `CLAUDE.md` | 你或团队 | 明确指令、目录、命令、约定 | 可验证的长期规则 |
| Auto memory | Claude | 从纠正中学到的模式 | 反复出现的偏好和项目经验 |

这两者都是上下文,不是强制权限。想硬性阻止危险动作,用 [权限规则](https://docs.passion8.cc/docs/claude-code/permissions) 或 [Hooks](https://docs.passion8.cc/docs/claude-code/hooks)。

## 文件位置

| 范围 | 位置 | 用途 |
| --- | --- | --- |
| Managed policy | macOS `/Library/Application Support/ClaudeCode/CLAUDE.md`,Linux `/etc/claude-code/CLAUDE.md`,Windows `C:\Program Files\ClaudeCode\CLAUDE.md` | 组织级指令 |
| User | `~/.claude/CLAUDE.md` | 个人全局偏好 |
| Project | `./CLAUDE.md` 或 `./.claude/CLAUDE.md` | 团队共享项目规则 |
| Local | `./CLAUDE.local.md` | 本项目个人私有规则,应 gitignore |
| Rules | `./.claude/rules/*.md` | 模块化规则,可按路径懒加载 |

Claude 从当前目录向上查找 `CLAUDE.md` 和 `CLAUDE.local.md`。越靠近当前工作目录的内容越晚进入上下文,因此更具体。子目录里的 `CLAUDE.md` 会在 Claude 读取相关文件时按需加载。

## 推荐结构

```text
your-project/
├── CLAUDE.md
└── .claude/
    ├── settings.json
    └── rules/
        ├── testing.md
        ├── api.md
        └── frontend.md
```

`CLAUDE.md` 控制全局骨架:

```markdown title="CLAUDE.md"
# 项目约定

- 包管理器: pnpm
- 改完先跑 `pnpm lint`,涉及类型再跑 `pnpm typecheck`
- 不要把 `.env`、Key、生产配置写入文档或提交

## 目录

- 页面: `src/app`
- 组件: `src/components`
- 文档: `content/docs`

## 工作方式

- 大改动先给计划
- 修改 UI 后需要检查浅色和暗色
- 输出最终结果时必须列出验证命令
```

## 写得短,才能更稳

目标控制在 200 行以内。越长越吃上下文,也越容易互相矛盾。

有效规则通常有三个特点:

- 具体:写 `pnpm lint`,不要写“跑必要检查”
- 可验证:写“不要提交 `.env`”,不要写“注意安全”
- 按主题分组:构建、测试、目录、风格分开




如果一条规则只对部分目录有效,不要塞进根 `CLAUDE.md`,放进 `.claude/rules/` 并加 `paths`。




## 导入其它文件

`CLAUDE.md` 支持 `@path` 导入。相对路径以当前 `CLAUDE.md` 所在目录为基准,最多递归 4 层。

```markdown title="CLAUDE.md"
@README.md
@docs/development.md

## Claude Code 专用补充

- 优先使用现有组件
- 不做无关重构
```

如果只是想展示字符串,用反引号包住,例如 `` `@README.md` ``。

首次导入项目外部文件时,Claude Code 会要求确认。拒绝后不会自动再弹,需要你手动调整。

## AGENTS.md 项目

对于使用 `CLAUDE.md`、尚未启用原生 `AGENTS.md` 加载的安装，已有 `AGENTS.md` 的仓库可以这样兼容：

```markdown title="CLAUDE.md"
@AGENTS.md

## Claude Code

- 大范围改动先使用 plan mode
- UI 修改后检查移动端、浅色和暗色
```

也可以用 symlink,但 Windows 上更推荐 `@AGENTS.md` 导入。当前版本是否支持原生 AGENTS.md，应核对官方记忆文档，避免同时启用原生读取和重复导入。

## `.claude/rules/`

规则文件是更细粒度的 `CLAUDE.md`。没有 frontmatter 的规则每次启动都加载:

```markdown title=".claude/rules/testing.md"
# 测试规则

- 修复 bug 后优先跑相关单测
- 不要跳过失败测试
```

带 `paths` 的规则只在相关文件被读取时加载:

```markdown title=".claude/rules/api.md"
---
paths:
  - "src/api/**/*.ts"
  - "app/api/**/*.ts"
---

# API 规则

- 所有输入必须校验
- 错误返回统一 `{ code, message }`
- 不把服务端密钥写到客户端 bundle
```

这对大型仓库很重要,能减少上下文噪音和缓存失效。

## Auto memory

Auto memory 会记录 Claude 从纠正中学到的内容,按仓库共享。它适合保存“这个项目里实际踩过坑”的经验,例如构建命令、测试前置条件、常见失败原因。

常见控制方式:

| 需求 | 做法 |
| --- | --- |
| 临时不想用 auto memory | 设置 `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` |
| 调试记忆为什么没生效 | 用 `/context` 看加载内容 |
| 让某类规则更可靠 | 从 auto memory 提炼到 `CLAUDE.md` |

## 排错

| 现象 | 可能原因 | 检查 |
| --- | --- | --- |
| 改了 `CLAUDE.md` 但当前会话不听 | 根级文件启动时已加载 | `/clear`、`/compact` 或重启 |
| 子目录规则不生效 | Claude 没读到匹配文件 | 用 `@文件` 明确引用 |
| 规则互相冲突 | 多个 CLAUDE.md 或 rules 重叠 | `/context` 看实际加载顺序 |
| `AGENTS.md` 不生效 | 当前版本或配置未启用原生读取 | 用 `CLAUDE.md` 导入或核对原生支持 |
| 大仓库规则太多 | 上下文被说明吃满 | 拆成 path-scoped rules |

## 官方参考

- [How Claude remembers your project](https://code.claude.com/docs/en/memory.md)
- [Explore the .claude directory](https://code.claude.com/docs/en/claude-directory.md)
- [Debug your configuration](https://code.claude.com/docs/en/debug-your-config.md)