Claude Code记忆系统

秋堂主2026-05-14 13:51

目录

  • [1 核心架构：双层记忆体系](#1 核心架构：双层记忆体系)
    • [1.1 CLAUDE.md(手动记忆) vs auto memory(自动记忆)](#1.1 CLAUDE.md(手动记忆) vs auto memory(自动记忆))
  • [2 CLAUDE.md 文件（手动记忆）](#2 CLAUDE.md 文件（手动记忆）)
    • [2.1 何时添加CLAUDE.md](#2.1 何时添加CLAUDE.md)
    • [2.2 配置项目级 CLAUDE.md](#2.2 配置项目级 CLAUDE.md)
      • [2.2.1 使用/init 自动生成初始 CLAUDE.md](#2.2.1 使用/init 自动生成初始 CLAUDE.md)
    • [2.3 编写高效指令指南](#2.3 编写高效指令指南)
    • [2.4 导入外部文件](#2.4 导入外部文件)
    • [2.5 关于 AGENTS.md 的兼容性说明](#2.5 关于 AGENTS.md 的兼容性说明)
    • [2.6 CLAUDE.md 文件的加载机制](#2.6 CLAUDE.md 文件的加载机制)
      • [2.6.1 从其他目录加载](#2.6.1 从其他目录加载)
    • [2.7 使用 .claude/rules/ 目录组织规则](#2.7 使用 .claude/rules/ 目录组织规则)
      • [2.7.1 配置规则](#2.7.1 配置规则)
      • [2.7.2 特定路径的规则限定](#2.7.2 特定路径的规则限定)
      • [2.7.3 使用符号链接跨项目共享规则](#2.7.3 使用符号链接跨项目共享规则)
      • [2.7.4 用户级规则](#2.7.4 用户级规则)
    • [2.8 为大型团队管理 CLAUDE.md](#2.8 为大型团队管理 CLAUDE.md)
    • [2.9 排除特定的 CLAUDE.md 文件](#2.9 排除特定的 CLAUDE.md 文件)
  • [3 Auto memory(自动记忆)](#3 Auto memory(自动记忆))
    • [3.1 启用或禁用自动记忆](#3.1 启用或禁用自动记忆)
    • [3.2 存储位置](#3.2 存储位置)
    • [3.3 如何高效读取？索引 + 按需加载](#3.3 如何高效读取？索引 + 按需加载)
  • [4 故障排查：自动记忆与 CLAUDE.md 相关问题](#4 故障排查：自动记忆与 CLAUDE.md 相关问题)
    • [4.1 问题：Claude 未遵循我的 CLAUDE.md 指令](#4.1 问题：Claude 未遵循我的 CLAUDE.md 指令)
    • [4.2 我不知道自动记忆保存了什么](#4.2 我不知道自动记忆保存了什么)

Claude Code 记忆系统 ------ 带你认识两种记忆核心概念

Claude Code 作为 CLI 编程助手，每次启动新会话时，模型面对的是一个全新的上下文窗口。如果没有记忆系统，它不知道你的项目技术栈、你的代码风格偏好，或是上次修复了哪个 Bug。这意味着每次都需要花费大量时间"教育"AI，这在复杂项目上是巨大的效率损耗和 Token 浪费。

1 核心架构：双层记忆体系

在Claude Code中，记忆是指跨会话持续存在的上下文。与每次重置的对话窗口不同，记忆文件会在每次启动Claude Code时自动加载。使用 CLAUDE.md 文件为 Claude 提供持久指令，并让 Claude 通过自动记忆功能自动积累学习内容。

Claude Code 的记忆系统是其作为 AI 编程助手最核心的机制之一。由于 LLM 本身是无状态的，每次启动新会话时，模型面对的都是一个全新的上下文窗口，完全不记得上次做过什么。为了解决这种"记忆断裂"问题，Claude Code 构建了一套精巧的持久化记忆架构，让 AI 能够跨会话地"记住"项目规范、用户偏好和踩坑经验。

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

  • CLAUDE.md 文件(手动记忆)：你编写的指令，为 Claude 提供持久上下文
  • Auto memory(自动记忆)：Claude 根据你的更正和偏好自己编写的笔记。

1.1 CLAUDE.md(手动记忆) vs auto memory(自动记忆)

Claude Code 配备了两个相辅相成的记忆系统，它们均会在每次对话启动时自动加载。请注意，Claude 将这些内容视为上下文参考，而非强制执行配置。因此，你的指令越具体、精炼，Claude 遵循的一致性就越高。

维度 CLAUDE.md 文件 自动记忆
编写者 你（开发者） Claude 自动生成
包含内容 指令、规则、项目架构 学习心得、调试见解、行为纠正
作用范围 项目、用户或组织 每个存储库，跨工作树共享
加载限制 整体加载（消耗上下文） 前 200 行或 25KB
是否提交Git 是（团队共享） 否（个人私有，存在本地）

当你需要主动指导 Claude 的行为时，请使用 CLAUDE.md 文件。而自动记忆功能则能让 Claude 从你的纠正中自主学习，整个过程无需手动干预。

可以把 CLAUDE.md 想象成项目的"正式规章制度"，而 Auto Memory 则是 Claude 给自己贴的"便利贴和工作笔记"。

2 CLAUDE.md 文件（手动记忆）

这是用户手动编写 的持久指令，相当于"项目说明书"。Claude Code 在每次会话启动时自动读取这些文件，并将内容注入到上下文窗口中。四个作用域层级（按优先级从低到高）

层级 说明
企业级 macOS: /Library/Application Support/ClaudeCode/CLAUDE.md 、Linux 和 WSL: /etc/claude-code/CLAUDE.md 、Windows: C:\Program Files\ClaudeCode\CLAUDE.md，由 IT/DevOps 管理的组织范围指令，适用于公司编码标准、安全策略等。
用户级 ~/.claude/CLAUDE.md，个人全局偏好
项目级 ./CLAUDE.md 或 ./.claude/CLAUDE.md，团队共享约定（提交到 git）
本地级 ./CLAUDE.local.md，个人项目偏好（加入到 gitignore）

注入机制 ：CLAUDE.md 并非拼接到 system prompt 中，而是通过 prependUserContext() 函数注入到消息列表的最前面，作为一条特殊的 user message。这意味着它会消耗实际的输入 token，因此写法上需要越短越好、结构化、可执行。

2.1 何时添加CLAUDE.md

请将 CLAUDE.md 视为核心文档，用于记录那些"原本需要反复向 AI 解释的背景知识"。建议在以下场景创建或更新该文件：

  • 当 Claude 第二次犯同样的错误时；
  • 当代码审查发现 Claude 缺乏对当前代码库的关键认知时；
  • 当你在对话中需要重复输入与上个会话完全相同的更正或澄清时；
  • 当新队友加入，需要同样的上下文背景来提升开发效率时。

建议将 CLAUDE.md 严格限定为 Claude 在每次会话中都必须遵循的全局事实，例如构建命令、开发约定、项目布局以及"始终执行 X"的通用规则。

如果某项内容涉及多步骤流程，或仅适用于代码库的特定部分，请将其移至 Skill 或 路径范围规则 中。

2.2 配置项目级 CLAUDE.md

项目级的 CLAUDE.md 文件可存放于项目根目录（./CLAUDE.md）或 .claude 子目录下（./.claude/CLAUDE.md）。请创建该文件，并纳入适用于所有项目贡献者的通用指令，例如构建与测试命令、编码规范、架构决策、命名约定及常见工作流。由于该文件将通过版本控制系统与团队共享，请确保内容聚焦于项目级标准，而非个人偏好。

2.2.1 使用/init 自动生成初始 CLAUDE.md

执行 /init 命令可自动生成基础的 CLAUDE.md 文件。Claude 会自动分析你的代码库，并创建包含构建命令、测试指令以及识别到的项目约定的文件。若 CLAUDE.md 已存在，/init 将提供改进建议而非直接覆盖，你只需在此基础上进行细化，补充 Claude 未能自动识别的特定指令即可。

如需启用交互式多阶段流程，请设置环境变量 CLAUDE_CODE_NEW_INIT=1。在此模式下，/init 会引导你选择需要配置的工件（包括 CLAUDE.md 文件、Skills 和 Hooks）。随后，它将调用子代理（subagent）深入探索你的代码库，通过后续提问填补信息空白，并在实际写入任何文件之前，向你展示可供审查的完整提案。

2.3 编写高效指令指南

CLAUDE.md 文件会在每次会话开始时加载至上下文窗口，并与你的对话共同占用token额度（可通过上下文窗口可视化功能查看其具体位置）。由于这些指令属于上下文提示而非强制性的系统配置，其编写方式将直接影响 Claude 遵循指令的可靠性。通常，具体、简洁且结构良好的指令效果最佳。

篇幅控制 ：建议将每个 CLAUDE.md 文件控制在 200 行以内。过长的文件不仅会消耗更多上下文资源，还会降低指令的遵守度。如果指令内容过于庞大，建议使用路径范围规则 ，确保指令仅在 Claude 处理匹配文件时才被加载。此外，你也可以将内容拆分为导入文件以便于组织，但需注意，导入的文件同样会在启动时加载并计入上下文窗口。

结构优化 ：请使用 Markdown 标题和项目符号来分组相关指令。Claude 扫描文档的方式与人类读者一致：结构清晰的分段远比密集的文字段落更易于理解和遵循。

具体明确：指令应具体到足以被验证和执行的程度。例如：

  • 使用"使用 2 空格缩进"，而非"正确格式化代码"；
  • 使用"在提交前运行 npm test"，而非"测试你的更改"；
  • 使用"API 处理程序位于 src/api/handlers/"，而非"保持文件有组织"。

保持一致性 ：如果存在相互矛盾的规则，Claude 可能会随机选择其中一条执行。请定期审查你的 CLAUDE.md 文件、子目录中嵌套的 CLAUDE.md 以及 .claude/rules/ 目录，及时剔除过时或冲突的指令。在 Monorepo（单体仓库）环境中，建议使用 claudeMdExcludes 配置，跳过与当前工作无关的其他团队的 CLAUDE.md 文件。

2.4 导入外部文件

CLAUDE.md 文件支持使用 @path/to/import 语法引入其他文件。被导入的文件会在会话启动时展开，并与引用它们的 CLAUDE.md 一同加载至上下文窗口中。

路径与层级规则 ：系统支持相对路径和绝对路径。其中，相对路径是相对于包含导入语句的文件进行解析，而非当前工作目录。导入支持递归嵌套，最大深度为五层。你可以在 CLAUDE.md 的任意位置使用 @ 语法来引入 README、package.json 或工作流指南等文档。

复制代码 
有关项目概述，请参阅 @README，有关此项目的可用 npm 命令，请参阅 @package.json。

# 其他指令
- git 工作流 @docs/git-instructions.md

本地私人偏好配置 ：对于不想提交到版本控制的私人项目偏好，你可以在项目根目录创建 CLAUDE.local.md。该文件会与 CLAUDE.md 一同加载并遵循相同的处理规则。请务必将 CLAUDE.local.md 添加到 .gitignore 中以防误提交（运行 /init 并选择个人配置选项时，系统会自动为你完成此操作）。

多 Worktree 共享 ：如果你在同一仓库的多个 git worktree 中工作，被 .gitignore 忽略的 CLAUDE.local.md 仅存在于你创建它的那个 worktree 中。若需在多个 worktree 间共享个人指令，建议改为从你的主目录（Home Directory）导入文件。

2.5 关于 AGENTS.md 的兼容性说明

Claude Code 默认读取 CLAUDE.md 文件，而非 AGENTS.md。如果你的代码仓库已为其他编码代理配置了 AGENTS.md，建议创建一个 CLAUDE.md 文件并直接导入 AGENTS.md。这样，两个工具即可共享同一套指令，无需重复维护。

你可以在导入语句下方继续添加 Claude 专属的特定指令。Claude 会在会话开始时首先加载被导入的文件（如 AGENTS.md），随后再加载 CLAUDE.md 中的其余内容。

markdown 复制代码 
@AGENTS.md

## Claude Code

对 `src/billing/` 下的更改使用 Plan Mode。

若在已存在 AGENTS.md 的代码仓库中运行 /init，系统将自动读取该文件，并将其中的相关内容合并至新生成的 CLAUDE.md 中。此外，该命令还会自动识别并读取其他工具的配置文件，例如 .cursorrules 和 .windsurfrules。

2.6 CLAUDE.md 文件的加载机制

Claude Code 通过从当前工作目录（CWD）向上遍历目录树来读取 CLAUDE.md 文件，并检查沿途每个目录是否存在 CLAUDE.md 和 CLAUDE.local.md。例如，如果你在 foo/bar/ 目录下运行 Claude Code，它将依次加载 foo/bar/CLAUDE.md、foo/CLAUDE.md 以及沿途发现的所有 CLAUDE.local.md 文件。

所有被发现的配置文件都会被合并到上下文中，而非相互覆盖。在目录树结构中，内容按照从文件系统根目录到当前工作目录的顺序进行排列。以 foo/bar/ 为例，foo/CLAUDE.md 的内容会先于 foo/bar/CLAUDE.md 被加载，这意味着距离你启动 Claude 位置越近的指令，在上下文中越靠后（即具有更高的上下文优先级）。在同一目录下，CLAUDE.local.md 会追加在 CLAUDE.md 之后，因此你的个人笔记将是 Claude 在该层级读取的最后内容。

此外，Claude 也会识别当前工作目录下的子目录中的 CLAUDE.md 和 CLAUDE.local.md 文件。这些文件不会在启动时立即加载，而是在 Claude 读取对应子目录中的文件时按需包含。

如果你在大型 Monorepo（单体仓库）中工作，为了避免加载其他团队无关的 CLAUDE.md 文件，建议使用 claudeMdExcludes 配置进行排除。

关于 HTML 注释的处理 ：块级 HTML 注释（如 <!-- maintainer notes -->）在 CLAUDE.md 内容注入到 Claude 的上下文之前会被自动剥离。你可以利用这一点为人类维护者留下备注，从而节省上下文令牌。但请注意，代码块内部的注释会被保留。当你直接使用 Read 工具打开 CLAUDE.md 文件时，这些注释依然可见。

2.6.1 从其他目录加载

使用 --add-dir 标志可使 Claude 访问主工作目录之外的其他目录。但请注意，默认情况下，系统不会加载这些额外目录中的 CLAUDE.md 文件。

若需从这些额外目录中一并加载记忆文件（如 CLAUDE.md），请设置 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD 环境变量。

复制代码 
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

启用该选项后，系统将从额外目录中加载 CLAUDE.md、.claude/CLAUDE.md、.claude/rules/*.md 以及 CLAUDE.local.md。请注意，如果你在 --setting-sources 中排除了 local，则 CLAUDE.local.md 文件将会被跳过。

2.7 使用 .claude/rules/ 目录组织规则

对于大型项目，你可以利用 .claude/rules/ 目录将指令拆分为多个独立的文件。这种模块化的管理方式不仅使指令结构更清晰，也极大地方便了团队的协同维护。此外，这些规则还可以限定于特定的文件路径，确保它们仅在 Claude 处理匹配文件时才被加载到上下文中，从而有效减少干扰并节省宝贵的上下文空间。

规则文件会在每次会话启动或打开匹配文件时自动加载到上下文中。对于那些不需要始终驻留在上下文中的特定任务指令，建议改用 Skills。Skills 仅在你显式调用，或 Claude 判定其与当前提示高度相关时才会被加载，从而有效节省上下文空间。

2.7.1 配置规则

请在项目的 .claude/rules/ 目录下创建 Markdown 文件。每个文件应聚焦于一个特定的主题，并采用具有描述性的文件名，例如 testing.md 或 api-design.md。系统会递归发现所有的 .md 文件，因此你可以将规则进一步组织到子目录中（如 frontend/ 或 backend/），以保持结构清晰。

复制代码 
your-project/
├── .claude/
│   ├── CLAUDE.md           # 主项目指令
│   └── rules/
│       ├── code-style.md   # 代码样式指南
│       ├── testing.md      # 测试约定
│       └── security.md     # 安全要求

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

2.7.2 特定路径的规则限定

规则可以通过包含 paths 字段的 YAML frontmatter，被限定在特定的文件范围内。此类条件规则仅在 Claude 处理与指定模式相匹配的文件时才会生效。

复制代码 
---
paths:
  - "src/api/**/*.ts"
---

# API 开发规则

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

若规则未包含 paths 字段，则会被无条件加载并适用于所有文件。而带有路径范围限定的规则，仅会在 Claude 读取与指定模式匹配的文件时触发，并非在每次工具调用时生效。

你可以在 paths 字段中使用 glob 模式，通过文件扩展名、目录路径或任意组合来精确匹配目标文件。

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

你可以指定多个匹配模式，或者在单个模式中使用大括号扩展（brace expansion），以同时匹配多种文件扩展名。

复制代码 
---
paths:
  - "src/**/*.{ts,tsx}"
  - "lib/**/*.ts"
  - "tests/**/*.test.ts"
---

2.7.3 使用符号链接跨项目共享规则

.claude/rules/ 目录完全支持符号链接，这意味着你可以维护一套统一的共享规则，并将其链接到多个不同的项目中。系统能够正常解析并加载这些符号链接，同时会自动检测并妥善处理循环符号链接，确保运行稳定。

以下示例展示了如何同时链接一个共享目录和一个单独的规则文件：

复制代码 
ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.md

2.7.4 用户级规则

位于 ~/.claude/rules/ 目录下的个人规则，将全局应用于你机器上的所有项目。建议在此处配置那些非项目专属的通用偏好设置，~ 代表你的用户主目录：

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

2.8 为大型团队管理 CLAUDE.md

对于在团队中部署 Claude Code 的组织，你可以对指令进行集中管理，并严格控制哪些 CLAUDE.md 文件会被加载。

2.8.1 部署组织范围的 CLAUDE.md

组织可以部署一份集中管理的 CLAUDE.md 文件，该文件将强制应用于机器上的所有用户。请注意，此文件具有最高优先级，无法被个人设置排除或覆盖。

  1. 在托管策略位置创建文件
    • macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
    • Linux 和 WSL: /etc/claude-code/CLAUDE.md
    • Windows: C:\Program Files\ClaudeCode\CLAUDE.md
  2. 使用配置管理系统进行部署
    • 请利用 MDM、Group Policy、Ansible 或类似的配置管理工具，将文件分发至开发者的机器上。
      claudeMd 键允许你将托管的 CLAUDE.md 内容直接嵌入 managed-settings.json 中，从而无需单独部署文件。
  • 作用范围 ：覆盖本机上的所有 Claude Code 会话及所有代码仓库。若需针对特定仓库进行指导，请直接提交项目级的 CLAUDE.md。
  • 加载优先级 ：与托管 CLAUDE.md 文件相同，会在用户级和项目级 CLAUDE.md 之前加载。
  • 生效条件 ：仅在托管和策略设置中有效。在用户、项目或本地设置中配置 claudeMd 将被忽略。

以下示例展示了如何直接在托管设置文件中添加行为指令：

json 复制代码 
{
  "claudeMd": "Always run `make lint` before committing.\nNever push directly to main."
}

托管 CLAUDE.md 和托管设置服务于不同的目的。建议利用托管设置进行技术层面的强制约束，而使用 CLAUDE.md 进行行为层面的指导规范：

关注点 配置在
阻止特定工具、命令或文件路径 托管设置：permissions.deny
强制沙箱隔离 托管设置：sandbox.enabled
环境变量和 API 提供商路由 托管设置：env
身份验证方法和组织锁定 托管设置：forceLoginMethod、forceLoginOrgUUID
代码样式和质量指南 托管 CLAUDE.md
数据处理和合规提醒 托管 CLAUDE.md
Claude 的行为指令 托管 CLAUDE.md

设置规则由客户端强制执行，具有最高约束力，不受 Claude 决策的影响。相比之下，CLAUDE.md 中的指令旨在塑造 Claude 的行为模式，但并不构成硬性强制层。

2.9 排除特定的 CLAUDE.md 文件

在大型 Monorepo（单体仓库）中，来自祖先目录的 CLAUDE.md 文件可能包含与当前工作无关的冗余指令。claudeMdExcludes 设置允许你通过指定路径或 glob 模式来跳过特定的文件。

以下示例展示了如何排除位于仓库根目录的 CLAUDE.md 以及来自父级文件夹的规则目录。建议将其添加到 .claude/settings.local.json 中，以确保该排除规则仅在当前机器上本地生效：

复制代码 
{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

模式匹配采用 glob 语法，并与绝对文件路径进行比对。你可以在任意设置层（包括用户、项目、本地或托管策略）配置 claudeMdExcludes，且数组配置会在各层之间自动合并。

请注意，托管策略中的 CLAUDE.md 文件无法被排除。这一机制确保了组织范围的指令始终有效，不受任何个人设置的影响。

3 Auto memory(自动记忆)

自动记忆需要 Claude Code v2.1.59 或更高版本。使用 claude --version 检查你的版本。自动记忆让 Claude 跨会话积累知识，无需你编写任何内容。Claude 在工作时为自己保存笔记：构建命令、调试见解、架构笔记、代码样式偏好和工作流习惯。Claude 不会每个会话都保存内容。它根据信息在未来对话中是否有用来决定什么值得记住。

这是 Claude Code 最有技术含量的部分。AI 自己能从对话中提取值得记住的信息 ，并自动写入记忆文件。两种触发方式如下表所示：

触发方式 说明
用户明确要求 你说"Claude，记住我喜欢用 tabs 缩进"，AI 直接写文件
AI 主动提取 每轮对话结束后，后台会 fork 一个子 Agent，分析有没有值得跨会话保留的信息

3.1 启用或禁用自动记忆

自动记忆默认开启。要切换它，在会话中打开 /memory 并使用自动记忆切换，或在你的项目设置中设置 autoMemoryEnabled：

json 复制代码 
{
  "autoMemoryEnabled": false
}

要通过环境变量禁用自动记忆，设置 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1。

3.2 存储位置

  • 这些自动生成的记忆文件存储在你个人用户目录下的 ~/.claude/projects/<项目路径>/memory/ 中。它们是私有的，不会提交到项目仓库，仅在你本机的这个项目中生效。如下图所示：

  • 目录包含一个 MEMORY.md 入口点和可选的主题文件，MEMORY.md 充当记忆目录的索引。Claude 在你的会话中读取和写入此目录中的文件，使用 MEMORY.md 跟踪存储的内容。

    ~/.claude/projects/<project>/memory/
    ├── MEMORY.md # 简洁索引，加载到每个会话
    ├── debugging.md # 关于调试模式的详细笔记
    ├── api-conventions.md # API 设计决策
    └── ... # Claude 创建的任何其他主题文件

  • 要将自动记忆存储在不同位置，在你的用户设置 ~/.claude/settings.json 中设置 autoMemoryDirectory：

json 复制代码 
{
  "autoMemoryDirectory": "~/my-custom-memory-dir"
}

3.3 如何高效读取？索引 + 按需加载

为了避免海量记忆撑爆上下文窗口，系统采用了巧妙的"索引"机制：

  1. 索引文件 (MEMORY.md) ：系统会维护一个轻量级的 MEMORY.md 索引文件，它只包含所有记忆的标题和摘要，并且严格限制大小（如前 200 行或 25KB），此限制仅适用于 MEMORY.md， CLAUDE.md 文件无论长度如何都完整加载。每次新会话启动时，这个索引文件会始终被加载，让 Claude Code 知道有哪些记忆可用。
  2. 智能召回：当需要时，系统会先用一个轻量级模型扫描索引，选出与当前任务最相关的几条记忆。
  3. 按需加载 ：只有在确定某条记忆相关后，才会去加载其完整的 .md 文件内容，注入到当前对话中。

4 故障排查：自动记忆与 CLAUDE.md 相关问题

本节汇总了关于 CLAUDE.md 配置文件(手动记忆)及自动记忆功能最常见的问题，并提供了相应的调试步骤。

4.1 问题：Claude 未遵循我的 CLAUDE.md 指令

原因分析：
CLAUDE.md 的内容是作为"用户消息"在系统提示（System Prompt）之后传递给 Claude 的，而非系统提示本身的一部分。虽然 Claude 会读取并尝试遵循其中的内容，但无法保证绝对严格遵守，特别是当指令模糊或存在冲突时。

调试与解决方案：

  1. 验证文件加载状态

    运行 /memory 命令，检查你的 CLAUDE.md 和 CLAUDE.local.md 文件是否被正确列出。如果文件未出现在列表中，说明 Claude 当前无法读取到它。

  2. 检查文件路径位置

    确认相关的 CLAUDE.md 文件是否位于当前会话能够加载的正确目录下（详情请参考"选择 CLAUDE.md 文件的位置"章节）。

  3. 优化指令的具体性

    尽量使指令明确且具体。例如，使用"使用 2 空格缩进"比笼统的"代码格式化要美观"效果要好得多。

  4. 排查指令冲突

    检查是否存在跨 CLAUDE.md 文件的指令冲突。如果多个文件对同一行为提供了不同的指导，Claude 可能会随机选择其中一种执行。

  5. 使用 Hooks 处理固定流程

    如果某些指令需要在特定时机强制运行（例如每次提交代码前或每次编辑文件后），建议将其编写为 Hooks。Hooks 会在固定的生命周期事件中作为 Shell 命令执行，其执行不受 Claude 决策过程的影响。

  6. 使用系统提示追加参数

    对于需要达到系统提示（System Prompt）级别的指令，请使用 --append-system-prompt 参数。由于该参数需要在每次调用时传递，因此它更适合用于脚本编写和自动化任务，而非交互式使用。

    利用 InstructionsLoaded hook 来记录指令文件的具体加载详情，包括加载的文件、时间以及原因。这对于排查特定路径规则或子目录中延迟加载文件的相关问题极具价值。

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

运行 /memory 命令并选择自动记忆文件夹，即可浏览 Claude 保存的所有内容。所有数据均以纯 Markdown 格式存储，你可以随时读取、编辑或删除。

我的 CLAUDE.md 文件太大了

超过 200 行的文件不仅会消耗大量上下文窗口，还可能导致 Claude 对指令的遵循度下降。建议采取以下优化措施：

  • 使用路径范围规则，仅在 Claude 处理匹配文件时才加载相关指令。
  • 精简文件内容，剔除那些并非每个会话都必需的冗余信息。
  • 注意 ：虽然将内容拆分到 @path 导入有助于文件组织，但由于导入的文件会在启动时全部加载，因此这并不能减少上下文的占用。

在执行 /compact 后指令似乎丢失了

  • 项目根目录的 CLAUDE.md ：具有持久性。在执行 /compact 后，Claude 会从磁盘重新读取该文件并重新注入到会话中。
  • 子目录中的嵌套 CLAUDE.md：不会自动重新注入。只有当 Claude 再次读取该子目录中的文件时，这些指令才会重新加载。

如果指令在压缩后消失，通常是因为该指令仅存在于对话历史中，或者位于尚未被重新加载的嵌套 CLAUDE.md 中。若希望指令持久生效，请将其添加到项目根目录的 CLAUDE.md 中。

相关推荐
乾坤瞬间2 小时前
【claude code 如何构建 agent 实践1】Agent Loop 永动机与工具扩展机制详解[S02]
claude code·code agent
布朗克1686 小时前
Claude Code 进阶玩法：MCP集成、自定义配置与团队协作
arcgis·claude code
qq_gpp1 天前
【Claude Code】Claude Code 的 Checkpoint 是怎么实现的
checkpoint·claude code·rewind
乾坤瞬间1 天前
【claude code agent 实践7】后台任务机制深度解析: 从S02到S08的演进
claude code·code agent
lunatic71 天前
Claude Code && Codex的安装方法
ai·codex·claude code
且去填词1 天前
Claude Code Skills 实践：从提示词到专业化 AI 开发工作流
人工智能·ai编程·开发·claude code·skills
dozenyaoyida1 天前
Claude Code Token 瓶颈破解：让 AI 编码永不中断的完整方案
token·上下文·claude code·ai记忆
乾坤瞬间2 天前
【claude code agent 实践3】Subagent子智能体机制深度解析：从S02到S04的演进
claude code·code agent
热门推荐
01GitHub 镜像站点02Codex 接入 DeepSeek API 完整配置文档03CC-Switch & Claude 基于 Linux 服务器安装使用指南04【AI】2026 年具身智能模型和世界模型总结05零基础教你claude code 接入 deepseek V406Cursor 接入 DeepSeek‑V4‑Pro 完整指南（2026 实测）07codex app每次打开重连5次Reconnecting问题解决08裂开！ChatGPT 居然开始要手机号验证，附详细解决方法09Windows端Codex接入第三方模型（DeekSeek，BaiLian)10AI科技热点日报 | 2026年5月11日