1. 从“失忆”到“过目不忘”：Claude Code 记忆问题的本质

如果你和我一样，每天都在和 Claude Code 打交道，那你肯定经历过这种抓狂时刻：昨天刚教会它项目里某个特定文件夹的代码规范，今天打开一个新文件，它又像个“金鱼”一样，把一切都忘得一干二净，开始用默认的通用风格来建议。或者，你精心调教了它处理某个复杂业务逻辑的“套路”，结果换了个聊天窗口，它又得从头学起。这种“每次启动都要从头教一遍”的体验，极大地消耗了开发者的耐心，也让这个本该成为“智能副驾”的工具，变成了一个需要反复培训的“实习生”。

问题的根源，在于 Claude Code 默认的“记忆”机制设计。为了确保安全、避免隐私泄露和不同项目间的信息污染，Claude Code 在默认情况下采用了严格的“会话隔离”和“上下文窗口限制”。简单来说，你可以把它想象成一个每次见面都清空大脑的助手。每一次你打开编辑器、新建一个聊天，甚至只是切换了一下对话标签，它都从一个“干净”的状态开始。它不知道你上一个小时在做什么项目，也不知道你昨天为这个项目定下的那些特殊规则。

这种设计有其合理性，尤其是在处理敏感代码或多项目并行时，能防止 A 项目的业务逻辑建议“窜”到 B 项目里去。但对于我们开发者而言，这带来了巨大的重复劳动成本。我们真正需要的，是一个能记住“我”的习惯、“这个项目”的规范、“这类任务”的最佳实践的智能伙伴。好消息是，Claude Code 其实预留了让我们实现这一目标的“后门”，而开启它的钥匙，往往只需要两行简单的配置。

网络上流传的“两行配置”说法，其核心就是通过创建并配置一个特殊的指导文件——通常是 CLAUDE.md 或 .cursorrules ——来为 Claude Code 建立一个持久化的、项目级的“记忆体”。这个文件就像是你给助手的一份长期工作手册，每次它“醒来”（启动或进入项目），都会先阅读这份手册，从而继承你所有的设定和习惯。接下来，我将带你彻底弄懂这套机制，并分享如何通过精准配置，让你的 Claude Code 真正变得“过目不忘”。

2. 记忆的载体：深入理解 CLAUDE.md 与 .cursorrules

要让 Claude Code 记住东西，我们首先得知道它把“记忆”存在哪里，以及如何读取。这里有两个核心概念文件： CLAUDE.md 和 .cursorrules 。它们的功能有重叠，但定位和用法有微妙区别，用对了才能事半功倍。

2.1 CLAUDE.md：你的项目级“宪法”

CLAUDE.md 文件是 Claude Code 识别并自动读取的全局配置文件。你可以把它理解为整个项目的“宪法”或“总纲”。当 Claude Code 被激活在一个包含 CLAUDE.md 文件的项目根目录（或上级目录）时，它会自动加载这个文件的内容，并将其作为本次会话的“前置知识”或“系统指令”。

它的核心工作方式如下：

1. 自动加载 ：无需任何额外命令，Claude Code 在初始化时会扫描当前工作区，寻找 CLAUDE.md 。
2. 上下文注入 ：文件的内容会被悄悄地“注入”到你和 Claude 对话的上下文最前端。这意味着，你虽然看不见，但 Claude 的“大脑”里已经预先装入了这份指南。
3. 持久生效 ：只要文件存在，每次新建会话、重启编辑器，这份指南都会生效，实现了“记忆”的持久化。

那么， CLAUDE.md 里应该写什么？ 它的内容应该是高层次的、项目全局的指导原则。例如：

• 项目架构说明 ：这是一个微服务项目，前端是 React + TypeScript，后端是 Go + Gin，它们通过 gRPC 通信。
• 代码风格规范 ：本项目使用 ESLint 的 airbnb 规则集，所有函数必须用 JSDoc 注释，缩进是 2 个空格。
• 目录结构约定 ： /src/api/ 下存放所有接口定义， /src/utils/ 下是公共工具函数， /tests/ 目录结构与 src/ 对应。
• 特定技术栈要求 ：使用 axios 进行 HTTP 请求，错误处理必须使用项目中定义的 ErrorBoundary 组件包裹。
• 禁忌与警告 ：绝对不允许直接使用 any 类型，禁止提交 console.log 调试代码。

