古法编程

Appearance

Claude Code 每次会话都从空上下文开始，但两种机制让知识跨会话传递：CLAUDE.md（你写的持久指令，按目录层级自动加载）和 Auto Memory（Claude 根据你的纠正自动写入的笔记）。CLAUDE.md 支持 @import 导入其他文件、.claude/rules/ 路径限定规则、AGENTS.md 别名兼容，以及 #include 等高级语法。本文详细介绍两种机制的区别、配置方法，以及如何利用它们让 Claude 在不同项目中保持一致的行为风格。

记忆系统：让 Claude 记住你的项目 ​

Claude Code 的每次会话都从一个全新的上下文开始，但有两种机制可以让知识跨会话传递：

  • CLAUDE.md 文件：你写的持久指令，每次会话开始时自动读取
  • 自动记忆（Auto Memory）：Claude 根据你的纠正和偏好自动写入的笔记

CLAUDE.md vs 自动记忆 ​

CLAUDE.md 文件自动记忆
谁来写你Claude
内容指令和规则发现和模式
范围项目、用户或组织每个工作目录
加载时机每次会话开始每次会话开始（前 200 行或 25KB）
用于编码规范、工作流程、项目架构构建命令、调试发现、Claude 发现的偏好

子代理也可以维护独立的自动记忆，详见子代理配置。

CLAUDE.md 文件 ​

CLAUDE.md 文件是给 Claude 持久指令的 Markdown 文件，适用于项目、个人工作流或整个组织。用纯文本编写，Claude 在每次会话开始时读取。

何时添加到 CLAUDE.md ​

把 CLAUDE.md 当成你会反复重新解释的内容的存放地。在以下情况时添加：

  • Claude 犯了同一个错误第二次
  • 代码审查发现了 Claude 本应了解的项目知识
  • 你在聊天中输入了上次会话也输入过的同样的纠正或说明
  • 新队友需要同样的上下文才能高效工作

只保留 Claude 在每次会话中都需要掌握的事实：构建命令、约定、项目布局、"始终做 X"的规则。如果是多步骤流程或只在某个代码区域才相关的内容，移到 skill 或路径限定规则中。

选择 CLAUDE.md 的位置 ​

CLAUDE.md 可以放在多个位置，每个位置有不同的作用域。更具体的位置优先于范围更广的位置。

范围位置用途示例共享对象
托管 policymacOS：/Library/Application Support/ClaudeCode/CLAUDE.md
Linux/WSL：/etc/claude-code/CLAUDE.md
Windows：C:\Program Files\ClaudeCode\CLAUDE.md		由 IT/DevOps 管理的组织统一指令公司编码标准、安全策略、合规要求组织所有用户
项目指令./CLAUDE.md 或 ./.claude/CLAUDE.md团队共用的项目级说明项目架构、编码规范、常见工作流通过源代码管理共享给团队
用户指令~/.claude/CLAUDE.md适用于所有项目的个人偏好代码风格偏好、个人工具快捷方式只有你（所有项目）
本地指令./CLAUDE.local.md个人项目专属偏好，加入 .gitignore沙箱 URL、首选测试数据只有你（当前项目）

编写有效的指令 ​

CLAUDE.md 文件在每次会话开始时加载到上下文窗口，与对话一起消耗 token。由于它们是上下文而不是强制配置，写法会影响 Claude 遵守的可靠性。具体、简洁、结构良好的指令效果最好。

大小：每个 CLAUDE.md 文件目标控制在 200 行以内。文件越长，上下文消耗越多，遵守率越低。

结构：用 Markdown 标题和列表组织。Claude 扫描结构的方式和读者一样——有组织的分节比密集段落更容易遵守。

具体性：写出具体可验证的指令，例如：

  • "使用 2 空格缩进"而不是"正确格式化代码"
  • "提交前运行 npm test"而不是"测试你的改动"
  • "API 处理器放在 src/api/handlers/"而不是"保持文件有组织"

