Claude 如何记住您的项目

• CLAUDE.md 文件：您编写的指令，为 Claude 提供持久上下文。Claude 也可以读取仓库的 AGENTS.md 文件来代替 CLAUDE.md
• 自动记忆：Claude 根据您的更正和偏好自己编写的笔记

• 编写和组织 CLAUDE.md 文件
• 使用现有 AGENTS.md 作为您的项目指令
• 使用 .claude/rules/ 将规则范围限定为特定文件类型
• 配置自动记忆，以便 Claude 自动记笔记
• 故障排除当指令未被遵循时

​

CLAUDE.md 与自动记忆

​

CLAUDE.md 文件

​

何时添加到 CLAUDE.md

• Claude 第二次犯同样的错误
• 代码审查发现 Claude 应该了解的关于此代码库的内容
• 您在聊天中输入的相同更正或澄清是您上一个会话中输入的
• 新队友需要相同的上下文才能提高生产力

​

选择 CLAUDE.md 文件的位置

​

设置项目 CLAUDE.md

​

编写有效的指令

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

• 大小：每个 CLAUDE.md 文件目标在 200 行以下。较长的文件消耗更多上下文并降低遵守度。将仅对代码库的一部分重要的指令移至 path-scoped rules，这样它们仅在 Claude 处理匹配文件时加载。导入 帮助您组织一个长文件，但不会减少其上下文成本，因为导入的文件会与导入它们的 CLAUDE.md 一起加载。
• 结构：使用 markdown 标题和项目符号来分组相关指令。有组织的部分比密集段落更容易让 Claude 遵循。
• 一致性：如果两条指令相互矛盾，Claude 可能会任意选择一条。定期审查您的 CLAUDE.md 文件、子目录中的嵌套 CLAUDE.md 文件和 .claude/rules/，以删除过时或冲突的指令。要让 Claude 为您找到它们，请 运行提示词审计。

​

审计您的指令文件

​

导入其他文件

- API conventions @Design\ Docs/api-conventions.md

See @README for project overview and @package.json for available npm commands for this project.

# Additional Instructions
- git workflow @docs/git-instructions.md

# Individual Preferences
- @~/.claude/my-project-instructions.md

​

CLAUDE.md 文件如何加载

​

从其他目录加载

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

​

使用 .claude/rules/ 组织规则

​

设置规则

your-project/
├── .claude/
│   ├── CLAUDE.md           # Main project instructions
│   └── rules/
│       ├── code-style.md   # Code style guidelines
│       ├── testing.md      # Testing conventions
│       └── security.md     # Security requirements

​

路径特定规则

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

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

• 项目规则：包含该规则所在 .claude 文件夹的目录
• 用户级规则：会话的主工作目录

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

​

规则 frontmatter 参考

​

使用符号链接在项目间共享规则

ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.md

​

用户级规则

~/.claude/rules/
├── preferences.md    # Your personal coding preferences
└── workflows.md      # Your preferred workflows

​

为大型团队管理 CLAUDE.md

​

部署组织范围的 CLAUDE.md

{
  "claudeMd": "Always run `make lint` before committing.\nNever push directly to main."
}

​

排除特定的 CLAUDE.md 文件

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

​

AGENTS.md

​

Claude Code 何时读取 AGENTS.md

• 计数，因此 Claude 读取它们而不是 AGENTS.md：您的工作目录或其上方任何目录中的 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md
• 不计数，并继续与 AGENTS.md 一起加载：您的 ~/.claude/CLAUDE.md、您组织的托管 CLAUDE.md 和 .claude/rules/ 文件

• 在会话开始时：您的工作目录和其上方目录中的每个 AGENTS.md 和 .claude/AGENTS.md。在交互式会话中，您会看到一行，例如 no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md 在对话中
• 当 Claude 在子目录中工作时：当 Claude 使用 Read 工具打开该处的文件且该子目录没有三个 CLAUDE.md 文件中的任何一个时，子目录的 AGENTS.md
• 在每个 AGENTS.md 内：@path 导入被展开，claudeMdExcludes 模式适用，启动时不带项目说明的子代理启动时同样不带这些文件
• 不读取：AGENTS.local.md、AGENTS.override.md 或 .agents/ 目录下的任何内容

​

选择加载哪些说明文件