一个简单的 CLAUDE.md 示例可能是这样的：

# 项目开发指南

## 项目概述
这是一个使用 Next.js 14 (App Router) 和 Tailwind CSS 构建的全栈博客系统。数据库使用 PostgreSQL，ORM 使用 Prisma。

## 代码规范
- **语言**：TypeScript，严格模式 (`strict: true`)。
- **命名**：变量和函数使用 camelCase，组件使用 PascalCase。
- **样式**：全部使用 Tailwind CSS 工具类，禁止编写独立的 `.css` 文件。
- **API 路由**：位于 `/app/api/` 下，所有 handler 必须包含 try-catch 错误处理，并返回标准的 `ApiResponse` 格式。
- **组件**：所有 React 组件必须是 Server Component，除非明确需要交互性（使用 `‘use client‘` 指令）。

## 常用命令
- 安装依赖：`pnpm install`
- 开发模式：`pnpm dev`
- 数据库迁移：`pnpm prisma migrate dev`
- 构建：`pnpm build`

## 注意事项
- 不要建议使用已弃用的 API（如 Pages Router 的 `getServerSideProps`）。
- 生成 Prisma 模型时，请参考现有模型的字段命名风格（如 `createdAt`, `updatedAt`）。

有了这个文件，Claude Code 在为你生成 API 路由代码时，就会自动采用 Prisma 和标准错误处理格式；建议组件时，也会优先考虑 Server Component。它“记住”了你的项目基调。

2.2 .cursorrules：更精细的会话级“操作手册”

如果说 CLAUDE.md 是宪法，那么 .cursorrules 就更像是一份针对特定场景或目录的“操作手册”或“工作流脚本”。它最初是为 Cursor 编辑器设计的，但许多规则同样能被 Claude Code 识别和利用，尤其在控制 AI 行为模式上更为精细。

它与 CLAUDE.md 的关键区别在于：

1. 作用域更灵活 ：它可以放在项目根目录，也可以放在子目录中，仅对该目录下的文件生效。这实现了“记忆”的模块化。
2. 指令更“底层” ：它包含的指令可能更具体，更偏向于控制 AI 的“思考过程”和“输出行为”。例如，可以指定代码生成的步骤、要求 AI 先解释再写代码、或者对某些类型的修改提出警告。
3. 格式可能更结构化 ：虽然也是 Markdown，但 .cursorrules 的某些社区约定格式可能包含更明确的指令块。

.cursorrules 的典型应用场景：

• 在 /tests/ 目录下 ：定义规则，要求生成的测试用例必须包含边界测试和模拟（mock）示例。
• 在 /docs/ 目录下 ：要求生成的文档必须遵循特定的模板，并自动添加到目录索引中。
• 针对代码重构 ：设定规则，要求 AI 在修改函数时，必须同时更新相关的单元测试。

示例：一个用于测试目录的 .cursorrules

# 测试文件生成规则

当在此目录或子目录中操作时，请遵循以下规则：

1. **框架**：使用 Jest 和 React Testing Library。
2. **结构**：每个测试文件应以描述被测模块的 `describe` 块开始。
3. **覆盖**：每个主要的导出函数/组件至少应有一个对应的 `it` 测试块。
4. **模拟**：当遇到外部 API 调用（使用 `axios`）时，请建议使用 `jest.mock(‘axios‘)` 并进行示例。
5. **断言**：优先使用 `expect(screen.getByRole(...))` 而非 `getByText`。

**工作流**：
当我要求为某个组件生成测试时，请先列出你计划测试的用例清单，经我确认后再生成代码。

这个文件让 Claude Code 在 tests/ 目录下“记忆”了你的测试哲学，无需每次重复强调。

如何选择？