一致性：如果两条规则互相矛盾，Claude 可能随机选一条。定期检查 CLAUDE.md、子目录中的嵌套 CLAUDE.md 和 .claude/rules/ 文件，删除过时或冲突的指令。

可以加强关键指令的力度（如 "重要：" 或 "你必须："）以提高遵守率。把 CLAUDE.md 提交到 git，让团队共同贡献，这个文件的价值会随时间增长。

好的 CLAUDE.md 示例：

markdown
# 代码风格
- 使用 ES modules (import/export)，不用 CommonJS (require)
- 尽量使用解构导入（如 import { foo } from 'bar'）

# 工作流程
- 做完一系列代码改动后记得做类型检查
- 优先运行单个测试，不要跑整个测试套件，性能更好

引入外部文件 ​

CLAUDE.md 文件可以用 @path/to/import 语法引入额外文件。被引入的文件在会话开始时随 CLAUDE.md 一起展开加载到上下文中。支持相对路径和绝对路径。相对路径相对于包含 import 的文件解析，而不是工作目录。引入文件可以递归引入其他文件，最多嵌套 5 层。

markdown
参见 @README.md 了解项目概述，@package.json 了解可用 npm 命令。

# 额外说明
- Git 工作流：@docs/git-instructions.md
- 个人偏好：@~/.claude/my-project-instructions.md

如果想要不提交到版本库的个人项目偏好，在项目根目录创建 CLAUDE.local.md，它和 CLAUDE.md 一起加载，效果相同。把 CLAUDE.local.md 加入 .gitignore；运行 /init 并选择个人选项时会自动完成这一步。

如果你在同一仓库的多个 git worktree 中工作，gitignored 的 CLAUDE.local.md 只存在于你创建它的 worktree 中。要跨 worktree 共享个人指令，改为从主目录引入：

markdown
# 个人偏好
- @~/.claude/my-project-instructions.md

AGENTS.md 兼容 ​

Claude Code 读取 CLAUDE.md，不读取 AGENTS.md。如果你的仓库已经在用 AGENTS.md（供其他编程代理使用），可以创建一个引入它的 CLAUDE.md，让两个工具读取相同的指令而不重复维护。在引入下面还可以加 Claude 专属指令：

markdown
@AGENTS.md

## Claude Code 专属

在 `src/billing/` 下的改动使用计划模式。

CLAUDE.md 如何加载 ​

Claude Code 从当前工作目录向上遍历目录树，在沿途每个目录中查找 CLAUDE.md 和 CLAUDE.local.md 文件。如果你在 foo/bar/ 中运行 Claude Code，它会加载 foo/bar/CLAUDE.md、foo/CLAUDE.md 以及它们旁边的 CLAUDE.local.md 文件。所有找到的文件被拼接进上下文，而不是相互覆盖。在每个目录内，CLAUDE.local.md 追加在 CLAUDE.md 之后，所以当指令冲突时，你的个人笔记是 Claude 在该层级读到的最后内容。

Claude 也会发现当前工作目录的子目录下的 CLAUDE.md 和 CLAUDE.local.md 文件，但不在启动时加载，而是当 Claude 读取那些子目录的文件时才引入。

CLAUDE.md 文件中的块级 HTML 注释（<!-- 维护者笔记 -->）在注入到 Claude 上下文前会被去掉。用它们给人类维护者留注释，而不会消耗上下文 token。代码块内的注释不受影响。

用 .claude/rules/ 组织规则 ​

对于大型项目，可以用 .claude/rules/ 目录把指令组织到多个文件。这使指令模块化，团队更容易维护。规则还可以限定到特定文件路径，只在 Claude 处理匹配文件时才加载。

设置规则 ​

在项目的 .claude/rules/ 目录中放 Markdown 文件。每个文件覆盖一个主题，文件名要描述性，如 testing.md 或 api-design.md：

your-project/
├── .claude/
│   ├── CLAUDE.md          # 主项目说明
│   └── rules/
│       ├── code-style.md  # 代码风格规范
│       ├── testing.md     # 测试约定
│       └── security.md    # 安全要求

没有路径限定 frontmatter 的规则在启动时加载，优先级与 .claude/CLAUDE.md 相同。