{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

​

当 AGENTS.md 支持不可用时

• 您使用的是 v2.1.277 之前的 Claude Code 版本
• 您使用 /plugin 禁用了读取 AGENTS.md 的内置插件
• 在某些情况下，这是您从 v2.1.276 或更早版本升级后的第一个会话。Claude 从您的下一个会话开始读取 AGENTS.md

​

AGENTS.md 与 CLAUDE.md 的区别

​

删除早期的 AGENTS.md 解决方案

• 包含 @AGENTS.md 的 CLAUDE.md：您可以保留它。保留导入永远不会让 Claude 读取 AGENTS.md 两次，无论您使用哪个项目说明值。如果 CLAUDE.md 不包含其他内容，请删除它，或如果您的某些会话无法直接加载 AGENTS.md，请保留它。
• 告诉 Claude 用词语读取 AGENTS.md 的 CLAUDE.md：仅当 Claude 决定打开文件时，它才会看到 AGENTS.md。删除 CLAUDE.md 以便 Claude 直接读取 AGENTS.md，或用 @AGENTS.md 导入替换该句子。
• 符号链接到 AGENTS.md 的 CLAUDE.md：无，或删除符号链接。无论哪种方式，Claude 都会读取内容一次。
• 打印 AGENTS.md 的 SessionStart hook：删除它。一旦 Claude 直接读取 AGENTS.md，该 hook 会向上下文添加第二个副本。

​

与其他编码工具共享一个文件

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

ln -s AGENTS.md CLAUDE.md

• 编辑：Claude 通过链接读取 CLAUDE.md，但 Edit 和 Write 工具拒绝通过符号链接写入，拒绝指示 Claude 编辑链接的目标 AGENTS.md
• Windows：如果您或克隆存储库的任何人在 Windows 上工作，请改用 @AGENTS.md 导入。在那里创建符号链接需要管理员权限或开发人员模式，Git 会将提交的符号链接检出为纯文本文件，除非启用了 core.symlinks，这会使该克隆具有一行 CLAUDE.md 代替您的说明

​

从其他工具迁移说明

• .cursor/rules/ 或 .cursorrules 中的 Cursor 规则
• .github/copilot-instructions.md 中的 Copilot 规则
• 设置 CLAUDE_CODE_NEW_INIT=1 时：AGENTS.md、.devin/rules/、.windsurf/rules/ 或 .windsurfrules，以及 .clinerules

​

自动记忆

• user：你的角色、专业知识和工作偏好
• feedback：你给 Claude 的更正和你确认的方法
• project：正在进行的工作、截止日期和 Claude 无法从代码或 git 历史推导的决策
• reference：在项目外查找信息的位置，例如问题跟踪器或仪表板

​

启用或禁用自动记忆

• 后台会话
• 由另一个 Claude Code 会话启动的会话，例如 Claude 通过其 Bash 工具运行 claude 时

{
  "autoMemoryEnabled": false
}

​

存储位置

{
  "autoMemoryDirectory": "~/my-custom-memory-dir"
}

~/.claude/projects/<project>/memory/
├── MEMORY.md           # Index, one line per memory, loaded into every session
├── user_role.md        # One memory
├── feedback_testing.md # One memory
└── ...                 # Any other topic files Claude creates

​

它如何工作

​

审计和编辑你的记忆

​

使用 /memory 查看和编辑

​

故障排除记忆问题

​

Claude 不遵循我的 CLAUDE.md

• 运行 /context 并检查 Memory files 下的列表，以验证应在启动时加载的 CLAUDE.md 和 CLAUDE.local.md 文件。如果其中某个文件不在列表中，Claude 就看不到它。使用 /memory 打开和编辑文件。
• 如果出现 Instruction file not loaded 提示，请参阅其含义及处理方法。
• 工作目录的子目录中的 CLAUDE.md 不会出现在 Memory files 下，因为它是按需加载而不是在启动时加载的。加载时，终端中会出现一行带有其路径的 Loaded。要测试新建的此类文件，请从 shell 中创建它，而不是让 Claude 编写它，然后让 Claude 读取该子目录中的某个文件。
• 检查相关 CLAUDE.md 是否在为您的会话加载的位置（参见 选择 CLAUDE.md 文件的位置）。
• 使指令更具体。“使用 2 空格缩进”比”格式化代码很好”效果更好。
• 查找跨 CLAUDE.md 文件的冲突指令。如果两个文件为相同行为提供不同的指导，Claude 可能会任意选择一个。
• 检查您的指令是否与 Claude Code 自身添加的指导相竞争。如果您的 CLAUDE.md 设置了提交或 Pull Request 规则，请使用 includeGitInstructions 关闭内置规则，并使用 attribution 设置归属文本。

​

我的 AGENTS.md 未加载

1. 在您的工作目录或其上方的任何目录中查找 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md，除了您的 ~/.claude/CLAUDE.md。如果找到一个，Claude 会读取它而不是 AGENTS.md，除非您将 Project instructions 设置为 claude-md-and-agents-md。
2. 运行 claude --version 并确认 v2.1.277 或更高版本。在 v2.1.281 之前，某些会话，例如 Amazon Bedrock 上的会话或禁用遥测的会话，也无法加载 AGENTS.md，因此在这些版本上请更新到 v2.1.281 或更高版本。
3. 在会话中输入 /config 以打开设置面板，并确认 Project instructions 未设置为 claude-md 或 managed-only。如果根本看不到该设置，则您的会话属于无法加载 AGENTS.md 的会话。

​

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

​

我的 CLAUDE.md 太大了

​

Claude 忽略了我的子目录 CLAUDE.md 的末尾部分

1. 确认该限制适用于您的文件。该限制适用于以下按需加载的文件：
   • 您启动 Claude Code 所在目录的子目录中的 CLAUDE.md 和 CLAUDE.local.md，以及它们通过 @path 导入的文件
   • 子目录的 .claude/rules/ 中的规则文件
   • 项目的 .claude/rules/ 或 ~/.claude/rules/ 中的路径范围规则
2. 根据您会话的上下文窗口找到对应的限制：
   • 200K 上下文窗口：40,000 个字符
   • 1M 上下文窗口：Claude Opus 4.6 和 Claude Sonnet 4.6 上为 200,000 个字符，更新的模型上为 150,000 个字符
3. 在 Bash 或 Zsh 中，运行 wc -m path/to/CLAUDE.md 以输出文件的字符数。
4. 将字符数与您的限制进行比较：
   • 超过限制：精简文件，或将其中一部分移到一个或多个规则文件中，每个规则文件会单独计算是否超过限制
   • 未超过限制：在 Claude 不遵循我的 CLAUDE.md 中查找其他原因

​

在 /compact 后指令似乎丢失了

​

相关资源

• 调试你的配置：诊断为什么 CLAUDE.md 或设置未生效
• Skills：打包按需加载的可重复工作流
• Settings：使用设置文件配置 Claude Code 行为
• Subagent 记忆：让 subagents 维护自己的自动记忆