• 新手或求简单 ：优先使用 CLAUDE.md 。它在项目级全局生效，设置简单，是解决“从头教”问题最直接的手段。
• 多项目维护或需要精细控制 ：结合使用。在根目录用 CLAUDE.md 定义全局规则，在特定子目录用 .cursorrules 定义特殊规则。这类似于配置管理中的“全局配置”加“局部覆盖”。

注意 ：关于“记忆乱窜”问题，这正是这些配置文件要解决的核心。通过将记忆绑定到项目目录下的具体文件，从物理上隔离了不同项目的上下文。工作区 A 的 CLAUDE.md 不会影响工作区 B，从而保证了记忆的独立性和准确性。

3. 实战：两行配置打造个性化智能工作流

理解了记忆载体，我们现在来实战如何用最少的配置，实现最大的效果。所谓“两行配置”是一个形象的说法，核心在于创建并正确编写上述的指导文件。让我们一步步来。

3.1 基础配置：创建你的 CLAUDE.md

这是最通用、最有效的一步，适用于几乎所有场景。

1. 在项目根目录创建文件 ： 打开你的项目（无论是 VS Code 还是 Cursor），在资源管理器的顶层，右键新建一个文件，命名为 CLAUDE.md （注意全大写和扩展名）。

2. 编写核心记忆内容 ： 打开 CLAUDE.md ，开始写入你想让 Claude Code 记住的东西。内容组织建议采用以下结构，这并非强制，但清晰的结构能让 AI 更好地理解：

   • 项目简介 ：用一两句话说明这是什么项目。
   • 技术栈 ：明确列出主要语言、框架、库和版本。
   • 代码风格与规范 ：这是重中之重。包括命名约定、缩进、注释要求、文件组织方式等。
   • 架构与模式 ：如使用的设计模式、状态管理方案、API 设计风格（RESTful/GraphQL）。
   • 开发命令 ：如何启动、构建、测试、部署。
   • 禁忌与最佳实践 ：明确禁止什么，鼓励什么。

3. 一个立竿见影的示例 ： 假设你受够了 Claude Code 总是用双引号，而你的项目强制使用单引号。你的 CLAUDE.md 可以精简到只有一行：

   在本项目中，所有 JavaScript/TypeScript 代码必须使用单引号 (‘)，JSX 属性使用双引号 (“)。
   

   保存文件。现在，无论你在项目的哪个文件里让 Claude Code 生成或修改代码，它都会自动遵循单引号规则。这就是“记忆”生效了。

3.2 进阶配置：利用 .cursorrules 实现场景化记忆

当你需要更精细的控制时， .cursorrules 就派上用场了。

1. 创建规则文件 ： 在需要特殊规则的目录下（如项目根目录、 /src/components/ 、 /tests/ ），创建名为 .cursorrules 的文件。

2. 编写场景化指令 ： 这里的指令可以更具体、更流程化。例如，在组件目录下，你可以这样写：

   # 组件开发规则
   
   ## 组件类型
   所有 React 组件默认应为函数式组件，并使用 `export default`。
   
   ## 状态管理
   - 简单的局部状态使用 `useState`。
   - 涉及复杂逻辑或跨组件状态，请优先建议使用 `Zustand`，并引用项目中现有的 store 模式。
   
   ## 样式方案
   组件样式必须使用 `Styled-Components`，样式对象应定义在组件文件底部，并遵循 `Styled[ComponentName]` 的命名约定。
   
   ## 交互要求
   当我要求“添加一个按钮”时，请同时提供点击事件的示例处理函数（例如，发起一个模拟的 API 调用并更新状态）。
   

   这样，当你在该目录下开发组件时，Claude Code 会自动套用这些“记忆”中的模式。

3.3 配置的生效与验证

创建并保存文件后，通常需要一点“触发”动作来让 Claude Code 重新加载上下文：

• 重启 Claude Code 插件/编辑器 ：最彻底的方式。
• 切换一下当前打开的标签页 ：有时也能触发重新读取。
• 新建一个聊天会话 ：在新的聊天中，配置通常会生效。