路径限定规则 ​

规则可以用 YAML frontmatter 的 paths 字段限定作用范围。这些条件规则只在 Claude 处理匹配指定模式的文件时才应用：

markdown
---
paths:
  - "src/api/**/*.ts"
---

# API 开发规则

- 所有 API 接口必须包含输入验证
- 使用标准错误响应格式
- 包含 OpenAPI 文档注释

没有 paths 字段的规则无条件加载，适用于所有文件。路径限定规则在 Claude 读取匹配模式的文件时触发，而不是在每次工具使用时触发。

paths 字段支持的 glob 模式：

模式匹配
**/*.ts任意目录的所有 TypeScript 文件
src/**/*src/ 目录下的所有文件
*.md项目根目录的 Markdown 文件
src/components/*.tsx特定目录的 React 组件

可以指定多个模式，并用大括号扩展匹配多个扩展名：

markdown
---
paths:
  - "src/**/*.{ts,tsx}"
  - "lib/**/*.ts"
  - "tests/**/*.test.ts"
---

用户级规则 ​

~/.claude/rules/ 中的个人规则适用于你机器上的每个项目：

~/.claude/rules/
├── preferences.md  # 你的个人编码偏好
└── workflows.md    # 你的首选工作流

用户级规则在项目规则之前加载，项目规则优先级更高。

自动记忆（Auto Memory） ​

自动记忆让 Claude 在会话之间自动积累知识，你不需要手动写任何东西。Claude 会保存：构建命令、调试发现、架构说明、代码风格偏好、工作流习惯等。

开关自动记忆 ​

自动记忆默认开启。要关闭：

json
// .claude/settings.json
{
  "autoMemoryEnabled": false
}

也可以设置环境变量 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1。

在会话中运行 /memory 可以切换开关、查看和编辑记忆内容，或启用/禁用自动记忆。

记忆存储在哪里 ​

每个项目有独立的记忆目录：~/.claude/projects/<project>/memory/

~/.claude/projects/<project>/memory/
├── MEMORY.md          # 简洁索引，每次会话都加载（前 200 行）
├── debugging.md       # 调试发现的详细笔记
├── api-conventions.md # API 设计决策
└── ...                # Claude 创建的其他主题文件

MEMORY.md 是入口文件，每次会话开始时加载前 200 行（或 25KB）。详细内容存在其他主题文件里，按需读取。

自动记忆是机器本地的，不会跨机器或云端环境共享。同一 git 仓库下的所有工作树共用一个记忆目录。

告诉 Claude 记住某件事 ​

始终使用 pnpm，不要用 npm
记住：API 测试需要本地 Redis 实例

Claude 会把这些保存到自动记忆中。如果你想添加到 CLAUDE.md 而不是自动记忆，直接说"把这个加到 CLAUDE.md"。

常见问题排查 ​

Claude 不遵守 CLAUDE.md 的指令？

  • 运行 /memory 确认文件被加载了
  • 检查 CLAUDE.md 是否放在正确位置
  • 把指令写得更具体："使用 2 空格缩进"而不是"格式化代码"
  • 检查是否有冲突的指令
  • 检查 CLAUDE.md 是否过长（超过 200 行会降低遵守率）

不知道自动记忆保存了什么？

  • 运行 /memory，选择自动记忆目录，所有内容都是可读的 Markdown

/compact 之后指令丢失了？

  • CLAUDE.md 在压缩后完全保留，Claude 会从磁盘重新读取
  • 如果某条指令在压缩后消失了，说明它只存在于对话中，没写进 CLAUDE.md

在 monorepo 中加载了不相关的 CLAUDE.md？

  • 使用设置中的 claudeMdExcludes 跳过其他团队的 CLAUDE.md 文件

相关资源 ​

  • Skills：打包可按需加载的可复用工作流
  • 设置：用设置文件配置 Claude Code 行为
  • 子代理记忆：让子代理维护独立的自动记忆
  • 最佳实践：写有效 CLAUDE.md 的技巧

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策