如何验证配置生效？ 你可以做一个简单的测试：在配置了使用单引号的 CLAUDE.md 的项目中，打开一个 JS 文件，对 Claude Code 说：“写一个简单的求和函数。” 观察它生成的代码是否使用了单引号。如果没有，检查文件是否在正确位置，并尝试重启编辑器。

4. 避坑指南：为什么你的“记忆”可能失效或混乱？

即使配置了文件，你可能还是会遇到记忆不灵、规则冲突或者行为怪异的情况。别急，这通常是以下几个原因造成的，理解了就能轻松排查。

4.1 文件位置与优先级冲突

这是最常见的问题。Claude Code 在读取配置文件时，可能会遵循一定的查找路径和优先级。

• 问题 ：你在子目录 /src/utils/ 下也放了一个 CLAUDE.md ，里面写了些工具函数的特殊规则，但发现根目录的规则好像被覆盖或忽略了。
• 排查与解决 ：
  1. 确认查找顺序 ：目前，Claude Code 通常从当前打开文件所在目录开始，向上级目录查找，直到找到第一个 CLAUDE.md 或 .cursorrules 为止。这意味着子目录的规则 可能 会覆盖根目录的规则（取决于具体实现）。最安全的做法是，将 全局通用规则 只放在 项目根目录 的一个 CLAUDE.md 中。
  2. 避免规则冲突 ：如果根目录要求“用 Redux”，子目录要求“用 Zustand”，AI 可能会困惑。确保不同层级的规则是互补而非矛盾的。子目录规则应是对根目录规则的 细化或补充 ，而非推翻。
  3. 使用 .cursorrules 进行局部覆盖 ：对于需要特殊规则的子模块，更推荐使用 .cursorrules ，因为它的设计初衷就是用于局部控制，语义上更清晰。

4.2 指令过于模糊或矛盾

AI 理解自然语言，但模糊的指令会导致不可预测的结果。

• 问题 ：你的 CLAUDE.md 里写着“代码要整洁高效”。这太主观了，Claude 无法形成稳定“记忆”。
• 解决 ：将指令具体化、可操作化。
  • 差 ：“写好点的错误处理。”
  • 优 ：“所有异步函数（如 API 调用）必须使用 try-catch 包裹，并在 catch 块中调用 logError(error) 函数，然后向上抛出统一的 AppError 类型错误。”
  • 差 ：“组件要复用。”
  • 优 ：“当发现相似代码段出现超过3次时，应建议将其抽取为独立工具函数，并放置在 /src/shared/utils/ 目录下。”

4.3 上下文窗口的天然限制

这是硬性约束。无论是 CLAUDE.md 还是 .cursorrules ，其内容都会占用宝贵的上下文窗口（Token 数）。如果文件写得过于冗长，可能会挤占后续对话中代码和问题的空间，导致 AI“忘记”更早的对话内容，甚至无法完整读取你的长篇配置。

• 策略 ：
  1. 精简 ：只写最重要的、最高频的规则。去掉废话。
  2. 结构化 ：使用清晰的标题和列表，帮助 AI 快速抓取关键信息。
  3. 分而治之 ：对于超大型项目，考虑拆分。用根目录的 CLAUDE.md 定义核心原则，然后用指向更详细文档的链接作为补充（例如，“代码风格详情请见 /docs/code-style.md ”）。虽然 AI 可能不会主动去读链接，但这给了你一个手动引用的途径。

4.4 不同 AI 工具间的配置干扰

这也是一个常见痛点。你同时在使用 Cursor、Claude Code 甚至其他插件的 AI 功能，它们可能都支持类似 .cursorrules 或 CLAUDE.md 的配置，但解析方式略有不同。

• 问题 ：为 Cursor 优化的 .cursorrules 在 Claude Code 中表现异常。
• 解决 ：
  1. 隔离配置 ：最干净的方法是为不同工具使用不同的配置文件名。例如，Claude Code 专用 CLAUDE.md ，Cursor 专用 .cursorrules 。这样互不干扰。
  2. 编写兼容内容 ：如果希望一个文件被多个工具识别，则尽量使用最通用、最标准的 Markdown 语法书写指令，避免使用某个工具特有的指令格式。优先陈述“要做什么”，而非“如何指挥 AI 去做”。
  3. 理解工具差异 ：Cursor 的 .cursorrules 可能包含一些控制其自身编辑器行为的指令（如自动导入），这些在 Claude Code 中会被忽略。专注于编写那些关于代码本身（风格、架构、模式）的规则，这些规则通常具有较好的跨工具可移植性。

5. 高阶技巧：让记忆更智能、更强大

基础配置解决了“记住”的问题，而高阶技巧能解决“记好”和“活用”的问题。

5.1 动态记忆：通过注释进行实时微调

CLAUDE.md 是静态的、项目级的记忆。但有时，我们需要在单个文件或一段代码上进行临时的、特定的指导。这时，可以使用代码注释。

• 方法 ：在代码文件中，添加特定的注释来给 Claude Code 下达指令。这些指令只对当前文件或紧随其后的代码块生效。
• 示例 ：

  // CLAUDE: 这个组件需要使用 React 18 的 `useId` 来生成唯一的表单 ID。
  // CLAUDE: 请使用我们内部的 `formatCurrency` 函数来格式化价格，不要手动处理。
  

  当 Claude Code 读到这些注释时，它会优先遵循这些即时、具体的指令。这相当于在全局记忆的基础上，增加了短期工作记忆，非常灵活。

5.2 模块化记忆：为不同工程类型创建配置模板

如果你经常创建类似的项目（比如多个前端 React 项目，或多个后端 Node.js 微服务），为每种类型创建一个配置模板会极大提升效率。

• 做法 ：
  1. 在你的电脑上建立一个“配置模板”文件夹。
  2. 在里面创建 react-project-CLAUDE.md 、 node-api-CLAUDE.md 、 python-data-CLAUDE.md 等文件。
  3. 每个文件里写好对应技术栈的完整、详尽的规则。
• 使用 ：当启动一个新项目时，直接将对应的模板文件复制到项目根目录，重命名为 CLAUDE.md ，然后根据项目特点稍作修改即可。这样，新项目从一开始就拥有了成熟的“记忆”，无需从头编写。

5.3 记忆的版本化与共享

既然 CLAUDE.md 和 .cursorrules 是项目文件，那么它们就应该被纳入版本控制系统（如 Git）。

• 好处 ：
  1. 团队协作 ：确保团队每个成员使用的 Claude Code 都遵循同一套项目规范，极大统一代码风格，减少评审成本。
  2. 历史追溯 ：当项目规范迭代时（比如从 RESTful 切换到 GraphQL），可以通过 Git 历史查看配置的变更记录。
  3. 项目入门 ：新成员克隆代码后，无需口头传授大量规范，AI 助手已经通过配置文件成为了他的“入职导师”。
• 注意 ：如果配置中包含敏感信息（如内部服务器地址、密钥命名示例），记得使用 .gitignore 将其忽略，或使用环境变量占位符。

5.4 结合 Skills 功能实现技能记忆

Claude Code 的 “Skills” 功能允许你创建可重用的自定义指令块。你可以将一些复杂的、但非项目特定的“记忆”封装成 Skill。

• 例如 ，你可以创建一个名为“生成 JSDoc 注释”的 Skill，内容为：

  请为以下函数/方法生成完整的 JSDoc 风格注释，包括对每个参数的描述、返回值描述，以及可能的错误抛出说明。
  

• 用法 ：在任意项目中，当你需要这个功能时，手动激活这个 Skill。这相当于一个可随身携带的“技能记忆”，它不依赖于项目配置文件，而是依赖于你的个人账户或本地设置。

通过将静态的 CLAUDE.md 、动态的代码注释、可复用的 Skills 以及可能存在的其他工具配置结合起来，你就能为 Claude Code 搭建一个立体、多层次、既稳定又灵活的记忆系统，让它真正成为一个深度理解你和你的项目需求的智能伙伴。